AIがナビゲートできるようにプロジェクトを構造化する

AIモデルはコードを読むことであなたのコードを推論する。散らかって、肥大化し、一貫性のないプロジェクトは、あなたにとってと同じく彼らにとっても扱いにくい。完璧なアーキテクチャは必要ないが、いくつかの習慣はすぐに報われる。

• 予測可能なレイアウトを保つ。 ソースは一箇所に、テストはソースの隣か鏡像の位置に、設定はルートに。
• 明確で説明的な名前を使う。 calculateMonthlyInvoiceTotal は calc2 に勝る。AIは名前を手がかりとして使う。
• 小さいファイルを好む。 200行のファイルは、あなたにとってもAIにとっても、2,000行のものより正しく変更しやすい。
• 関連するものをまとめて配置する。 ある機能のコード、スタイル、テストが一緒にあれば、AIは一度の読み込みでコンテキストを集められる。
• 明確なエントリポイントを保つ。 アプリが始まる明白な一箇所は、AIがプロジェクトを把握するときに手繰る糸口を与える。

典型的でAIに優しいレイアウトはこんな感じだろう。

my-app/
├── AGENTS.md            # AI用のプロジェクト規則 & コンテキスト
├── README.md            # プロジェクト概要、実行方法
├── .env.example         # 必要なシークレットを記載 (実値なし)
├── .gitignore           # .env, ビルド成果物, node_modules を除外
├── package.json         # スクリプト: dev, test, lint, build
├── src/
│   ├── features/
│   │   └── invoices/    # 1機能のコード + テスト、一緒に
│   ├── lib/             # 共有ヘルパー
│   └── index.ts         # エントリポイント
└── tests/               # 横断 / 統合テスト

その見返りは複利で膨らむ。プロジェクトがAIにとってナビゲートしやすいほど、AIの変更は小さく外科的になる。よく整理されたリポは、AIが三十個を引っ掻き回して推測する代わりに、関連する三つのファイルだけに触れさせる——つまり、より小さい差分、より少ない事故、そしてあなたが実際に読めるレビューになる。AIが広範で焦点の定まらない編集をしているのを見つけたら、真犯人はプロンプトではなく構造であることが多い。