← ブログに戻る

AGENTS.md と CLAUDE.md の違いは「専用機か汎用機か」ではない — 3ヶ月使い分けて分かった実践設計の分岐点

/ 8分で読めます / claude-code · agents-md · harness · context-engineering

CLAUDE.md と AGENTS.md を両方書いて、3ヶ月で3回矛盾しました。同じプロジェクトで、同じ制約を、微妙に違う言い方で。エージェントは律儀に両方読んで、両方守ろうとして、両方半端に破ります。

一般的な整理は「CLAUDE.md は Claude Code 専用、AGENTS.md は汎用」というものです。この整理は間違ってはいないのですが、両方置いた瞬間から役に立ちません。両方置くと、エージェントから見て両方とも「読むべきファイル」であって、専用も汎用もありません。実際に問題になるのは「どちらに何を書くか」ではなく、「両方置いたときにどう分岐させるか」の設計です。

先日、ハーネスを構成する6要素という記事で、CLAUDE.md を含むハーネス全体の解剖学を書きました。今回はその続きです。解剖してからの「じゃあ実際どう配置するのか」の話をします。

「専用機 vs 汎用機」フレームがなぜ機能しないのか

Anthropic のドキュメントや ch11 のガイドライン上では、AGENTS.md はエージェント非依存のインデックスマップとして紹介されます。CLAUDE.md は Claude Code が起動時に読むファイルとして紹介されます。文字通り解釈すれば、「AGENTS.md を汎用として、CLAUDE.md を Claude 専用として、片方だけ置けばよい」と読めます。

実運用では、そうはなりません。理由は3つあります。

  1. Claude Code は両方読む。AGENTS.md がリポジトリに存在すれば、Claude Code はそれをコンテキストに含めます。CLAUDE.md も同じく読みます。片方だけ置くつもりで両方置いてしまうケースが実際には多い(私も何度もやりました)。
  2. サブエージェントの伝播が違う。CLAUDE.md はメインエージェントには渡りますが、Task ツールで spawn したサブエージェントには自動では引き継がれません。AGENTS.md はプロジェクトルートに置いてあれば、サブエージェントが自主的に読み直します。この非対称が「同じ制約なのに片方だけ守られる」状況を生みます。
  3. 人間のレビュー導線が違う。AGENTS.md は GitHub 上で「プロジェクトの指示書」として PR レビュアーに見えます。CLAUDE.md は Claude を使わないレビュアーからすると「なぜあるのか分からないファイル」で、git blame で忘れられます。

つまり、両者の実効的な違いは「専用機か汎用機か」ではなく、「読み込みタイミング / 伝播経路 / 人間から見える度合い」のトリプルの違いです。

3ヶ月で発生した5つの矛盾

私は ~/.claude/CLAUDE.md(グローバル)と、リポジトリ側の AGENTS.md + プロジェクト CLAUDE.md を併用していました。3ヶ月の運用ログから、実際に衝突したケースを5つ抽出します。

矛盾1: Constraints 節の重複記述

AGENTS.md に「TypeScript strict mode 必須」と書いた翌週、忘れて CLAUDE.md にも「型は strict にすること」と書きました。エージェントは両方読んで、両方をコンテキストに載せました。同じ制約が二重に載っている分だけ、コンテキスト予算が削られます。実害は小さいですが、こういう重複が積み上がると本当に読ませたいスキルファイルの分量を圧迫します。

対処: 制約は AGENTS.md に一本化。CLAUDE.md からは「制約は AGENTS.md 参照」の一行だけ残す。

矛盾2: AGENTS.md の「小さく保つ」ルールを CLAUDE.md が破っていた

AGENTS.md には SmartScope の推奨に従って「500文字以下、ポインター集に徹する」と書いていました。ところが CLAUDE.md は放置してエンハンスするうちに3000文字を超えていました。エージェントは AGENTS.md の「小さく」というメタ指示を読みながら、同時に3000文字の CLAUDE.md も読まされる。エージェントが「このプロジェクトは小さく保つ文化なのか、そうでないのか」の判断に迷いが出ます。

対処: 500文字ルールは AGENTS.md だけでなく CLAUDE.md にも適用する。詳細はスキルファイルにレイジーロードで逃がす。

矛盾3: スキル参照の slug 不一致

AGENTS.md からは harness/skills/add-api-endpoint.md を参照していて、CLAUDE.md からは同じスキルを .claude/skills/add-endpoint.md と別名で参照していました。リファクタリングでスキルファイルを移動したとき、AGENTS.md 側の参照だけを更新して、CLAUDE.md 側の壊れたリンクに1ヶ月気づきませんでした。エージェントは静かに「該当ファイルが見つからないので推測で作業する」を選びます。

対処: スキルファイルの正規パスは AGENTS.md にだけ書く。CLAUDE.md からは AGENTS.md を経由させる。参照は一箇所に集約する。

矛盾4: サブエージェントに CLAUDE.md が伝わらなかった

Task ツールで「テスト全部走らせて」というサブエージェントを spawn したところ、CLAUDE.md に書いてあった「PR は squash merge」というルールをサブエージェントが知らないまま作業しました。Task から返ってきた結果を私がそのまま merge commit で取り込みそうになり、直前に気づきました。

CLAUDE.md はメインエージェントの起動コンテキストにしか載りません。サブエージェントは AGENTS.md をプロジェクトルートで発見するので、コミット/PR 系の制約は AGENTS.md 側に置かないとサブエージェントには伝わりません。

