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

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

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

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

my-app/
├── AGENTS.md            # project rules & context for the AI
├── README.md            # what the project is, how to run it
├── .env.example         # documents needed secrets (no real values)
├── .gitignore           # excludes .env, build output, node_modules
├── package.json         # scripts: dev, test, lint, build
├── src/
│   ├── features/
│   │   └── invoices/    # code + tests for one feature, together
│   ├── lib/             # shared helpers
│   └── index.ts         # entry point
└── tests/               # cross-cutting / integration tests

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