Claude CodeのAGENTS.md対応｜共有ルールの使い方と設定
Claude Codeで共有ルールをそろえたいのに、CLAUDE.mdとAGENTS.mdのどちらへ何を書くべきか迷うのではないでしょうか。2026年9月18日の告知で、同じフォルダにCLAUDE.mdがない場合にAGENTS.mdを確認する対応が示されました。今回の条件と、受託開発で使える共有文書の作り方、小さな案件での確認方法までまとめました。
AGENTS.mdが確認される条件は、同じフォルダにCLAUDE.mdがない場合です。告知された対象はClaude Code v2.1.277であり、AGENTS.mdを置くだけでどの構成でも同じ結果になると広げて解釈せず、まず対象フォルダを確認します。
CLAUDE.mdがある案件では、従来の指示をいきなり移動しません。既存ファイルの有無を先に確認し、両方がある場合や階層が異なる場合は、告知で明示されていない優先関係を実機で確かめてから共有ルールを決めます。
チームで使う文書には、命名だけでなく確認方法と納品条件まで書きます。担当者が変わっても再現できる基準にし、小さな案件で読み込みと成果物を確認してから、よく使う案件へ実際の結果を見ながら段階的に広げるのが安全です。
目次 (8)
9月18日の告知で何が変わったのか：AGENTS.md対応の事実
2026年9月18日、Claude Code v2.1.277について、同じフォルダに CLAUDE.md がない場合は AGENTS.md を確認して使う対応が告知されました。今回の話の中心は、別の形式へ設定を変換する機能ではありません。プロジェクトの説明を置くファイル名について、これまでClaude Codeで広く使われてきた CLAUDE.md に加えて、条件付きで AGENTS.md も確認対象になったという点です。
この内容はAGENTS.md対応を知らせる公式告知で確認できます。導入前に読むべきなのは、対応したバージョンと、CLAUDE.md がない場合という条件です。「AGENTS.mdを置けば必ず読み込まれる」「どの階層に置いても同じように働く」といった説明は、告知からは導けません。手元のフォルダ構成に条件を当てはめることが必要です。
また、同じ話題の拡張の仕組みに関する補足告知もあります。両方のファイルがある場合にどちらを優先するのか、親フォルダと子フォルダにそれぞれ置いた場合にどう重なるのかは、今回確認できた告知だけで断定しない方がよいでしょう。未確認の挙動をチームの決まりとして配布すると、担当者ごとに受け取り方がずれるためです。
この変更を実務で受け止めるときは、「新しいファイル名が使える」という短いニュースで終わらせないことが大切です。共有ルールの置き場所を増やすと、既存の CLAUDE.md と内容が分かれて更新漏れが起きる可能性もあります。まず現状のファイルを一覧にし、どのツールがどの文書を読む前提なのかを整理してから、案件単位の運用へ進めます。
CLAUDE.md がある場合・ない場合の違いと確認点を整理する
CLAUDE.md と AGENTS.md はどちらもMarkdownで書ける説明文書ですが、同じ意味のファイルとして扱うのは危険です。前者はClaude Codeのプロジェクト指示として長く利用されてきた名前で、後者は複数のAI開発ツールに共通する説明書として知られています。AGENTS.mdを複数ツールで整理した解説でも、ツールごとの文書が分かれると同じルールの重複管理が起きる点が説明されています。
今回の告知は、Claude Codeが CLAUDE.md のない同一フォルダで AGENTS.md を確認する条件を示したものです。したがって、次の表は仕様を広げて断定するためではなく、確認すべき状況を切り分けるために使います。
| フォルダの状況 | まず確認する文書 | 運用上の判断 |
|---|---|---|
CLAUDE.md がある |
CLAUDE.md の内容と更新日 |
既存の指示を基準にし、急いで移動しない |
CLAUDE.md がない |
AGENTS.md の有無と内容 |
告知された条件に当てはまるかを確認する |
| 両方がある | それぞれの位置と内容 | 優先関係を推測せず、小さな変更で確認する |
| 親子フォルダに分かれている | 全階層のファイル | 対象フォルダを固定して結果を記録する |
表の「確認する」は、ファイルを開いて読むだけという意味ではありません。実際に変更を依頼するフォルダを決め、文書に書いた短い識別用の指示が反映されるか、成果物に期待する条件が守られるかまで見る必要があります。確認できないまま「共有できた」と判断すると、書いたルールと実際の結果の差が納品直前に見つかります。
とくに両方のファイルがある構成では、内容を同じにして安心しないことが重要です。片方だけ更新されれば差分が生まれますし、読み込まれる順番が不明な状態で同じ項目に異なる指示を書くと、結果の説明が難しくなります。告知にない優先関係は決め打ちせず、ファイルを一つに寄せるか、役割を明確に分けるかをチームで選びます。
チームの納品基準を一枚の共有文書に落とす具体的な作成方法と更新方法
共有文書の目的は、AIに長い背景を覚えさせることではありません。案件に参加する人が変わっても、最初に確認すべき場所、変更してよい範囲、提出前に見る項目が同じになるようにすることです。文章を増やすほどよいわけではなく、担当者がその場で判断できる具体的な行動へ落とすことが重要です。
たとえば、冒頭には案件の目的と主なフォルダを短く書き、その後に準備、変更、確認、納品の順で並べます。「適切に対応する」「品質を高める」のような抽象語だけでは結果をそろえにくいため、「変更後に何を確認し、どの状態なら提出できるか」まで書きます。既存のREADMEや設計資料と重なる説明は、場所を示して本文の重複を減らします。
共有文書を作る順番
最初から全案件の規則を詰め込むと、読むべき情報が埋もれます。次の順番で最小限の文書を作り、実際の作業で迷った点だけを追記してください。
- 納品物を一文で定義する。 画面、API、帳票など何を提出する案件なのかを書き、対象外の範囲も短く示します。担当者が作業を始める前に、完成の形を想像できる状態にします。
- 作業場所と準備方法を固定する。 変更対象のフォルダ、必要な資料、確認に使うコマンドや画面を列挙します。個人の環境だけにある手順は入れず、別の担当者が再現できる情報に絞ります。
- 変更時の境界を決める。 触れてよいファイル、変更前に相談する領域、互換性を保つ項目を分けます。判断が必要なときの相談先も役割名で書き、特定の人だけに知識が集中しないようにします。
- 確認項目を成果物に結び付ける。 画面なら主要な表示、APIなら入力とエラー、帳票なら数値と出力形式というように、変更内容に応じた確認を指定します。確認した結果を短く残せる欄も用意します。
- 納品条件と差し戻し条件を書く。 必須資料、確認結果、未解決事項の扱いを決め、「何がそろえば提出できるか」を明文化します。未確認のまま提出しない条件も、同じ場所で読めるようにします。
文書の例を作るときは、次のような見出しだけでも十分に始められます。
# Project rules
## Purpose and deliverables
## Project structure
## Change boundaries
## Checks before delivery
## Delivery requirements
見出しの下には、案件固有の事実だけを置きます。担当者個人の好み、短期間だけの連絡事項、外部へ出せない情報は共有文書に混ぜません。内容が変わったら更新日と変更理由を残し、古い手順がまだ有効なのかを後から判断できるようにします。こうした手入れがあって初めて、AGENTS.md は一度作って終わりのファイルではなく、チームの基準を残す場所になります。
なお、CLAUDE.mdとAGENTS.mdの違いを整理した解説が指摘するように、両者の役割を混同しないことが大切です。Claude Code固有の指示と、複数の道具で共通に使いたい説明を同じ段落へ詰め込まず、どの文書に置くべき情報かを一項目ずつ判断してください。
小さな案件で読み込みと成果物を確認するための表の使い方と手順
新しい文書をいきなり重要案件へ適用するのではなく、変更範囲が小さく、結果を人が見比べられる案件で試します。確認の目的は、文書が存在することではなく、作業開始時に必要な指示が参照され、成果物が納品基準を満たし、やり直しの理由を説明できることです。結果を表に残せば、うまくいかなかったときに文書と作業内容のどちらを直すべきか判断しやすくなります。
| 確認段階 | 見ること | 合格の目安 |
|---|---|---|
| 読み込み | 置き場所と対象フォルダ | 想定した文書が確認される |
| 指示の反映 | 命名や変更範囲 | 共有文書に書いた境界を外れない |
| 成果物 | 画面、処理、資料 | 必須項目と形式がそろう |
| 手戻り | 質問と修正の内容 | 同じ確認を繰り返していない |
| 記録 | 日付、対象、結果 | 別の担当者が経緯を追える |
「読み込まれたか」を確認するために、文書へ曖昧な合図を書く必要はありません。たとえば成果物の命名規則、必ず含める見出し、確認時に残す記録など、結果から判断できる項目を一つ選びます。個人の文体や偶然の表現を合図にすると、同じ結果を再現できず、確認そのものが担当者の感覚に左右されます。
小さな案件で試す順番
対象を広げる前に、次の順序で一件を確認します。各段階で問題が出たら、次へ進まず文書の該当箇所を直し、同じ条件で再確認します。
- 対象フォルダを一つに固定する。
CLAUDE.mdとAGENTS.mdの位置、対象となる作業場所、既存の指示文書を記録します。親子関係がある場合は、どのフォルダから作業を始めたかも残します。 - 小さな変更を一つだけ依頼する。 命名変更や短い資料の修正など、結果を目視できる作業を選びます。複数の条件を同時に試すと、どの指示が効いたのか分からなくなるためです。
- 成果物を納品基準と照合する。 変更されたファイル、確認結果、未対応の項目を表へ記入します。文書に書いた条件が守られなかった場合は、読み込み条件と指示の具体性を分けて調べます。
- 質問と修正時間を記録する。 作業前後で同じ説明が何回必要だったか、差し戻しが何件あったかを残します。数字が小さくても、次の案件で比較できる基準になります。
この確認で大切なのは、うまくいった一回だけを根拠にしないことです。別の担当者、別の小さな変更、別の日の作業でも同じ基準を使えるかを見ます。両方のファイルを置く構成を試すなら、ファイルの有無と場所を変えたケースを分け、結果を混ぜないようにします。告知されていない優先関係を推測したまま採用しないことが、後の説明コストを抑えます。
受託開発で利益を守る：手戻りを減らし、知識を残す実務方法と改善方法
受託開発では、作業時間だけでなく確認のやり直しや説明の繰り返しも利益を圧迫します。担当者が変わるたびに同じ構成を説明し、納品直前に命名や資料の不足が見つかれば、見積もりに含めにくい時間が増えます。共有文書はその時間を減らすための基準ですが、長く書くほど効果が出るわけではありません。実際に発生した手戻りを一つずつ、次の担当者が判断できるルールへ変えることが重要です。
まず、案件開始時に納品物と確認項目をそろえます。次に、担当者が作業中に迷った内容を「質問された事実」として記録し、文書へ反映する価値があるかを判断します。すべてを追加すると読む負担が増えるため、複数案件で繰り返す問題、納品品質に直結する問題、誤ると修正範囲が広がる問題を優先します。これなら文書の更新が単なる情報追加ではなく、利益を守るための改善になります。
チーム内の役割分担も、個人名ではなく役割で書きます。たとえば「仕様確認は業務担当」「画面の受入確認は品質担当」「提出判断は案件責任者」のように、誰がどの判断を持つかを明確にします。人が入れ替わっても文書を使い続けられ、特定の人へ質問が集中しにくくなります。相談が必要な項目は、相談のタイミングと渡す情報まで書けば、確認の往復を短くできます。
今回のAGENTS.md対応は、ファイル名を変えるだけの話ではありません。Claude Codeを使う案件で、既存の CLAUDE.md があるのか、ないのか、両方を置くのかをチームで説明できるようにする機会です。対応条件が明示された範囲を守り、未確認の優先関係は小さな案件で確かめる。そのうえで命名、確認、納品の基準を一枚へまとめれば、共有ルールが実際の作業と利益に結び付きます。
