CLAUDE.mdとAGENTS.md：役割、書き方、エージェントがルールを無視する理由

CLAUDE.md と AGENTS.md とは

これらはリポジトリのルートにある通常のMarkdownファイルで、セッションの開始時にエージェントが自動的にコンテキストへ読み込みます。コードから推測できないこと、つまり環境の起動方法、検証に使うコマンド、譲れないプロジェクトルール、詳しいドキュメントの場所をエージェントに伝えるためのものです。

CLAUDE.md は Claude Code が読むファイルです。AGENTS.md は同じ考え方に基づくオープンな形式で、多くのコーディングエージェントが対応しています。チームで複数のエージェントを使うなら、主な内容は AGENTS.md に書き、CLAUDE.md からそれを参照するのが便利です。Claude Code では @ を使って別ファイルを取り込めます。

# CLAUDE.md
@AGENTS.md

こうするとルールが一か所にまとまり、二つのファイルの内容がずれることがありません。

エージェントはこれらのファイルをどう読むか

指示ファイルの内容は、システムプロンプトとともにモデルのコンテキストウィンドウに入り、セッションの間ずっと残ります。ここから三つの重要な帰結が生まれます。

• 一行一行がコンテキストの容量を消費する。ファイルは起動のたびに全文が読まれます。今のタスクに必要なのが十分の一でも同じです。
• それは実行可能なルールではなく、テキストである。モデルは他のコンテキストと同じように扱うだけで、百パーセントの遵守は保証されません。厳格な禁止事項は、検査、フック、アクセス権限といった仕組みで担保する必要があります。
• ファイルは階層的に配置できる。Claude Code はプロジェクトルートの CLAUDE.md と、ユーザーディレクトリ ~/.claude/ のファイルを読み込みます。サブディレクトリのファイルは、エージェントがそのディレクトリのファイルを扱うときに読み込まれます。モジュールごとのルールを、そのモジュールのすぐ隣に置けます。

CLAUDE.md と AGENTS.md に書くべきこと

良い指示ファイルは教科書ではなく地図です。新しく入ったエージェントが、ベテランの同僚に初日に尋ねるような質問に答えるものにします。

1. プロジェクトの組み立てと検証の方法

最も価値のあるセクションです。エージェントが「完了」と言う前に必ず実行すべき具体的なコマンド、つまりテスト、リンター、型チェック、環境の起動などを書きます。これがなければ、エージェントは「目分量で」自分の作業を確認するしかありません。

2. 厳格な制約

どんな場合でも破ってはならないことの短いリストです。安全性とデータに関する不変条件を書きます。実装手順ではなく不変条件として書いてください。「SQLクエリは必ずパラメータ化する」は良い例で、「このファイルのこの関数を使え」は悪い例です。

3. プロジェクトの地図

何がどこにあるか。ディレクトリ構成を数行で示し、詳細がどこにあるかを記します。大きなテーマごとに独立したドキュメントへのリンクを置き、エージェントがそのテーマに取りかかったときだけ開くようにします。

4. 作業の状態をどこに置くか

前回のセッションが止まった場所から再開するために見るべきもの、つまり計画ファイル、進捗ログ、バックログを示します。これはセッション間の「健忘症」を治す手段になります。

書いてはいけないこと

• エージェントがコードから読み取れること。依存関係は package.json や pyproject.toml にあり、クラスの構造はコードそのものにあります。
• 一般的なアドバイス。「きれいなコードを書け」「注意深く」などは振る舞いを変えず、スペースを奪うだけです。
• プロジェクトの経緯や一時的なメモ。「3月にMySQL 5.7から移行した」は今のタスクの役に立ちません。
• まれな作業の詳しい手順。デプロイやデータ移行の手順は週に一度しか使わないので、独立したドキュメントやskillに移します。
• シークレット。このファイルはリポジトリにあり、丸ごとモデルに送られます。トークンやパスワードは環境変数にだけ置いてください。

エージェントが、ファイルに書かれたルールを無視するのはなぜか

よくある経緯はこうです。エージェントがミスをする。ルールを一行追加する。また別のミスをする。もう一行追加する。数か月後にはファイルは数百行になり、重要な安全ルールがあたかも存在しないかのように破られています。原因は普通四つあり、同時に働きます。

ファイルの肥大化

600行のファイルはおよそ1万〜2万トークンに相当します。コンテキストウィンドウは大きく見えますが、コード、コマンドの出力、会話履歴とも場所を奪い合います。指示が占める量が多いほど、各ルールが受け取る注意は減り、タスク本体の余地も減ります。

中ほどに埋もれたルール

言語モデルは、長い文章の先頭や末尾の情報を、中ほどの情報よりもうまく使えます。600行のうちの300行目にあるルールは、最も弱い位置にあります。

優先順位がない

譲れない禁止事項も、ちょっとした書式の好みも、同じ形式でリストの一行として並んでいます。エージェントには、どちらが重要かを判断する材料がありません。スタイルに関する矛盾したルールが三つあれば、実行のたびに振る舞いがランダムに変わります。

