Claude CodeがAGENTS.mdの読み込みに対応：CLAUDE.mdとAGENTS.mdの比較、.claudeディレクトリ

claude.mdとは何か、何を記載すべきか

CLAUDE.md は、Claude Codeがセッションコンテキストに読み込む指示を含む、プレーンテキストのMarkdownファイルです。ビルドとテストのコマンド、コーディング規約、プロジェクトのアーキテクチャ、ワークフローのルールなど、通常なら繰り返し伝える必要がある情報を記録する場所として使えます。

必須のドキュメント形式はありません。通常のMarkdownの見出しやリストを使い、プロジェクトの指示が理解しやすくなる構成を選べます。Claude Codeの /init コマンドは、プロジェクトに基づいて初期ファイルを生成します。詳細は次のドキュメントに記載されています。 公式のベストプラクティスドキュメント.

まずは、次の領域を押さえるとよいでしょう。

• ビルドとテストのコマンド： コントリビューターがプロジェクトをビルドし、変更を確認するために使用するコマンド。
• コーディング規約： 命名、書式設定など、リポジトリに関係する規約。
• プロジェクトのアーキテクチャ： 主要なコンポーネントと、それらの相互関係。
• ワークフローのルール： 変更の実施と確認にあたって、Claudeに従ってほしい手順。

これらは継続的に適用される指針として扱ってください。指示はClaudeのコンテキストに取り込まれますが、強制適用される設定ではありません。Claude Code自体を設定する必要がある場合は、適切な設定ファイルを使用してください。次のファイル内の文章が CLAUDE.md 設定値として機能することを期待しないでください。

リポジトリを整理する際には、この区別が重要です。プロジェクトに関する知識は指示ファイルに、アプリケーションの設定は設定ファイルに置きます。 Claude Codeガイドハブ は、関連するワークフローを理解するための出発点になります。

CLAUDE.mdの配置場所

Claude Codeは、プロジェクトの共有指示と個人用の指示を複数の場所でサポートしています。 指示ファイルのドキュメント には、これらの標準的な配置場所と、指示の検出方法が説明されています。

上位ディレクトリの指示ファイルは起動時に読み込まれます。サブディレクトリ内のファイルは必要に応じて読み込まれるため、Claudeがプロジェクトの該当部分で作業するときに、その指示が適用されるようになります。

共有指示には、チームにとってわかりやすい配置場所を選んでください。ルートに置いた CLAUDE.md では、リポジトリのほかの最上位ファイルと並べて指針を配置できます。 .claude/CLAUDE.md では、プロジェクトのClaude専用ファイルとまとめて配置できます。

個人用指示はファイルの整理以外にも影響する

CLAUDE.local.md は、プロジェクトの共有ファイルとは異なる目的を持ち、そのプロジェクトに対する個人用の指示を保存します。バージョン2.1.277では、このファイルの有無は、Claude Codeが次のファイルにフォールバックするかどうかにも影響します。 AGENTS.md.

つまり、ローカルの指示ファイルを追加すると、どの共有指示がコンテキストに取り込まれるかが変わる場合があります。次のファイルに依存するリポジトリでローカルの指示ファイルを作成する前に AGENTS.md、以下で説明する「プロジェクトの指示」設定を確認してください。

上記の配置場所は継続的に更新されるドキュメントに基づいており、19年9月時点の正確な記述は確認されていません。次のセクションのフォールバック動作は、タグ付きの2.1.277リリースについて明記されています。

Claude CodeはAGENTS.mdを自動的に読み込むか？

はい、条件付きで読み込みます。 Claude Code 2.1.277のリリースノート には、「AGENTS.mdのサポートを追加：CLAUDE.mdがないプロジェクトでは、Claude Codeは代わりにAGENTS.mdを読み込みます」と記載されています。

デフォルトの動作はフォールバックなので、 AGENTS.md ファイルが存在するだけで読み込まれるとは限りません。このリリースでは、ルートにある次のファイル以外もチェックの対象になります。 CLAUDE.md.

デフォルトのフォールバックを抑止するものは？

ファイルシステムのルートから作業ディレクトリまでのパス上のどこかに、以下のいずれかのファイルがあると、デフォルトの AGENTS.md フォールバックが抑止されます。

• CLAUDE.md
• .claude/CLAUDE.md
• CLAUDE.local.md

