開発方針を相談する

AI に強いコードベースの作り方

AI が迷わないコードベースは、人間にも保守しやすい。

この記事の結論

「自社のコードベース、AI が読みづらいみたいで、生成精度が低くて」

CTO や開発責任者からよく届く相談です。AI コーディングツール (Cursor / Claude Code / Codex) を入れたものの、出てくるコードが既存スタイルとズレている、関連ファイルを見落としている、というケースです。

Anthropic の Claude Code 解説でも、コードベースを traverseするときに ハーネス全体 (CLAUDE.md、hooks、skills、plugins、MCP servers) が成果を左右する、と整理されています (Claude Code docs / Anthropic)。AI に強いコードベースの整備は、ハーネスを整える作業です。

この記事では、AI に強いコードベースの特徴と、既存コードベースを改善する手順を整理します。

AI が迷うコードベースの特徴

実際に AI コーディングで迷いが多いコードベースの特徴:

1. ディレクトリの責務が不明確

src/utils/ に何でも入っていて、何があるか分からない。

2. 命名が一貫していない

同じ概念を、ファイルごとに違う名前で呼んでいる (User, Customer, Member など)。

3. 共通ロジックが散らばっている

集計、認証、バリデーションが、複数の場所で独立に実装されている。

4. テストがない、または部分的

「動いている」の確認手段がないので、AI が変更してよいか分からない。

5. ドキュメントが古い

README に書かれていることと、実装が乖離している。

6. 触ってはいけない領域が明示されていない

マイグレーション、課金、認証など、慎重に扱うべき領域が普通の場所に置かれている。

これらは AI だけでなく、人間の新規メンバーも同じく迷う 構造です。

AI に強い構造とは

1. ディレクトリ構成が責務を表現

src/
  app/           # ルーティング
  lib/
    domain/      # ドメインロジック (純粋関数)
    db/          # データアクセス
    auth/        # 認証ラッパー
    integrations/# 外部 SaaS 連携
  components/    # UI コンポーネント

各ディレクトリの責務が、構造から読み取れる状態にします。

2. 命名の一貫性

3. 共通ロジックの集約

4. テストの存在

詳しくは AI でコード生成するなら、先にテストとレビューを整備すべき理由 で展開しています。

ここまでで「自社のコードベースを AI フレンドリーに整えたい」と感じたら、診断から相談するのが現実的です。

AI-ready コードベース診断を相談する →

ドキュメントとテストの整備

必要なドキュメント

テストの整備順序

CLAUDE.md / AGENTS.md の活用

最も効果が高い投資は、プロジェクト文脈ファイル の整備です。

Anthropic の CLAUDE.md は system prompt に自動的に含まれる 設計 (Using CLAUDE.md files / Anthropic)。OpenAI の AGENTS.md は 作業前に Codex が読む プロジェクト固有指示 (Custom instructions with AGENTS.md / OpenAI Developers)。

書くべき項目

詳しくは CLAUDE.md / AGENTS.md に何を書くべきか で展開しています。

リファクタリング手順

既存コードベースを AI フレンドリーに整える手順:

Step 1: 現状把握 (1〜2 週間)

Step 2: CLAUDE.md / AGENTS.md 作成 (1 週間)

Step 3: 重要ドメインの整理 (2〜4 週間)

Step 4: ADR の蓄積 (継続)

Step 5: 振り返りサイクル

既存コードベースのよくある改善ポイント

実際に AI フレンドリー化で多い改善:

改善ポイント効果
ユーティリティ関数の整理AI が同じ機能を再実装しない
命名の統一AI が正しい名前を使える
テストの追加AI が変更の影響を確認できる
CLAUDE.md / AGENTS.mdAI が文脈を理解できる
ディレクトリの責務明示AI が正しい場所にファイルを置く
触ってはいけない領域の明示AI が事故を起こさない

min's のコードベース整備支援

min's では、AI フレンドリーなコードベース化を以下の流れで支援しています。

Phase 1: 診断 (1〜2 週間)

現状の構造、テスト、ドキュメントの評価。費用 50〜100 万円。

Phase 2: 整備 (4〜12 週間)

CLAUDE.md / AGENTS.md 作成、ディレクトリ整理、テスト追加、ADR 整備。費用 200〜600 万円。

Phase 3: 継続並走

月次のレビューと改善。費用 月 30〜80 万円。

AI-ready コードベース診断を相談したい方へ

min's では、既存コードベースの AI フレンドリー化、CLAUDE.md / AGENTS.md の整備、リファクタリング並走を支援しています。

次に読む記事

参考

動くデモで終わらせず
本番まで持っていく開発を

AI で作りかけたもの、止まりかけている開発、新しいプロダクトの構想。 まずは現状を整理するところから、ご相談ください。

開発方針を相談する概算見積もりを依頼する