AGENTS.md・CLAUDE.mdとは|書き方と違い・使い分けの設計
最終更新日:2026/10/08
AGENTS.mdとは、AIコーディングエージェントにプロジェクトの前提を渡すための指示ファイルで、CLAUDE.mdはそのClaude Code版です。「両方いるのか」「書いたのに守られない」で詰まる人に向けて、公式仕様にもとづく置き場所・読み込み順・書き方の型と、客先案件で使うときの線引きまで整理します。
先に結論
AGENTS.mdは複数エージェント共通の「エージェント向けREADME」、CLAUDE.mdはClaude Code専用の階層型メモリ。役割が違うので、二重管理にしないことが設計の出発点
Claude Codeは2026年9月リリースのv2.1.277以降、CLAUDE.mdが無いときにAGENTS.mdを読む(公式ドキュメント記載)。「Claude CodeはAGENTS.mdを読まない」という説明は古い
複数ツールを併用するなら、AGENTS.mdを正本にして、Claude固有の指示だけをCLAUDE.md側に足すのが二重管理を避けやすい
1ファイルは200行以内が公式の目安。長くすると守られにくくなるため、パス別ルール・スキルへ逃がす
指示ファイルは強制力のある設定ではなく文脈。必ず止めたい操作はフックなどの仕組み側で担保する
客先案件では、自分用の設定を相手のリポジトリにコミットしない。ローカル専用ファイルとgitignoreの運用を参画初日に決めておく
書き方の型だけ先に挙げると、次の3点に集約されます。
最初に書くのは実行コマンド・テスト手順・リポジトリ構成・禁止事項の4点
抽象的な方針ではなく、コマンド名とパス名で書く
200行を超えたら分割する
この記事でわかること
AGENTS.mdとCLAUDE.mdの役割の違いと、どちらを正本にすべきか
Claude Code・Codex・GitHub Copilotがそれぞれどのファイルをどこから読むか
指示が効かないときの切り分け手順
客先常駐・受託案件で指示ファイルを扱うときの契約・情報の注意点
対象は、AIコーディングエージェントを日常的に使っているエンジニアです。Claude CodeやCodex CLIを一度でも動かしたことがあれば読み進められます。
目次
AGENTS.mdとCLAUDE.mdの違い|役割と対応ツール
Claude CodeはAGENTS.mdを読むのか|2026年9月以降の仕様
置き場所と読み込み順|ツール別早見表とモノレポ運用
何を書き、何を書かないか
肥大化させない設計の型|3層に分けて書く
「指示が効かない」ときの切り分け手順
客先案件・受託で指示ファイルを使うときの注意点
よくある失敗と対策
導入チェックリスト
まとめ
よくある質問
AGENTS.mdとCLAUDE.mdの違い|役割と対応ツール
結論から言うと、AGENTS.mdは「ツール横断の共通仕様」、CLAUDE.mdは「Claude Codeの製品機能」です。同じマークダウンファイルでも、出自がまったく違います。
AGENTS.md:エージェント向けのREADME
AGENTS.md公式サイトは、AGENTS.mdを「AIコーディングエージェントがプロジェクトで作業するために必要な文脈と指示を提供する、専用で予測可能な場所」と定義しています。README.mdが人間向けの説明であるのに対し、AGENTS.mdはエージェント向けの作業手順書という住み分けです。
公式サイトには、対応ツールとしてOpenAI Codex、Google Jules、GitHub Copilot、VS Code、Cursor、Zed、Devin、Windsurf、JetBrains Junie、Gemini CLI、Aiderなど25以上が掲載されています。特定ベンダーの機能ではなく、オープンな取り決めとして公開されている点が特徴です。
推奨セクションとして公式が挙げているのは、プロジェクト概要/ビルド・テストコマンド/コードスタイル/テスト手順/セキュリティ上の考慮事項の5つ。この5項目が、どのツールでも外せない骨格になります。
CLAUDE.md:Claude Code専用の階層型メモリ
一方のCLAUDE.mdは、Claude Code公式ドキュメントが定める製品機能です。AGENTS.mdと違ってスコープが4階層に分かれているのが大きな差で、組織配布・個人設定・プロジェクト共有・個人のローカル設定を別ファイルに分離できます。
さらにClaude Codeには、.claude/rules/ ディレクトリでパス別にルールを分割する仕組みや、Claudeが自分で学習メモを書き足すオートメモリもあります。AGENTS.mdが「1枚の取扱説明書」なら、CLAUDE.mdは「階層を持つ設定群」と捉えると整理しやすいでしょう。
README.md・CONTRIBUTING.mdとどう分けるか
ファイル | 主な読み手 | 書く内容 |
|---|---|---|
README.md | 人間(利用者・新規参加者) | プロダクトの概要、導入方法、使い方 |
CONTRIBUTING.md | 人間(コントリビューター) | 貢献の流れ、レビュー方針、行動規範 |
AGENTS.md | AIエージェント全般 | ビルド・テストの実行コマンド、禁止事項、構造の説明 |
CLAUDE.md | Claude Code | 上記に加えて、Claude固有の運用指示 |
重複させるほどメンテ漏れが起きます。READMEにしか書いていない「このコマンドで動く」をAGENTS.mdにも書き写すのではなく、エージェントが迷いやすい点だけを抜き出すのがコツです。
ミニFAQ:両方のファイルを置くと矛盾しませんか
内容が重複・競合すると矛盾しやすくなります。両方を置くこと自体が問題なのではなく、同じ論点を二重に書くことが原因です。Claude Code公式も「2つの指示が矛盾する場合、Claudeはどちらかを恣意的に選ぶことがある」と明記しています。本体をAGENTS.mdに置き、CLAUDE.md側はインポート1行+Claude固有の数行に留めると衝突しにくくなります。
Claude CodeはAGENTS.mdを読むのか|2026年9月以降の仕様
読みます。ただし条件付きです。 Claude Code公式ドキュメントは「AGENTS.mdを直接読むにはClaude Code v2.1.277以降が必要」と記載しています。日本語の解説記事には「Claude CodeはAGENTS.mdを読み込まない」と書かれたものが残っていますが、これは仕様変更前の情報です。
本章の記述は、本記事執筆時点(2026年10月)に上記の公式ドキュメントで確認できる内容にもとづきます。AIコーディングツールの仕様は更新が早いため、挙動が想定と違う場合は公式ドキュメントの現行版を確認してください。
読み込みの条件
既定の挙動は、公式ドキュメントの表に整理されています。
リポジトリの状態 | Claudeが読むもの |
|---|---|
AGENTS.mdがあり、作業ディレクトリとその上位にCLAUDE.md/CLAUDE.local.mdが無い | AGENTS.md |
AGENTS.mdとCLAUDE.md(またはCLAUDE.local.md)の両方がある | CLAUDE.mdのみ |
CLAUDE.mdがAGENTS.mdをインポートしている | CLAUDE.md(インポート経由でAGENTS.mdも含む) |
判定に数えられるのは、作業ディレクトリとその上位にある CLAUDE.md/.claude/CLAUDE.md/CLAUDE.local.md の3つ。ユーザースコープの ~/.claude/CLAUDE.md、組織配布のCLAUDE.md、.claude/rules/ のファイルは判定に数えられず、AGENTS.mdと並行して読み込まれます。
挙動を変えたいときの設定
セッション内で /config を開き、Project instructions の値を変えると挙動が変わります。
値 | 読まれるファイル |
|---|---|
claude-md-or-agents-md | CLAUDE.md、無ければAGENTS.md(既定値) |
claude-md-and-agents-md | 両方を読む(各ディレクトリでCLAUDE.md→AGENTS.mdの順) |
claude-md | CLAUDE.mdのみ |
managed-only | 組織配布のCLAUDE.mdとオートメモリのみ |
読まれないファイルに注意
公式ドキュメントは、AGENTS.local.md、AGENTS.override.md、.agents/ 配下は読まないと明記しています。ここが紛らわしいのは、Codex側はAGENTS.override.mdを読む点です。ツールをまたいで同じファイル名が同じ意味を持つとは限りません。
ミニFAQ:CLAUDE.local.mdを置いたらAGENTS.mdが効かなくなりました
仕様どおりの挙動です。CLAUDE.local.mdは判定に数えられるため、置いた時点でAGENTS.mdの読み込みが止まります。両方を読ませたい場合は Project instructions を claude-md-and-agents-md に変更してください。
置き場所と読み込み順|ツール別早見表とモノレポ運用
Claude Codeの4スコープ
読み込み順は、スコープの広いものから狭いものへ。後に読まれたものほどClaudeの文脈では新しい情報になります。
スコープ | 置き場所 | 用途 |
|---|---|---|
組織配布(managed) | macOSは /Library/Application Support/ClaudeCode/CLAUDE.md、Linux・WSLは /etc/claude-code/CLAUDE.md | 全社の規約・セキュリティ方針 |
ユーザー | ~/.claude/CLAUDE.md | 全プロジェクト共通の個人設定 |
プロジェクト | ./CLAUDE.md または ./.claude/CLAUDE.md | チーム共有。バージョン管理に入れる |
ローカル | ./CLAUDE.local.md | 個人のプロジェクト設定。gitignore対象 |
ディレクトリ階層では、ファイルシステムのルート側から作業ディレクトリへ向かって連結されます。各ディレクトリ内では CLAUDE.local.md が CLAUDE.md の後に追加されるため、個人の指示が最後に読まれる構造です。サブディレクトリのCLAUDE.mdは起動時には読まれず、Claudeがそのディレクトリのファイルを読み書きしたタイミングで読み込まれます。
Codexの探索順と32KiBの壁
Codex公式ドキュメントによると、Codexはグローバル(~/.codex/AGENTS.override.md、~/.codex/AGENTS.md)を見てから、プロジェクトルートから作業ディレクトリまでの各階層で AGENTS.override.md、AGENTS.md の順に探索します。連結はルート側から行われ、「作業ディレクトリに近いファイルほど後に出現するため、先の指示を上書きする」と説明されています。
実務で効いてくるのがサイズ上限です。Codexは結合後のサイズが project_doc_max_bytes(既定32KiB)に達すると、それ以降のファイルの追加を止めます。モノレポでルート側に大きなAGENTS.mdを置くと、本当に読ませたいパッケージ直下のファイルが落ちるという事故が起こり得ます。上限は ~/.codex/config.toml で変更できますが、まずはルート側を軽くするのが筋です。
GitHub Copilotなど他ツール
GitHub Copilot公式ドキュメントでは、リポジトリ全体向けの .github/copilot-instructions.md、パス別の .github/instructions/ 配下のファイル、そしてエージェント指示としてAGENTS.md・CLAUDE.md・GEMINI.mdが挙げられています。ただし「現時点ですべてのCopilot機能がサポートしているわけではない」という但し書きが付いており、IDEによって扱いが異なります。各ツールの位置づけの違いはAIコーディングエージェント比較|Cursor・Claude Code・Clineの選び方でも整理しています。
モノレポでは「近いファイルが勝つ」を前提に置く
AGENTS.md公式サイトは「各パッケージ内に別のAGENTS.mdを配置でき、エージェントはディレクトリツリー内の最も近いファイルを読み込む」と説明しています。OpenAIのリポジトリでは88個のAGENTS.mdが使われている例も紹介されています。
ルートには全体共通の最小限だけを置き、パッケージ固有のビルド手順やテストコマンドはパッケージ直下へ。Claude Codeで他チームのファイルを読ませたくない場合は、settings.json の claudeMdExcludes にグロブパターンを書いて除外できます。
何を書き、何を書かないか
原則は「検証できる粒度で書く」。Claude Code公式は、良い例と悪い例を次のように対比しています。
「コードを適切にフォーマットする」ではなく「2スペースインデントを使う」
「変更をテストする」ではなく「コミット前に npm test を実行する」
「ファイルを整理する」ではなく「APIハンドラは src/api/handlers/ に置く」
書くべき6要素
セットアップ・実行コマンド:依存関係のインストール、開発サーバーの起動方法
テストと品質ゲート:どのコマンドでテストが通るか、コミット前に何を通すか
リポジトリ構造:どのディレクトリに何があるか、エージェントが迷いやすい場所
コード規約:命名、インデント、使用禁止のライブラリや書き方
Git・PR規約:ブランチ命名、コミットメッセージ、PR本文のテンプレート
ガードレール:触ってはいけないファイル、実行してはいけないコマンド
書かないほうがよいもの
リンターやフォーマッタで機械的に検出できる規約。設定ファイルに任せたほうが確実です
一時的な依頼。「今回だけこうして」はチャットで伝える内容で、ファイルに残すとノイズになります
コードベースから読み取れる情報。ディレクトリ一覧や依存パッケージの羅列は、読ませる価値に対して文脈の消費が大きくなります
秘密情報。APIキー、顧客名、社内固有の非公開情報。バージョン管理に入るファイルであることを忘れずに
Claude Code公式は、CLAUDE.mdに追記すべきタイミングを「同じミスを2回目にしたとき」「同じ訂正を前回のセッションでも打ち込んだとき」「新しいチームメンバーにも同じ説明が必要なとき」と表現しています。この基準は、ファイルを無駄に太らせないフィルタとして実用的です。
そのまま使える最小テンプレート
迷ったら、次の5見出しだけで始められます。各見出しの下は3〜5行で十分です。
見出し | 書く内容 | 記入例 |
|---|---|---|
Project overview | 何のプロジェクトか、主要言語とフレームワーク | TypeScript製のSaaS管理画面。Next.js App Routerを使用 |
Setup | 依存関係の導入と開発サーバー起動 | pnpm install を実行し、pnpm dev で起動する |
Test | テストと静的解析のコマンド | コミット前に pnpm test と pnpm lint を通す |
Code style | 命名・整形・使用禁止の書き方 | インデントは2スペース。any型は使わない |
Guardrails | 触らせない場所、実行させないコマンド | infra/ 配下は変更しない。本番DBへは接続しない |
この5つは、AGENTS.md公式サイトが推奨セクションとして挙げている項目とほぼ対応します。まずこの骨格を置き、エージェントが実際に間違えた箇所だけを足していくと、不要な肥大化を避けられます。
ミニFAQ:どのくらいの分量が適正ですか
Claude Code公式は1ファイルあたり200行未満を目標として挙げています。Codexの場合は結合後32KiBという別種の制約があります。行数の正解を探すより、書いた指示が実際に守られているかで判断するほうが早いでしょう。
肥大化させない設計の型|3層に分けて書く
指示ファイルが守られなくなる原因の多くは、内容ではなく分量です。公式も「長いファイルは文脈を消費し、遵守率を下げる」と明記しています。そこで、常時読ませるものと必要なときだけ読ませるものを分けます。
1層目:常時読ませる本体(AGENTS.md)
全作業に効く最小限だけを置きます。ビルド・テストコマンド、絶対に守ってほしい禁止事項、リポジトリ構造の要点。ここが200行を超えてきたら、2層目へ移す合図です。
2層目:条件付きで読ませるルール(.claude/rules/)
Claude Codeでは .claude/rules/ にトピック別のファイルを置けます。YAMLフロントマターの paths フィールドにグロブパターンを書くと、Claudeがそのパターンに一致するファイルを読み書きしたときだけルールが読み込まれます。
たとえばAPI層の規約を src/api/配下のTypeScriptファイルに限定すれば、フロントエンドの作業中はその文脈を消費しません。paths を書かないルールは常時読み込みになり、.claude/CLAUDE.md と同じ優先度で扱われます。
3層目:手順はスキル・フックへ
複数ステップの手順は、指示ファイルではなくスキルに切り出します。そして「何があっても止めたい操作」はフックで担保するのが要点です。
ここは誤解されやすい部分なので強調しておきます。Claude Code公式は「Claudeは指示ファイルを文脈として扱い、強制された設定としては扱わない」「Claudeの判断に関わらず操作をブロックしたいなら、PreToolUseフックを使う」と明言しています。本番DBへの接続を禁止したいなら、AGENTS.mdに「接続禁止」と書くだけでは担保になりません。
@importの使いどころと落とし穴
CLAUDE.mdは @path/to/import の記法で他ファイルを取り込めます。相対パスはインポート元ファイルからの相対で解決され、再帰的なインポートは最大4ホップまで。
注意点が2つあります。ひとつは、インポートしても文脈の消費量は減らないこと。インポート先も起動時にまとめて読み込まれるため、整理には役立ってもコスト削減にはなりません。もうひとつは、パスにスペースが含まれる場合、各スペースの前にバックスラッシュが必要な点です。クォートで囲んだパスはインポートされません。
コンテキストをどう設計するかという考え方そのものは、コンテキストエンジニアリングとは|プロンプトとの違いと実務で体系的に扱っています。
「指示が効かない」ときの切り分け手順
書いたはずの指示が無視される。これが一番よく聞く悩みです。原因は「読まれていない」「読まれているが曖昧」「そもそも指示では強制できない」の3つに切り分けられます。
手順1:読み込まれているか確認する
Claude Codeならセッション内で /context を実行し、Memory files の一覧に目的のファイルが載っているかを見ます。載っていなければClaudeはそのファイルを見ていません。/memory を使えばファイル一覧を開いて編集できます。
サブディレクトリのCLAUDE.mdは起動時の一覧には現れません。これは仕様で、そのディレクトリのファイルを読み書きしたときに読み込まれます。新しく作ったものをテストするなら、Claudeに書かせるのではなくシェルから作成し、そのディレクトリのファイルを読ませてみるのが確実です。
手順2:AGENTS.mdが読まれない場合
公式のトラブルシュートは、次の順で確認するよう案内しています。
作業ディレクトリとその上位に CLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.md が無いか探す(~/.claude/CLAUDE.md は除く)
claude --version でv2.1.277以降か確認する
/config で Project instructions が claude-md や managed-only になっていないか確認する
/config にその設定自体が出てこない場合は、そのセッションがAGENTS.mdを読めない状態にあります。そのときは、AGENTS.mdの隣にCLAUDE.mdを置いて @AGENTS.md でインポートする形に切り替えます。
手順3:書き方を疑う
読み込まれているのに守られないなら、指示の具体性と矛盾を疑います。複数のCLAUDE.mdやルールファイルに食い違う記述があると、どちらが採用されるかは安定しません。Claude Codeにはv2.1.283以降で /doctor prompt-audit という監査コマンドがあり、古いモデル向けの指示、存在しないファイルやコマンドへの参照、相互に矛盾する記述を洗い出してレポートしてくれます。
手順4:そもそも指示で足りているかを疑う
特定のタイミングで必ず実行させたい処理(コミット前、ファイル編集後など)は、指示ではなくフックの領域です。システムプロンプトのレベルで渡したい内容なら、起動時の --append-system-prompt オプションという選択肢もあります。
ミニFAQ:/compact したら指示が消えたように見えます
プロジェクトルートのCLAUDE.mdは圧縮後にディスクから再読み込みされるため残ります。消えたように見えるのは、会話内だけで伝えた指示か、まだ再読み込みされていないサブディレクトリのファイル、あるいは直近でパスが一致していないパス別ルールです。
客先案件・受託で指示ファイルを使うときの注意点
ここからはフリーランス視点の論点です。自分のリポジトリなら好きにすればよいのですが、他人のリポジトリで作業する場合、指示ファイルは契約と情報管理の対象になります。
クライアントのリポジトリに自分の設定をコミットしてよいか
原則として、個人の好みはコミットしない。CLAUDE.mdやAGENTS.mdはバージョン管理に入り、チーム全員のエージェント挙動に影響します。「自分はこの書き方が好き」をプロジェクトのファイルに入れると、他メンバーの作業に副作用が出ます。
個人設定は、プロジェクトルートのCLAUDE.local.mdか、~/.claude/CLAUDE.md に置くのが筋です。前者は.gitignoreへの追加が前提で、公式も「バージョン管理に入れないプロジェクト固有の個人設定用」と位置づけています。gitignoreの追加を忘れると、自分のサンドボックスURLや検証用データが相手のリポジトリに入ります。
ただし前述のとおり、CLAUDE.local.mdを置くとAGENTS.mdの読み込みが止まります。AGENTS.md運用のプロジェクトで個人設定も持ちたいなら、Project instructions を claude-md-and-agents-md にするか、~/.claude/ 側に寄せる判断が要ります。
秘密情報をどこまで書けるか
AGENTS.mdには、業務知識やドメイン固有の前提を書くほどエージェントの精度が上がります。だからこそ、顧客名・取引先名・未公開の仕様・個人情報を書き込む誘惑が生じる。ここは秘密保持契約の範囲を確認してからにすべき領域です。条項の読み方は秘密保持契約(NDA)とは|フリーランスエンジニアが押さえる条項とチェックポイントにまとめています。
加えて、常駐先の生成AI利用規程との整合も参画初日に確認したい項目です。ツール自体の利用が許可されていても、「どの情報をプロンプトに入れてよいか」は別途定められているケースがあります。契約・機密情報まわりの実務は業務委託で生成AIを使うときの契約・機密情報の注意点|客先案件の実務、持ち込みPCやISMS要件への対応は客先セキュリティ要件対応|ISMS・Pマーク・持ち込みPCの実務が参考になります。
自分のテンプレートを次の案件へ持ち出せるか
案件ごとにAGENTS.mdを整備していると、自分なりの「型」が資産として溜まります。構成や見出しの型そのものは一般的な知識として持ち出せる範囲ですが、クライアント固有の業務知識・内部構造の記述が混ざった状態のファイルをそのまま次の現場へ持ち込むのは避けるべきです。テンプレート化するときは、固有名詞と業務ロジックを抜いた骨組みだけを残す運用にしておくと、後から線引きで悩みません。
参画初日にAGENTS.mdを書くとキャッチアップが早い
これは実務で効く使い方です。参画して最初にやることは、ビルドが通る手順とテストの回し方の把握。それをそのままAGENTS.mdに書き下ろすと、自分のキャッチアップメモとエージェントへの指示が同じ成果物になります。既存のリポジトリに指示ファイルが無い場合、Claude Codeの /init を走らせると、コードベースを解析してビルドコマンドやテスト手順を含むたたき台を生成してくれます。
整備した内容をチームに共有できれば、参画初月の貢献として見えやすい実績にもなります。立ち上がりの進め方はフリーランス参画初月の立ち上がり方|30日で信頼を得るオンボーディング型、レビュー文化への馴染み方はコードレビューの作法|指摘の書き方・受け方と信頼される進め方が具体的です。
なお、こうしたAIエージェント運用の経験は商談でも話題になりやすい領域です。自分の経験が市場でどう評価されるかを確認したい方は、無料のフリーランスエンジニア単価診断で現在の市場単価の目安を把握できます。
よくある失敗と対策
失敗1:AGENTS.mdとCLAUDE.mdに同じ内容を書いて放置する
片方だけ更新され、もう片方が古い規約を主張し続ける状態になります。対策は正本をひとつに決めること。AGENTS.mdを本体にして、CLAUDE.mdは @AGENTS.md の1行とClaude固有の指示だけにします。シンボリックリンクでも同じ効果が得られますが、Windowsで作業するメンバーがいる場合は管理者権限やcore.symlinksの設定が絡むため、インポート記法のほうが無難です。
失敗2:「このファイルを読め」と文章で指示する
CLAUDE.mdに「AGENTS.mdを読んでください」と日本語で書いても、Claudeがそのファイルを開くと判断しなければ読まれません。公式も「言葉で指示した場合、Claudeがファイルを開くと決めたときだけ見える」と説明しています。確実に読ませるなら @AGENTS.md のインポート記法を使います。
失敗3:ルートに巨大なAGENTS.mdを置く
Codexでは結合サイズが上限に達した時点で以降のファイルが追加されなくなるため、ルートが重いとパッケージ固有の指示が落ちます。Claude Codeでも遵守率が下がります。ルートは共通の最小限に、詳細は下層とパス別ルールへ。
失敗4:禁止事項を指示ファイルだけで担保する
「本番環境には接続しない」「このディレクトリは触らない」をファイルに書いただけで安心してしまうパターン。指示ファイルは文脈であって強制力ではありません。重要な禁止はフックや権限設定で止めます。
失敗5:個人設定をプロジェクトのファイルに混ぜる
チーム全員のエージェント挙動が、ひとりの好みに引きずられます。スコープを使い分けてください。
導入チェックリスト
参画時・新規プロジェクト立ち上げ時に、上から順に確認できる形にまとめました。
# | 確認項目 | 判断基準 |
|---|---|---|
1 | リポジトリに既存の指示ファイルがあるか | AGENTS.md / CLAUDE.md / .github/copilot-instructions.md / .cursor/rules を確認 |
2 | 正本をどれにするか決めたか | 複数ツール併用ならAGENTS.mdを本体に |
3 | ビルド・テストコマンドが書かれているか | コピペで動く形になっているか |
4 | 禁止事項が書かれているか | 触らせたくないパス、実行させたくないコマンド |
5 | 本体が200行以内に収まっているか | 超えるならパス別ルールへ分割 |
6 | 重要な禁止をフック側でも担保したか | 指示ファイルだけに頼っていないか |
7 | 個人設定をプロジェクトファイルに混ぜていないか | CLAUDE.local.md か ~/.claude/ へ |
8 | CLAUDE.local.mdを.gitignoreに入れたか | コミット事故の防止 |
9 | 秘密情報・顧客固有情報が入っていないか | NDA・社内規程の範囲内か |
10 | 読み込まれていることを確認したか | /context の Memory files で確認 |
まとめ
AGENTS.mdを正本に置き、Claude固有の指示だけをCLAUDE.mdに足す。これが2026年10月時点での最もメンテしやすい構成です。
AGENTS.mdはツール横断の共通仕様、CLAUDE.mdはClaude Code専用の階層型メモリ。役割が違う
Claude Codeはv2.1.277以降、CLAUDE.mdが無いときにAGENTS.mdを読む。古い解説に引きずられない
本体は200行以内。超える分はパス別ルールやスキルへ逃がす
Codexは結合32KiBで打ち切られるため、ルートを重くしない
指示ファイルは文脈であって強制力ではない。必ず止めたい操作はフックで担保する
客先案件では、個人設定をプロジェクトのファイルに混ぜない。CLAUDE.local.mdはgitignoreとセットで
秘密情報の記述範囲はNDAと常駐先の生成AI利用規程を確認してから決める
次のアクションとしては、いま参画しているリポジトリで /context を実行して、どのファイルが実際に読み込まれているかを確認するところから始めるのが早道です。想定と違っていれば、この記事の切り分け手順に戻ってください。
参照した一次情報は次のとおりです。
よくある質問
AGENTS.mdとCLAUDE.md、どちらか片方だけにできますか
できます。Claude Codeしか使わないならCLAUDE.mdだけで足ります。逆に、v2.1.277以降のClaude Codeを使っていてCLAUDE.mdを置かなければ、AGENTS.md1枚で運用できます。複数ツールを併用する場合は、AGENTS.mdを本体にしてCLAUDE.mdから取り込む形が管理しやすいでしょう。
ファイル名はagents.mdでも動きますか
AGENTS.md公式サイトおよび各ツールのドキュメントは大文字表記のAGENTS.mdで記述しています。ツールによってはファイル名の候補を設定で追加できますが(Codexの project_doc_fallback_filenames など)、既定の挙動を期待するなら公式表記に合わせるのが確実です。
CLAUDE.mdとスキル、ルールはどう使い分けますか
常に守ってほしい短い事実はCLAUDE.md、コードベースの一部にだけ効くものは .claude/rules/ のパス別ルール、複数ステップの再現可能な手順はスキルです。公式も「複数ステップの手順や、コードベースの一部にだけ関係するものはスキルかパス別ルールへ移す」と案内しています。
日本語で書いても大丈夫ですか
動作します。ただし、コマンド名・パス・識別子は原文のまま書いてください。「テストを実行する」より「npm test を実行する」のように、検証できる形で書くほうが守られやすくなります。
指示ファイルを置けば必ず従いますか
従うとは限りません。Claude Code公式は、CLAUDE.mdの内容がシステムプロンプトではなくシステムプロンプト後のユーザーメッセージとして渡されると説明したうえで、「厳密な遵守の保証はない。特に曖昧な指示や矛盾する指示ではそうなる」と明記しています。確実性が要るものはフックで担保してください。
チームメンバーが指示ファイルを更新しません
更新のきっかけを定義しておくと動きやすくなります。「同じ指摘がレビューで2回出たら追記する」のように、イベント駆動のルールにするのが実用的です。レビューのやり取りからパターンを拾う進め方はコードレビューの作法|指摘の書き方・受け方と信頼される進め方が参考になります。
モノレポでどの階層に何を置くべきですか
ルートには全パッケージ共通の規約と禁止事項だけ。言語やビルドツールが異なるパッケージには、その直下に個別のAGENTS.mdを置きます。最も近いファイルが優先されるため、パッケージ側で上書きできます。他チームのファイルを読ませたくない場合、Claude Codeなら claudeMdExcludes で除外できます。
指示ファイルの整備は案件単価に影響しますか
直接的な単価項目として提示されるものではありませんが、エージェント運用の整備経験はスキルシートに書ける実務です。AIツールの使いこなしをどう案件アピールに結びつけるかはエンジニアの生成AI活用術|ツール使い分けで開発効率化と単価アピールに効く実務で具体的に整理しています。
Cursorやその他のIDEはどう扱いますか
Cursorは .cursor/rules 形式の独自ルールを持ちつつ、AGENTS.md公式サイトの対応ツール一覧にも掲載されています。GitHub Copilotも .github/copilot-instructions.md を標準としながらAGENTS.mdをエージェント指示として扱います。ツールごとの特徴はCursorとは?AIコードエディタの特徴・使い方・料金とGitHub Copilotとの違いを解説、GitHub Copilotの使い方|エンジニアの開発効率と案件単価への影響を解説でそれぞれ扱っています。
Claude Code自体の使い方も知りたいのですが
導入手順、料金プラン、案件での使われ方はClaude Codeとは|使い方・料金プラン・案件動向を解説にまとめています。本記事は指示ファイルの設計に絞っているため、ツール本体の情報はそちらを参照してください。OSS系の選択肢はClineとは|OSSのAIコーディングエージェントの使い方・料金・違いが該当します。
エージェントに任せる範囲はどう決めればいいですか
指示ファイルの整備は「任せる前提を揃える」作業であって、任せる範囲の判断は別問題です。AIとの協働スタイルの実態はvibe codingとは|AI協働コーディングの実態とエンジニアの業務変化【2026年版】で扱っています。
