はじめに

AIコーディングエージェントを実務で使い始めると、最初にぶつかるのが「何を、どこまで、どう書いて伝えるか」という問題です。口頭やチャットで毎回補足しているうちは回りますが、リポジトリに明文化されていないルールは再現性がなく、別のセッションや別の担当者に切り替わった瞬間に崩れます。

このときに効くのが AGENT.md や CLAUDE.md のようなエージェント向け指示ファイルです。目的は長い仕様書を書くことではありません。エージェントが迷いやすい判断を先回りして潰し、毎回同じ品質で動ける最短経路を用意することです。この記事では、役割分担、必須項目、避けるべき書き方、運用ルールまで実務目線で整理します。

AGENT.mdとCLAUDE.mdの役割を分ける

まず重要なのは、README.md とエージェント向けファイルを混ぜないことです。README は人間の onboarding 用、AGENT/CLAUDE は実行時の判断補助用と考えると整理しやすくなります。

READMEとの違い

README には、プロダクトの概要、セットアップ手順、アーキテクチャの背景など、人間が最初に読むべき情報を置きます。一方で AGENT/CLAUDE に書くのは、「この repo ではどう動くべきか」という行動指針です。抽象的な背景説明より、失敗しやすいポイントや必須コマンドの方が価値があります。

  • README.md: プロジェクト理解の入口
  • AGENT.md: どのエージェントでも共通で守るべき repo ルール
  • CLAUDE.md: Claude 固有の運用スタイルや応答ルール

分け方の基準

基準は「その指示が repo 固有か、ツール固有か」です。例えば generated/ を直接編集しない、DB スキーマ変更後は生成コマンドを実行する、といった内容は AGENT.md に置くべきです。一方、回答は日本語、レビューでは findings を先に並べる、といった振る舞いは CLAUDE.md 向きです。

もし特定ツールしか使っていないなら CLAUDE.md だけでも運用はできます。ただし、その場合でも「プロジェクト固有の事実」と「ツール依存の振る舞い」は章を分けておくと、将来別エージェントを導入したときに移植しやすくなります。

最初に書くべき項目

最初から完璧なファイルを作る必要はありません。むしろ、毎回エージェントが詰まりやすい項目だけを先に固定する方が効果的です。次の項目は優先度が高いです。

  • プロジェクトの目的: 何を作っている repo なのかを 2〜3 行で明記する
  • 必須コマンド: インストール、開発起動、テスト、ビルド、lint を具体的に書く
  • 変更禁止領域: 自動生成ファイル、外部同期ディレクトリ、秘密情報の扱いを明示する
  • 検証基準: UI 変更後は何を実行するか、API 変更後は何を確認するかを書く
  • コード規約: 命名、コメント方針、使用ライブラリ、既存パターン尊重のルールを書く
  • レビュー観点: バグ、回帰、テスト不足を優先するなど、出力の型を定義する

ポイントは「美しい理念」ではなく「判断に使える事実」を書くことです。きれいなコードを書く よりも、React コンポーネントは既存の hooks パターンを崩さない の方が圧倒的に役に立ちます。

良い指示と悪い指示の違い

エージェント向けファイルが機能しない最大の理由は、抽象的で検証不能な文章が多いことです。読んだ瞬間に行動へ変換できる粒度まで落とす必要があります。

悪い例

# AGENT.md

- 既存コードを尊重する
- できるだけ安全に変更する
- 必要に応じてテストする
- わかりやすい説明を書く

これらは一見もっともらしいですが、実際には何も指示していません。どこまでが「必要に応じて」なのか、何をもって「既存コードを尊重」とするのかが曖昧だからです。

良い例

# AGENT.md

## Project Snapshot
- Product: BtoB 向け管理画面
- Runtime: Node.js 22 / npm
- Main directories: `app/`, `components/`, `lib/`

## Commands
- install: `npm ci`
- dev: `npm run dev`
- test: `npm test`
- build: `npm run build`

## Constraints
- `app/generated/**` は直接編集しない
- DB schema を変えたら `npm run prisma:generate` を実行する
- UI 変更後は `npm run build` を通す
# CLAUDE.md

- 回答は日本語で行う
- 変更前に影響ファイルを短く説明する
- review 依頼では findings を先に列挙する
- テスト未実行なら最後に明記する

良い指示は、実行可能で、検証可能で、優先順位が明確です。エージェントが迷ったときに「どちらを選ぶべきか」が分かるかどうかを基準に書くと精度が上がります。

運用で壊れにくくするコツ

指示ファイルは一度書いて終わりではありません。実務では、事故が起きた後やレビューで毎回同じ指摘が出た後に更新していくのが現実的です。

  • 頻繁に変わる情報は書きすぎない: 一時的なブランチ名や担当者名は別の場所に逃がす
  • 長文化しすぎない: まずは 50〜100 行程度に抑え、リンクで詳細に飛ばす
  • コマンドは実際に通るものだけを書く: 古い npm script を残すと逆効果になる
  • 障害やレビューの再発防止を反映する: 同じミスが出たらルールへ昇格させる
  • 責務を混ぜない: repo 共通ルールとモデル固有ルールは分ける

特に有効なのは、ポストモーテムの結果をそのまま AGENT.md/CLAUDE.md に戻す運用です。たとえば「生成ファイルを手編集して壊した」「レビュー時にリスク説明が抜けた」といった事象は、次回以降の明示ルールに変えやすい題材です。運用ファイルは理想論ではなく、過去の失敗の圧縮メモとして育てると強くなります。

まとめ

AGENT.md と CLAUDE.md の価値は、エージェントを賢く見せることではなく、迷いどころを減らして再現性を上げることにあります。書くべきなのは抽象論ではなく、実際の作業判断に使うルールです。

迷ったら、次の順番で整えると失敗しにくいです。まずは役割分担を決める。次に必須コマンドと禁止事項を書く。最後にレビューや運用で繰り返し出る失敗を追記する。この 3 段階だけでも、エージェントの出力品質はかなり安定します。これから整備するなら、短く具体的な初版を作り、実務の中で育てていくのがおすすめです。

記事一覧に戻る