AIエージェントが迷わないコードベースの設計原則

AIコーディングエージェントの性能は、プロンプトの書き方よりもリポジトリの構造に左右される。これはCursorやClaude Codeを使った実装検証で繰り返し確認されている事実で、200コンポーネントを持つデザインシステムを渡せば、エージェントが単体で管理画面を1行も手書きせずに構築できる。ただしその前提は「エージェントが読めるコードベース」であることだ。

業務システムの開発では、長年の機能追加によってファイルが膨れ上がり、1ファイルに4000行を超えるコードが集中するケースは珍しくない。こうした「フラットなファイル構造」のリポジトリにAIエージェントを投入しても、エージェントはコード全体を毎回再解析しなければならない。結果として生成精度が落ち、変更のたびに広範囲の再生成が発生する。

モジュール境界がエージェントの「地図」になる

エージェントがコードを読む動作は、新しいメンバーがリポジトリを調べる動作に近い。関心ごとがフォルダ単位で分離されていれば、エージェントは目的のファイルを素早く特定できる。逆に全てが `app/page.tsx` に集まっていると、エージェントはファイル全体を文脈として保持し続ける必要が生じる。

有効な構成の一例を示す。

src/
  components/
    Button/
      Button.tsx
      Button.test.tsx
      index.ts
    Card/
      Card.tsx
      index.ts
  lib/
    auth.ts
    billing.ts
  routes/
    dashboard.tsx
    settings.tsx

1フォルダが1つの関心事を担い、バレルエクスポート（`index.ts` から外部向けの公開APIをまとめてエクスポートする仕組み）でインターフェースを整理する。エージェントは `Card/Card.tsx` だけを読めばコンポーネントのプロパティ仕様を把握でき、それ以外のファイルに触れる必要がない。業務システムに置き換えると、ドメインごとにモジュールを切る設計—注文処理・在庫管理・請求—とほぼ同じ発想だ。

型定義がエージェントへの「仕様書」になる

TypeScriptの型（TypeScript固有の型アノテーション機能で、変数や関数の入出力に型制約を与える仕組み）は、エージェントにとって実質的な仕様書として機能する。プロパティの型が `any`（型チェックを無効にするTypeScriptの特殊型）になっていると、エージェントは実装コードを全部読んで意図を推測するしかない。一方で明示的な型とともにコンポーネントが公開されていれば、エージェントはそれをそのまま利用できる。

シード記事が示す設計では、コンポーネントとともにプロパティ型を `export` で外部公開する。たとえば `variant?: 'default' | 'elevated' | 'outlined'` と宣言されていれば、エージェントはバリアントの選択肢を読み取るだけで正しい使い方を導き出せる。これはREST APIのOpenAPI仕様書（APIの入出力スキーマを機械可読な形式で記述する仕様）と同じ役割を果たしていると考えると理解しやすい。仕様書がなければクライアントは実装を読むしかなく、型定義のないコードはそれと同じ状態だ。

JavaやKotlinを主体とした業務システムでも考え方は共通する。インターフェースを明示的に定義し、DTOクラス（Data Transfer Objectの略で、レイヤー間のデータ受け渡しに使うクラス）のフィールドにJavadocコメントを付与しておくと、エージェントがコードを生成する際の誤りが減る傾向がある。

コンベンションファイルが「永続的な文脈」になる

CursorというAIエディタは `.cursorrules` というファイルを、Claude Codeというコマンドラインエージェントは `CLAUDE.md` というファイルを、それぞれシステムコンテキスト（AIが毎回参照する固定の指示領域）として自動的に読み込む。これらのファイルに記述した内容は、プロンプトを書くたびに再説明しなくても良い永続的なルールになる。

シード記事では、こうしたファイルに盛り込む内容として以下を挙げている。

使用するコンポーネントライブラリの指定
カラートークン・スペーシングの参照先
サーバーロジックの配置ルール
ファイル分割の粒度（1コンポーネント1ファイル等）
DBアクセスの方式と型付きクエリの場所

READMEとの違いは明確だ。人間はREADMEをざっと読んで必要な部分を抽出できるが、エージェントはルールファイルを読み、それ以外は基本的に無視する。30行のコンベンションファイルが、ドキュメントのないコード3万行を上回るのはこのためだ。既存リポジトリへの導入であれば、まずルールファイルを1つ追加するだけでも効果が出る。

さらにシード記事が提案するのが `ai/prompts/` フォルダへの検証済みプロンプト集の整備だ。「新しいページを追加する」「既存コンポーネントを改修する」といったユースケースごとに、動作確認済みのプロンプトをMarkdownで管理する。スタイルガイドがルールを定義するのに対し、チュートリアルがその動かし方を示すのと同じ関係だ。

これらの設計原則は、AIエージェントの有無にかかわらず保守性の高いコードベースの条件と一致している。エージェントが迷わないコードは、新しいメンバーも迷わないコードだ。型定義・モジュール分離・明示的なコンベンション管理を整備することで、エージェントと人間の双方が並走できる開発環境が実現する。