管理対象の指示、次の場所にある個人用指示 ~/.claude/CLAUDE.md、および .claude/rules/ は わけではありません そのフォールバックを抑止します。

たとえば、共有の AGENTS.md があり、上位ディレクトリへのパス上に条件を満たすClaude指示ファイルがないリポジトリを考えてみましょう。デフォルトモードではAGENTSの指示を読み込みます。その後、次のファイルを追加すると CLAUDE.local.md、デフォルトのフォールバックは抑止されます。新しいファイルに含まれるのがチームの共有指針ではなく個人用指示であっても同様です。

AGENTS.mdの検出方法

組み込みのサポートは、次の agents-md プラグインによって提供されます。バージョンは 0.1.0です。このプラグインは両方を検出します。 AGENTS.md と .claude/AGENTS.md 上位ディレクトリへのパス上で検出し、Claudeがプロジェクトルート配下のファイルを読み込むときに、ネストされた指示を添付します。

インポートやリンクを通じてすでに読み込まれた内容は、重複排除されます。Claude指示ファイルがすでに同じAGENTSの内容を取り込んでいる場合、この点が重要になります。

19年9月の公開情報の締め切り時点では、リリース告知によると、このサポートはBedrock、Vertex、Foundryではまだ利用できません。

Claude Codeで片方または両方のファイルを読み込むように設定する

次を開きます。 /config そして、次の設定を変更します。 プロジェクトの指示 指示の読み込み動作を選択します。 タグ付きv2.1.277プラグインのREADME には、指定できる値が正確に記載されています。

READMEには、次の値に関する重要な注意事項があります。 managed-only：ネストされた CLAUDE.md 添付は引き続き取り込まれる場合があります。この値を、ネストされたClaude指示の内容が会話に一切取り込まれないことの保証と解釈しないでください。

バージョン2.1.277の具体的な設定

両系統の指示を読み込むには、次の設定を使用します。

{
  "pluginConfigs": {
    "agents-md@builtin": {
      "options": {
        "instructionFiles": "claude-md-and-agents-md"
      }
    }
  }
}

このリリースでは、次の場所にあるユーザー設定に記述します。 ~/.claude/settings.json、または次の方法で指定するファイル --settings、あるいは管理対象の設定に記述します。プロジェクトの .claude/settings.json は わけではありません これらのプラグインオプションを提供します。

変更は、次のターンや新しい会話など、コンテキストが次に再構築されるときに適用されます。設定によって読み込まれる指示が変わったかどうかを確認する際は、このタイミングに注意してください。

共有指示のインポートも引き続き利用可能

次の記述を配置することもできます。 @AGENTS.md 隣接する次のファイル内に配置します。 CLAUDE.md。これにより、Claude指示ファイルを通じて共有指示が明示的にインポートされます。

Claude指示ファイルのインポートには、次の構文を使用します。 @path/to/file.md この機能はv0.2.107で導入されました。バージョン2.1.277では、次のファイルによってすでにインポートされたAGENTSの内容が重複排除されます。 CLAUDE.md.

これにより、共有指針を整理する方法を選べます。Claude Codeが両方のファイルを読み込むように設定するか、インポートを使ってAGENTSの内容をClaude指示ファイルに取り込むことができます。リポジトリのコントリビューターにとって関係が明確になる構成を選んでください。

.claudeディレクトリには何を置くべきか？

この .claude ディレクトリには、さまざまな種類のプロジェクトファイルを保存します。それぞれ用途が異なるため、継続的に適用する指針、設定、再利用可能なプロンプト、サブエージェント定義、手順のいずれを記述するかに応じて、配置場所を選んでください。

プロジェクト横断の個人用設定は、次の場所に保存します。 ~/.claude/settings.json。個人用のサブエージェント定義には、次の場所を使用します。 ~/.claude/agents/、個人用スキルでは次を使用します ~/.claude/skills/<name>/SKILL.md.

コマンド、サブエージェント、スキル

次のようなコマンドファイルは .claude/commands/deploy.md 次を作成します /deploy。バージョン 2.1.3 ではスラッシュコマンドとスキルが統合され、既存のコマンドファイルもスキルと併用して引き続き動作します。

