なぜAIは同じところで必ずコケるのか

Cursor、Windsurf、Claude Codeで開発してる人なら絶対経験してるはず。AIがコードを吐く→コピペ→ビルドエラー→テスト真っ赤→依存関係が変な場所に。AIの頭が悪いわけじゃない。あなたのプロジェクトの「ローカルルール」を知らないだけ。

AGENTS.mdはプロジェクト直下に置くMarkdownファイルで、AI専用に「ビルド方法」「テスト方法」「コーディング規約」を伝えるもの。README.mdは人間向けで、プロジェクト紹介・コントリビュートガイド・ブランドストーリーが詰まってる。AIがこれを読むと、新人が入社初日に会社パンフレットを渡されて「じゃあコード書いて」と言われるのと同じ状態になる。会社は何やってるか分かるけど、ビルドコマンドも、テストの動かし方も、ESLintのルールも知らない。だから毎回チャットで「pnpmね、npmじゃなくて」「テストはpackages/web下ね」「lint忘れてない？」と訂正し続ける羽目になる。

外注案件だと被害がもっと直接的。Next.js + Prismaの案件をCursorで加速しようとしたら、AIがnpm installで依存を入れてpnpmのworkspace設定を全部破壊。DBスキーマのディレクトリも知らないからmigrationファイルがエラー。クライアントに催促されて、3時間AI生成コードをデバッグするハメに。こんな稼ぎ方は割に合わない。

AIがローカルルールを知らない典型3パターン：① パッケージマネージャーを間違える（pnpm指定なのにAIがnpm installで入れて、workspaceが機能不全）② テストの入口が見つからない（テストがpackages/web下にあるのに、AIがルートでpnpm testを叩いて「テストなし」と怒られる）③ コードスタイルがバラバラ（ESLint + Prettierなのに、AIがインデントもクォートも全部無視してCIが落ちる）。

AGENTS.mdが「人間ドキュメント」と「機械ドキュメント」を切り分ける

GitHubのオープンソースプロジェクトAGENTS.md（リポジトリ：github.com/agentsmd/agents.md、2026-08-25時点で約2.4万star）がこの問題を解決する。仕組みは超シンプル。プロジェクト直下にMarkdownファイルを置いて、AIにビルド・テスト・スタイル規約を伝えるだけ。

READMEの代替じゃなくて補完。READMEは人間のコントリビューター向け、AGENTS.mdはAIエージェント向け。役割がはっきり分かれてて、干渉しない。

ソース記事によると、AGENTS.mdは数万のオープンソースプロジェクトで採用されてる（具体的な数字は要確認）。VS Code、Cursor、Windsurf、Aider、GitHub Copilotなど主要AIコーディングツールが対応済み（確認済み）。さらにコミュニティ報告ではOpenAI Codex、Google Julesなども対応してる模様（⚠️未確認）。今学ばないと、AIに方言で話しかけ続けることになる。

ルート1：最小構成のAGENTS.mdを手書きする

コストはほぼゼロ。新規ファイル作って、3セクション書けば動く。

前提知識：以下の例ではpnpm（npmより省ディスク、monorepo workspace対応）を使用。turboはmonorepoのタスクオーケストレーター、--filterで特定のパッケージだけ実行してリポジトリ全体への影響を避ける。

セクション1「Dev environment tips」：パッケージマネージャー、サブパッケージへの移動、新規モジュールの作成方法を伝える。公式サンプル：

• pnpm dlx turbo run where <project_name> —— 該当サブパッケージのディレクトリに直行。lsで掘り返す必要なし
• pnpm install --filter <project_name> —— 特定サブパッケージの依存だけインストール。monorepo全体は触らない
• pnpm create vite@latest <project_name> -- --template react-ts —— TypeScriptチェック付きのReact + Viteサブパッケージを新規作成

こういうコマンドはAIには推測できない。でも書いておけば素直に実行する。

セクション2「Testing instructions」：テストの実行方法、CIプラン、コミット前必須チェックを伝える。公式サンプル：

• pnpm turbo run test --filter <project_name> —— 該当サブパッケージの全チェック実行
• pnpm vitest run -t "<test name>" —— 名前一致の単体テストだけ実行
• 「Fix any test or type errors until the whole suite is green」 —— 全グリーンになるまで止めない
• 「Add or update tests for the code you change, even if nobody asked」 —— ここが最重要。書かないとAIはテストをサボる