腐敗

ルールを追加するのはただですが、削除するのは怖いものです。「何か依存しているかもしれない」と思うからです。その結果、ファイルは単調に増え、有用な行の割合は下がっていきます。シグナル対ノイズの比で測ると分かりやすいでしょう。典型的なタスクで実際に必要な行数と、それ以外の行数を比べてみてください。

直し方：長文の代わりにルーターを

一つの原因だけを直しても意味がありません。ファイルを短くしても構造がなければ、ルールは相変わらず混ざったままです。次の措置を組み合わせて効果を出します。

1. 入口のファイルをルーターにする。50〜150行程度にして、検証コマンド、厳格な制約、プロジェクトの地図、専門ドキュメントへのリンクだけを置きます。
2. テーマごとに別ファイルに分ける。例えば docs/agents/deploy.md や docs/agents/database.md。エージェントが必要なときに開きます。Claude Code では、繰り返し行う手順にskillsが向いています。必要になったときだけ読み込まれます。
3. 重要なものを上に置く。厳格な制約はファイルの冒頭に、MUST と明記した短いブロックとして置きます。
4. 矛盾をなくす。テーマごとにルールは一つにします。例外がある場合は、そのルールの隣に書きます。
5. 仕組みでルールを補強する。違反が許されないなら、文章だけでは不十分です。リンター、テスト、pre-commitフック、エージェントのフック、アクセス権限など、違反を検出する仕組みが必要です。
6. 定期的に見直す。行数の上限を決め、何かを追加するたびに、削除したり別ファイルへ移せるものはないか問いかけます。

ルールか、検査か

コンパクトなAGENTS.mdの例

# AGENTS.md——決済バックエンド（FastAPI、PostgreSQL）

## MUST——必ず守る
- 金額は整数（int、円単位）で扱い、float は使わない
- SQLはパラメータ化されたものだけを使い、f文字列は使わない
- 適用済みのマイグレーションは変更せず、新しいものを追加する
- シークレットは環境変数からのみ読み込む

## 「完了」と言う前の検証
docker compose up -d     # 環境
make lint                # ruff + mypy
make test                # pytest
make e2e                 # 注文シナリオ
単体テストが通ってもe2eがなければ「完了」ではない。

## 地図
- app/payments/   — 金額計算、割引、プロバイダのWebhook
- app/api/        — HTTPエンドポイント
- tests/e2e/      — ユーザーのシナリオ
詳細：docs/agents/architecture.md、docs/agents/database.md

## 作業の状態
- PLAN.md      — 現在の目標、完了条件、次のステップ
- PROGRESS.md  — 完了した作業と検証方法、行き詰まり
- BACKLOG.md   — ついでに気づいたこと：ここに記録し、今は直さない

セッションの終わりに PROGRESS.md と PLAN.md の次のステップを更新する。

ここにないものに注目してください。依存ライブラリの一覧、スタイルのアドバイス、プロジェクトの経緯はありません。それらはコードから分かるか、検査で担保されるか、専門ドキュメントにあるからです。

健忘症の問題：指示ファイルと計画ファイル

指示ファイルは、プロジェクトでどう働くかを記述しますが、今何が起きているかは記述しません。そのためには、エージェントがセッションの開始時に読み、終了時に更新する別の状態ファイルが必要です。そこには、目標、完了した作業とその検証方法、理由を伴う決定、棄却した選択肢、そして次のステップが一つだけ書かれます。品質の確認方法は簡単です。新しいセッションを開き、「続けて」とだけ入力してみてください。エージェントが質問せずに有益な作業を始めるかどうかで分かります。

この二つのファイルを混同しないでください。指示はめったに変わらず、すべてのタスクに当てはまります。計画は毎セッション変わり、今のタスクにだけ関係します。混ぜてしまうと、指示ファイルはすぐに古いメモで膨らみます。

ファイルが機能しているかを確認する

指示ファイルも検証が必要です。バグ修正、小さな機能追加、リファクタリングといった典型的なタスクを選び、エージェントが何もヒントなしで何をするかを観察します。必要なコマンドを実行したか、正しい専門ドキュメントを開いたか、厳格な制約を守ったかを確認します。ルールが破られたら、まず問いかけてください。それは目に見えているか、矛盾するルールがないか、自動検査に置き換えられないか。一行追加するのは最後の手段です。

まとめ

CLAUDE.md と AGENTS.md は、エージェントがプロジェクトに入るための入口です。短い地図として機能しているときにだけ役立ちます。検証コマンド、冒頭の厳格な制約、詳細と計画ファイルへのリンクを備えていることが条件です。ルールが無視されるなら、原因はほとんどの場合、肥大化して構造のないファイルにあります。そして本当に重要なルールは、検査とフックで補強する必要があります。指示と状態の組み立て方は、ハーネスエンジニアリングの講座で実践を通して解説しています。