対処: git 運用ルール、コミット規約、PR ポリシーは AGENTS.md 側に置く。CLAUDE.md には対話ポリシー(トーン、確認の頻度など)を残す。

矛盾5: git blame で AGENTS.md 側の更新が忘れられた

チームメンバーが CLAUDE.md を更新したときに、対応する AGENTS.md 側のポインター更新を忘れました。CLAUDE.md 経由でしか作業しないメンバーには問題なく見え、AGENTS.md 経由で読むエージェントには古い情報が残る。ハーネスの状態が人間からもエージェントからも見えにくくなる状況が生まれます。

対処: PR テンプレに「CLAUDE.md と AGENTS.md の両方を確認したか」のチェックボックスを1行追加。これはツールではなく人間側の運用対策です。

私が最終的に決めた分岐点

3ヶ月の矛盾を全部整理した結果、「何を CLAUDE.md に書き、何を AGENTS.md に書くか」の分岐点は以下の3軸で決めるのが実務的だと落ち着きました。

判断軸AGENTS.md に置くCLAUDE.md に置く
誰が読むかエージェント全般 + 人間の PR レビュアーClaude Code メインセッションだけ
伝播範囲サブエージェント含む全プロセスメインエージェントのみ(サブエージェントには渡らない)
更新頻度低い(構造・制約・スキル参照)高い(対話トーン、その日の作業モード)

具体的にマッピングすると:

  • AGENTS.md に置く: プロジェクト概要、ディレクトリ構成、スキルファイルへのポインター、コミット規約、PR ポリシー、テスト要件、禁止事項(理由付き)
  • CLAUDE.md に置く: 対話トーン、確認頻度、そのプロジェクト特有の会話ルール(例: 「ですます調で答えて」)、Claude Code 特有のツール使用方針

大事なのは「両方に同じことを書かない」ことです。ポインター集としての AGENTS.md と、対話ポリシーとしての CLAUDE.md、と役割を分ければ、矛盾5つは全部発生しなくなります。

具体例: 私の実運用

参考までに、私の ~/repos/harness-ops/ の断片を出します(差し障りのある部分は伏せています)。

AGENTS.md(400文字弱):

# AGENTS.md — harness-ops

## Overview
事業運営を自律化するハーネス。cron + Claude Code + skills。

## Structure
- core/    → 抽象層
- domains/ → 事業ドメイン別設定
- skills/  → skills 定義
- scripts/ → cron スクリプト

## Key Skills
- 新ドメイン追加 → skills/add-domain/SKILL.md
- Evolver 手動起動 → skills/harness-evolve/SKILL.md
- カレンダー登録 → core/calendar_register.py 参照

## Constraints
- .sh 編集後は scripts/lint-shellcheck.sh を通す
- 各ドメインは strategy.md に従う
- Evolver は diff 20行 / 週2提案まで(安全弁)

CLAUDE.md(200文字弱):

# CLAUDE.md — harness-ops

構造や制約は AGENTS.md 参照。

対話モード:
- 判断ログはドメインの data/ に必ず残す
- カレンダー登録は core/calendar_register.py 経由(直接叩かない)
- 決断疲れの検知は harness-ops/docs 参照

CLAUDE.md は「AGENTS.md 見て」で済ませて、Claude Code の対話特有の話だけ残しました。3ヶ月の運用でこの2ファイルは分量が肥大化しませんでした。

「両方置く」が悪いわけではない

念のため書いておくと、両方置くこと自体が悪いわけではありません。むしろ、伝播経路が違うので両方置いた方が良い場面が多いです。悪いのは「同じことを両方に書く」ことと、「AGENTS.md を巨大化させる」ことです。

Anthropic Engineering Blog が繰り返し強調しているのは「小さく保つ」です。ファイルを分割することが目的ではなく、コンテキストウィンドウを圧迫しないことが目的です。AGENTS.md と CLAUDE.md を役割分担させることで、両方を小さく保てるなら意味があります。両方を分厚くしただけなら、片方だけの方がマシです。

Louis Bouchard の言葉を借りるなら、「モデルがバカだ」と言うのをやめて、「自分のシステムがこの矛盾を許容した」と言うことにしました。矛盾5つは全部、私が両方に何を書くかを設計しないまま書き足したから起きました。設計してから書き足すと、矛盾は起きません。当たり前ですが、当たり前を言語化しないと3ヶ月かかります。

まとめ

  • AGENTS.md と CLAUDE.md の実効的な違いは「読み込みタイミング / 伝播経路 / 人間から見える度合い」の3つ
  • 両方置くと3ヶ月で矛盾が発生する(私は5つ発生させました)
  • 分岐点は「誰が読むか / 伝播範囲 / 更新頻度」の3軸で決める
  • AGENTS.md はポインター集 + 構造 + 制約、CLAUDE.md は対話ポリシーだけ
  • 両方に同じことを書かない、両方を小さく保つ

ハーネス設計全体を体系立てて書き下ろしたのが ハーネス エンジニアリング実践ガイド です。AGENTS.md/CLAUDE.md の話は ch11 に相当します。ch08 の「6要素の解剖学」→ ch11 の「実践設計」の順で読むと、この記事の位置づけが見えると思います。

関連する記事

記事一覧を見る →