セクション3「PR instructions」：コミットタイトル形式、lintとtestの強制実行。公式サンプルはTitle format: [<project_name>] <Title>と「Always run pnpm lint and pnpm test before committing」。

この3セクションで50行未満。でもAI生成コードの一次通過率が体感で劇的に上がる（コミュニティ報告、具体的数字は要確認）。

ルート2：大規模monorepoでネスト運用する

企業案件でmonorepo構造（フロント・バック・共有コードなど複数プロジェクトを単一Gitリポジトリで管理）の場合、AGENTS.mdは1ファイルじゃ足りない。AGENTS.mdはネスト対応で、各サブディレクトリに専用ファイルを置ける。AIは自動的に「一番近いファイル」を読み込む。

実作業：ルートのAGENTS.mdに全体規約（パッケージマネージャー、CIフロー、セキュリティ注意事項）を書く。次にpackages/web/、packages/api/、packages/shared/にそれぞれ専用ファイルを置いて、そのサブパッケージ固有のビルドコマンド・テスト入口・特殊依存を記載。例えばフロントパッケージなら「UIはshadcn、スタイルはTailwind、アイコンはlucide-react」、バックエンドパッケージなら「DBマイグレーションはPrisma、APIルートはsrc/routes配下、認証はJWT」。

AIがサブディレクトリで作業するとき、自動的に最も近いAGENTS.mdを読み込んで、ルートより優先する。つまり同じプロジェクト内で、フロント用AIアシスタントとバックエンド用AIアシスタントが完全に異なる指示を受け取れる。混線しない。

ルート3：外注の差別化ポイントにする

AI外注市場はもうレッドオーシャン。全員がCursor使えるけど、納品品質はピンキリ。提案書に「本プロジェクトはAGENTS.md標準ドキュメントを設定済み、AI補助開発はプロジェクト規約に準拠」と1行書けるだけで、「AIでコード書きます」しか言えない競合より受注率が体感で跳ね上がる。

具体打法：案件受注後、まず30分でクライアントのプロジェクト構造を読み込んで、カスタマイズ版AGENTS.mdを作成。このドキュメント自体が成果物の一部になる。クライアントは将来AIでコード保守するときも楽になる。

AGENTS.md設定サービスを単体で価格設定（地域相場に応じて調整）：ベーシック版 7,000円（単一ファイル設定 + README説明付き）、エンタープライズ版 42,000円（monorepoネスト + セキュリティ規約 + チーム研修）。成果物：① カスタマイズAGENTS.mdファイル ② 30日チャットサポート ③ 10分の録画研修。対象：Cursor/Windsurf会員だけど使いこなせてないクライアント。対象外：まだ完全手動開発でAIツール未導入のクライアント。

事例：AGENTS.mdの互換性という堀

AGENTS.mdはMITライセンス（素材で確認）、コミュニティ運営（ガバナンス詳細は要確認）、公式サイトはagents.md。

最大の堀は互換性：VS Code、Cursor、Windsurf、Aider、GitHub CopilotがAGENTS.md読み込みに対応済み（確認済み）。コミュニティ報告ではOpenAI Codex、Claude Code、Gemini CLI、Google Julesなども対応してる模様（⚠️未確認）。つまり1ファイル書けば、主要AIアシスタント全部で使える。ツールごとに設定を書く必要なし。

他方案と比較：Cursorの.cursorrulesはCursor専用でWindsurfに切り替えると無効化。Claude CodeのCLAUDE.mdはClaude専用。GitHub Copilotの指示システムも別物。AGENTS.mdの「一度書けばどこでも動く」特性が、短期間で広く採用された根本理由。

ツール移行コストがゼロ。今日Cursor使っても、明日Windsurfに切り替えても、AGENTS.mdはそのまま再利用できる。ルール書き直し不要。

今夜のアクション：プロジェクトに機械マニュアルを置く

5分アクションリスト：① プロジェクトのルートディレクトリを開く ② AGENTS.mdを新規作成 ③ 公式テンプレート（github.com/agentsmd/agents.md）をコピー ④ ビルド・テスト・lintの3コマンドを記入 ⑤ 次回AIにコード書かせるときの効果を観察。

monorepo使ってるなら、今夜さらに20分使って各サブパッケージにネスト設定を追加。明日仕事始めるとき、AI生成コードの訂正作業が激減してるのが分かるはず。

AGENTS.mdは現時点でROI最強のAIコーディング設定。30分の投資で、毎月数時間のデバッグ時間を回収できる。