サブエージェントの定義には、YAML フロントマターを含む Markdown を使用します。必須フィールドは次のとおりです name と description。関連する任意フィールドには次が含まれます tools, model、および permissionMode。管理には次を使用します /agents。また、 サブエージェントガイド を参照して、プロジェクト設定の該当部分を構成してください。

スキルは、次を含むフォルダーに再利用可能な手順をまとめたものです SKILL.md。任意でスクリプトや参考資料を含めることもできます。Claude は関連するスキルを選択でき、次を使って呼び出すこともできます /skill-name。スキルの本文は使用時に読み込まれます。 スキルガイド では、このワークフローを説明しています。

これらの構造は、AGENTS フォールバックのリリース以前から存在していました。 タグ付き変更履歴 から、プロジェクト設定、コマンド、エージェント、スキルが v2.1.277 までに存在していたことを確認できます。ディレクトリの詳細な説明は随時更新されるドキュメントに基づいており、基準日時点の正確な文言は検証していません。

CLAUDE.md と自動メモリの違い

CLAUDE.md と自動メモリは、内容を誰が書くかが異なります。プロジェクトの指針を定義する指示ファイルはユーザーが記述し、Claude は有用なコンテキストを自動メモリに保存します。

タグ付き変更履歴には、次を通じた自動保存と管理が記載されています /memory 。これはバージョン 2.1.59 で導入されました。したがって、自動メモリは、次のファイルでユーザーが意図的に管理する指示とは別の役割を担います CLAUDE.md または AGENTS.md.

情報をどこに置くか判断するときは、この作成者の違いを基準にしてください。明示的なビルドコマンド、規約、アーキテクチャに関するメモ、ワークフローのルールは指示ファイルに記述します。次を使用して /memory Claude が自動保存する有用なコンテキストを管理してください。

重要なポイント

• CLAUDE.md には、Claude Code がコンテキストに読み込む永続的な Markdown の指示が含まれます。設定を強制するものではありません。
• Claude Code 2.1.277 では、条件付きの AGENTS.md フォールバックが追加されました。リリース時点では Bedrock、Vertex、Foundry は対象外です。
• 祖先ディレクトリにある CLAUDE.md, .claude/CLAUDE.md、または CLAUDE.local.md は、デフォルトのフォールバックを抑止します。
• プロジェクトの指示を次に設定すると claude-md-and-agents-md 両系統の指示を読み込めます。
• v2.1.277 では、プラグインオプションはユーザー設定、 --settings ファイル、または管理対象設定に記述します。プロジェクトの次のファイルには記述しません .claude/settings.json.
• この .claude ディレクトリには、設定、コマンド、サブエージェント、スキルも格納されます。自動メモリには Claude が保存したコンテキストが含まれます。

よくある質問

CLAUDE.md とは何ですか？

CLAUDE.md は、ビルドコマンド、コーディング規約、アーキテクチャに関するメモ、ワークフローのルールなど、Claude Code 向けの永続的な指示を含むプレーンテキストの Markdown ファイルです。Claude はこれをセッションのコンテキストに読み込み、 /init を使うと、プロジェクトに基づいて初期ファイルを生成できます。

CLAUDE.md と AGENTS.md が両方存在する場合、どちらのファイルが読み込まれますか？

Claude Code 2.1.277 のデフォルトの claude-md-or-agents-md モードでは、条件を満たす Claude の指示ファイルがあると、AGENTS フォールバックが抑止されます。次を選択すると claude-md-and-agents-md 両方を読み込めます。または、隣接する AGENTS の指示を次でインポートできます @AGENTS.md 。記述先は次のファイルです CLAUDE.md.

CLAUDE.local.md を追加すると AGENTS フォールバックが停止するのはなぜですか？

バージョン 2.1.277 では、 CLAUDE.local.md も、ファイルシステムのルートから作業ディレクトリまでの間で見つかった場合にデフォルトのフォールバックを抑止するファイルに含まれます。そのため、個人用のプロジェクト指針を記述するためのファイルであっても、その存在によって共有の AGENTS の指示が読み込まれるかどうかが変わる場合があります。

プロジェクトの .claude/settings.json で両方のファイルを有効にできますか？

v2.1.277 では、プロジェクトの .claude/settings.json では、次の agents-md プラグインオプションを指定できません。次を使用するか /config、ドキュメントに記載されている pluginConfigs 設定をユーザー設定、 --settings ファイル、または管理対象設定に記述してください。