AI コーディングエージェントを飼い慣らす：最強の「AGENTS.md」の書き方

近年、Gemini、Claude、Aider といった「自律型 AI コーディングエージェント」が開発現場に浸透しつつあります。彼らは指示一つでファイル構成を理解し、コードを書き、テストを実行して修正まで行います。

しかし、エージェントを使い始めた多くのエンジニアが直面するのが、**「AI エージェントの暴走」**です。

• 型定義を面倒くさがって any を連発する
• プロジェクト独自のディレクトリ構造を無視して勝手に utils/ を作る
• vitest --watch などの終了しないコマンドを叩いてフリーズする
• 指示していないリファクタリングを始めて関係ないファイルを壊す

これらの問題を防ぎ、エージェントを「熟練のペアプロ相手」に変える魔法のファイル、それが AGENTS.md です。本記事では、AI エージェントに守らせるべきルールを定義する AGENTS.md の書き方と、その設計思想を徹底解説します。

なぜ AGENTS.md が必要なのか

AI エージェントは、人間が数年かけて培った「プロジェクトの阿吽の呼吸」を知りません。 エージェントに与えられるコンテキスト（ファイル内容や履歴）は有限であり、その中で彼らは「最も確率的に正しそうな推論」を行います。その結果、彼らはしばしば**「最も楽な道（＝技術的負債を生む道）」**を選んでしまいます。

AGENTS.md をプロジェクトのルートに配置する理由は、**「エージェントの推論空間に強制的な制約（ガードレール）を設けるため」**です。

なぜその設計にしたか：外部メモリとしての役割

エージェントは毎回ゼロベースで思考するわけではありませんが、多くのファイルを見すぎることで逆に重要なルールを見失う（ロスト・イン・ザ・ミドル現象）ことがあります。AGENTS.md という明確なルールブックを定義し、エージェントの起動時やタスク開始時に必ず読み込ませることで、思考のブレを最小限に抑えることができます。

AGENTS.md に書くべき内容の 4 つの分類

効果的な AGENTS.md は、以下の 4 つのセクションで構成するのがベストプラティスです。

1. 禁止事項 (Prohibitions): 致命的なエラーや環境のハングを防ぐ
2. 命名規則・コーディング基準 (Standards): コードの品質を一定に保つ
3. アーキテクチャ原則 (Architecture): システムの整合性を維持する
4. テスト・検証方針 (Testing): 修正の正しさを担保する

それぞれのセクションについて、具体的な記述例を見ていきましょう。

1. 禁止事項 (Prohibitions)

エージェントが最もやりがちな「環境破壊」を防ぐための最重要セクションです。

実例コード

## 禁止事項
- **コマンド実行**:
  - `vi`, `nano`, `top` などのインタラクティブなコマンドは実行しない。
  - `npm start`, `vitest --watch` などの終了しないプロセスは背景実行 (`&`) するか、単発実行モードを使用すること。
- **TypeScript**:
  - `any` 型の使用は厳禁。どうしても必要な場合はコメントで理由を明記すること。
- **Git**:
  - ユーザーの明示的な指示なしに `git commit` や `git push` を行わない。

2. 命名規則・コーディング基準 (Standards)

プロジェクトの「見た目」と「一貫性」を守るためのルールです。ここを疎かにすると、エージェントは自分の得意なスタイル（多くの場合、学習データで最も多いスタイル）で書き始めてしまいます。

なぜその設計にしたか：レビューコストの削減

人間が後でコードを読んだときに「あ、ここは AI が書いたな」と分かってしまうような不一致を減らすためです。一貫性のあるコードは、次回の AI による修正の精度も高めます。

実例コード

## 命名規則とスタイル
- **ファイル名**: `kebab-case` を使用する (例: `user-repository.ts`)。
- **React コンポーネント**:
  - 関数コンポーネントのみを使用し、`export const ComponentName: React.FC = ...` の形式で定義する。
  - スタイルは CSS Modules ではなく、同じディレクトリの `styles.css` に記述する。
- **非同期処理**: `callback` は禁止。常に `async/await` を使用すること。

3. アーキテクチャ原則 (Architecture)

エージェントはしばしば、既存のパターンを無視して最短距離で機能を実装しようとします。これを防ぐために、フォルダ構成や依存の方向を明示します。

実例コード

## アーキテクチャ原則
- **ディレクトリ構造**:
  - `packages/core/src/domain`: ビジネスロジックとインターフェースのみ。
  - `packages/core/src/port`: 外部通信のポート定義。
  - `apps/client/src/adapters`: 具体的な実装 (LocalStorage, API Client)。
- **依存ルール**: `domain` は他のどのパッケージにも依存してはならない。
- **モジュール化**: 1 ファイルは原則 200 行以内とする。超える場合は機能単位で分割すること。

4. テスト・検証方針 (Testing)

エージェントに「コードを書いて終わり」にさせないためのルールです。

なぜその設計にしたか：デグレードの防止

自律型エージェントは、A を直して B を壊すことがよくあります。変更のライフサイクル（修正 → 再現テスト作成 → 修正 → 全テストパス）をルール化することで、品質を自動的に担保させます。

実例コード

## テストと検証のワークフロー
1. **バグ修正の場合**:
   - まず、バグが再現する失敗テストコードを作成し、実行して失敗を確認すること。
   - 修正後、そのテストがパスすることを確認すること。
2. **機能追加の場合**:
   - 新規機能に対応するユニットテストを `tests/` ディレクトリに作成すること。
3. **最終確認**:
   - すべての修正が終わったら、必ず `npm run test:all` を実行し、既存機能に影響がないか確認すること。

運用上の注意：AGENTS.md を「腐らせない」ために

せっかく書いた AGENTS.md も、エージェントが読まなければ意味がありません。また、プロジェクトの成長に合わせて更新し続ける必要があります。

1. エージェントのプロンプトに組み込む

エージェントを起動する際のエイリアスや設定ファイルに、AGENTS.md を最初に読み、そのルールを絶対厳守せよ という命令を含めてください。

2. 表形式と箇条書きを多用する

LLM は構造化されたデータを好みます。単なる文章よりも、表形式（Markdown Table）やチェックリスト形式の方が、ルールの重みを正しく認識しやすい傾向にあります。

3. 「なぜ」よりも「何を」を強調する

人間向けには理由（Why）が重要ですが、エージェントには具体的な行動（What/How）を指示する方が効果的です。

• ❌ 「保守性が下がるので any は避けてください」
• ✅ 「any の使用を禁止します。発見した場合は Unknown または適切な Interface に置き換えてください」

まとめ

AI コーディングエージェントは、強力なツールであると同時に、制御を誤ればコードベースを混乱させる「諸刃の剣」でもあります。

AGENTS.md は、エージェントに対する**「プロジェクト憲法」**です。

• 禁止事項で事故を防ぎ
• 基準で品質を保ち
• 原則で構造を守り
• 検証ルールで正しさを証明する

このファイルを用意するだけで、エージェントの出力クオリティは劇的に向上し、あなたは「AI が生成したゴミの掃除」から解放されるはずです。今日からあなたのプロジェクトにも、一冊のルールブックを添えてみませんか？