agent-config

使用するタイミング

コーディングエージェントがセッションごとに読み込む指示ファイルを作成、更新、または監査します。AGENTS.md がデフォルトの出力先です。これは Claude Code（v2.1.277+）、Codex、Cursor、Copilot などが読み込むオープン標準です。CLAUDE.md を出力するのは、ユーザーが「CLAUDE.md を作成して」「CLAUDE.md に X を追加して」のように、明示的に作成または編集を依頼した場合に限ります。ソースとして名前を挙げただけでは該当しません（「既存の CLAUDE.md を AGENTS.md に移行して」）。また、ディスク上にすでに CLAUDE.md が存在する場合も該当しません。README やコントリビューター向けドキュメント、スキル（skill-creator）、.claude/agents/ 配下のサブエージェントファイルは対象外です。

基本原則

これらのファイルは強制される設定ではなく、コンテキストです。毎セッション読み込まれますが、エージェントが指示から逸脱する可能性はあります。

• エージェントが推測できない、短く常時適用される事実をファイルに記載します。
• 複数ステップの手順はスキルに記載します。決して発生させてはならないことは、権限とともに PreToolUse フックに記載します。作業の検証はテストまたは CIで行います。
• **完全さより最小限にすることを優先します。**エージェントはファイルに記載されたすべてのコマンドを実行し、すべてのルールに従うため、行を追加するたびに、すべてのタスクで手順とトークンが増えます。リポジトリの内容を言い換えた LLM 生成ファイルでは、成功率が向上しないままコストが約 20%増加しました。このスキル自体がそのようなファイルを作成する LLM であるため、新しい内容を追加する際は、Step 3 の削減処理を必ず実施します。

指示を管理するレイヤーについては、references/knowledge-routing.md を参照してください。読み込み規則と情報源については、references/official-standards.md を参照してください。

前提条件

• 書き込みを行う場合は、origin が設定された Git リポジトリが必要です。audit には読み取りアクセスのみ必要です。
• ツール：git、および対象パスへの書き込みアクセス。

モード選択

$ARGUMENTS

• audit：ユーザーが audit、「レビュー」、「確認」と指定した場合です。読み取り専用です。
• write：それ以外の場合です（create、update、特定の変更、または packages/api/AGENTS.md のようなパスの指定）。

すべてのモードで、まず Step 1 を実行します。Step 1 の後、既存ファイルに対する具体的な変更をユーザーが指定している場合、write は対象を絞った編集になります。それ以外は全体の見直しです。write は Step 2〜4 に進み、audit は監査に進みます。

編集前のリポジトリ同期（必須）

write で変更を加える前に、リモートと同期します。audit ではこの手順を省略します。git fetch は読み取り専用のドライランです。

branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin                       # dry-run: read-only preview
git status                             # validate clean tree
git pull --rebase origin "$branch"     # only once the tree is clean

作業ツリーに変更がある場合は、git stash push -u -m "pre-sync-backup" でバックアップしてから同期し、その後 git stash pop を実行します。次のいずれかが発生した場合は、同期を省略してよいかユーザーに確認するため、処理を停止します。ディレクトリが Git リポジトリではない、origin がない、HEAD がデタッチされている、ブランチにアップストリームがない、pull または rebase に失敗する、または pop に失敗する場合です。ユーザーが同期の省略を許可しない場合は、何も書き込まず、最終レポートを BLOCKED として終了します。既存のエージェントファイルは、読み込んで差分を提示するまでは決して上書きしないでください。

ステップ 1：対象を特定する（すべてのモード）

1. 出力先はリポジトリのルートにある AGENTS.md、またはユーザーが指定したパスです。明示的に依頼された場合に限り CLAUDE.md にします（「使用するタイミング」を参照）。

2. シャドウチェック。 デフォルトでは、起動ディレクトリまたはその親ディレクトリに CLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.md が存在しない場合に限り、Claude Code は AGENTS.md を読み込みます。~/.claude/CLAUDE.md は対象外です。サブディレクトリの AGENTS.md は、そのディレクトリに独自の CLAUDE ファイルがない場合に限り読み込まれます。対象となるファイルはどれも AGENTS.md をシャドウします。リポジトリのルートから、ルートより上とリポジトリ内にある CLAUDE ファイルを一覧表示します。

   root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"; d="$(dirname "$root")"
   while :; do for f in CLAUDE.md .claude/CLAUDE.md CLAUDE.local.md; do p="$d/$f"
     { [ -e "$p" ] || [ -L "$p" ]; } && [ "$p" != "$HOME/.claude/CLAUDE.md" ] && echo "ABOVE-REPO $(ls -l "$p")"
   done; [ "$d" = / ] && break; d="$(dirname "$d")"; done
   find "$root" \( -name node_modules -o -name .git \) -prune -o \( -name CLAUDE.md -o -name CLAUDE.local.md -o -name AGENTS.md \) -print |
     while read -r p; do ls -l "$p"; grep -qE '^@(\.\.?/)*AGENTS\.md' "$p" 2>/dev/null && echo "  -> imports AGENTS.md" || true; done
   

3. 見つかった CLAUDE ファイルをすべて分類します。それぞれに個別の対応を行います：

ファイル	対応
リポジトリのルートより上（例：~/CLAUDE.md）	編集しません。 そのファイルが下位のすべてのリポジトリで AGENTS.md をブロックすることを警告し、内容を対象外の ~/.claude/CLAUDE.md に移すよう提案します
CLAUDE.local.md	編集しません。 そのファイルが対象のリポジトリで Claude に AGENTS.md を読み込ませないことを警告します。最初の行に @AGENTS.md を追加するか、/config → Project instructions → claude-md-and-agents-md を使うよう提案します。この設定はユーザーごとに適用され、プロジェクト設定では無視されます
AGENTS.md へのシンボリックリンク	対応不要です。Edit と Write はシンボリックリンク経由での書き込みを拒否するため、リンク先に書き込みます
すでに AGENTS.md をインポートしている	そのまま維持し、Claude 専用の行だけを残します
リポジトリ内にあり、インポートがない	移行します：共通ルールを AGENTS.md に移し、ファイルにはインポートと Claude 専用の行だけを残します。インポートパスはファイルからの相対パスです。そのため .claude/CLAUDE.md では @../AGENTS.md を使います

4. 分岐を選びます：
   • wrapper：ユーザーが両方のファイルを依頼した場合。
   • claude-only：CLAUDE.md が明示的に依頼されていて、AGENTS.md が存在しない場合。
   • wrapper：CLAUDE.md が明示的に依頼されていて、AGENTS.md が存在する場合。CLAUDE.md はインポートと Claude 専用の行で作成し、依頼がない限り AGENTS.md には手を加えません。
   • migrate：リポジトリ内の CLAUDE ファイルを移行する必要がある場合。
   • agents-only：それ以外すべての場合。

Claude 専用の行とは、プランモード、/commands、スキル、フック、サブエージェント、MCP ツールなどの Claude Code 機能に関する記述です。すでに存在する、または依頼された CLAUDE ファイルに残します。それ以外の場合は .claude/rules/<topic>.md に記載します。このファイルは AGENTS.md とともに読み込まれ、シャドウしません。これらを置くためだけに CLAUDE.md を作成してはいけません。

ユーザーから AGENTS.md が読み込まれていないと報告され、シャドウチェックで問題が見つからなかった場合は、内容を書き換える前に環境を確認します：claude --version（v2.1.277 以降）、/config の Project instructions の値、および agents-md プラグインが有効かどうか（official-standards.md → Claude Code）。

完了時には、出力先のパス、選択した分岐、各 CLAUDE ファイルへの対応、シャドウチェックの生の出力を示します。

ステップ 2：プロジェクトを分析する（全体を確認）

エージェントが誤認する可能性のある情報だけを収集します：

• コマンド：マニフェストと CI（package.json のスクリプト、pyproject.toml、Makefile、.github/workflows/*）から、インストール、開発、テスト全件 および 個別実行、リント、型チェックのコマンドを、CI で使用されるフラグとともに確認します。
• 固定バージョン：推測が間違いにつながる場合は、パッケージマネージャーとランタイムのバージョンを確認します（npm ではなく pnpm）。
• 境界：生成物、ベンダー提供物、シークレットのパス、および事前に人間の対応が必要な操作。
• 既存のルール：エージェント用ファイル、.cursor/rules/、.cursorrules、.github/copilot-instructions.md にあるルールを確認します。現在も有効なものは維持し、それらのファイルはそのまま残します。

記載するすべてのコマンドをファイルから確認できた時点で完了です。マニフェストや CI でコマンドが定義されていない場合は、そのコマンドを記載せず、ユーザーに確認してください。決して推測してはいけません。

ステップ 3：草案の作成

対象を絞った編集では、依頼された変更を行い、トークン効率化ブロックがなければ追加し、それ以外は何も変更しません。一般的なワークフロー、コーディング規律、またはユニットテストのルールに関する依頼には、references/optional-blocks.md の該当ブロックで対応します。その他の削除候補はレポートに列挙しますが、適用はしません。全体の見直しでは、まず references/agents-md-writing.md を読んでください。テンプレート、執筆ルール、それらを裏付ける根拠が記載されています。その後、次の手順に従います。

1. テンプレートを埋めます。 Commands、Constraints（Never と Ask first）、Done when は必須です。Project、Layout、Conventions、Read when needed は、エージェントが推測できない事実がある場合にのみ記載します。
2. 削除パスを実施します。 削除判定の問い（「これを削除すると、具体的な間違いが起きるか？」）を満たさない行はすべて削除します。また、概要、ディレクトリツリー、依存関係の一覧、README の言い換えも削除します。ファイル内にすでにあるオプトインブロックは残します。Claude 専用の行は、ステップ 1 で指定された場所に移します。
3. references/optional-blocks.md のオプトインブロック（ワークフローのオーケストレーション、コーディング規律、ユニットテスト）は、ユーザーが求めた場合にのみ追加します。
4. 最後にトークン効率化ブロックを追加します（以下を参照）。

残ったすべての行が、コマンド、固定事項、制約、または参照先になると完了です。

ステップ 4：記述と検証

• 書き込む前に提示します。 新規ファイルの場合は草案を提示します。既存ファイルの場合は差分を提示します。ユーザーの承認後、または依頼ですでに変更の適用が指示されている場合はすぐに書き込みます。ユーザーが拒否した場合は何も書き込まず、最終レポートを BLOCKED として終了します。
• 検証します。チェックに失敗した場合はファイルを修正し、そのチェックをもう一度実行します。それでも失敗する場合は、Result: FAIL とチェック名を示してステップ 4 を終了します。
  • 各ファイルの wc -l が 200 未満であること。
  • grep -c '^## Token Efficiency' が、正本では 1 を、それ以外のすべての場所では 0 を返すこと。
  • 各ラッパーの 1 行目が AGENTS.md のインポートであること。
  • シャドウチェックを再実行した際に、リポジトリ内で AGENTS.md をシャドウする CLAUDE ファイルがないこと。
• 読み込みを確認する方法を報告します。 Claude Code v2.1.280 以降では、/memory に AGENTS.md が表示されます。Codex では、codex --ask-for-approval never "Summarize the current instructions." を実行します。AGENTS.md を読み込めないクライアントでは、@AGENTS.md を記載した 1 行だけの CLAUDE.md が必要です。対象は Claude Code v2.1.277 より前のバージョンと、一部の Bedrock セッションまたはテレメトリー無効セッションの v2.1.281 より前のバージョンです。このファイルは提案しますが、依頼されない限り作成しません。

監査（読み取り専用）

1. シャドウやドリフトは一連のファイルを横断して確認して初めて見つかるため、以下をまとめて読みます。
   • AGENTS.md
   • シャドウチェックで見つかったすべてのファイル
   • AGENTS.override.md があればそのすべて
   • フックを確認するための .claude/settings.json と .claude/settings.local.json
2. references/agents-md-checklist.md に沿って確認し、各項目を合格、不合格、または該当なしとして、理由を 1 行で報告します。読み込みのセクションでは、インポートせずにシャドウする CLAUDE ファイル、Claude に「AGENTS.md を読む」よう指示する文章、AGENTS.md を出力する SessionStart フック、Codex が代わりに読み込む AGENTS.override.md を検出します。
3. references/anti-patterns.md と照合します。
4. 適切な場所に振り分け、適用します。 不合格となった行ごとに、references/knowledge-routing.md に基づいて適切な場所を示します。機械でチェックできるルールにはゲートを設け、同時にその文章を削除します。
5. 何も変更しません。git status が変更なしであることを確認します。監査レポートの Result: 行に全体の判定（PASS、PARTIAL、または FAIL）を記載します。読み込まれた内容を確認するには /memory を、再確認には /doctor prompt-audit（v2.1.283 以降）を提案します。

Token Efficiency Block（常に挿入）

references/token-efficiency-block.md のフェンス付きブロックを、source-of-truth ファイルの最後のセクションとして一度追加します。source of truth はルートの AGENTS.md、または claude-only ブランチでは CLAUDE.md です。このブロックをラッパー、ネストされたパッケージファイル、.claude/rules/ ファイルに追加してはいけません。これらはルートファイルとともに読み込まれるため、二つ目のコピーを置くと重複します。これは、依頼がなくても追加する唯一の一般的なアドバイスです。エージェントがコンテキストウィンドウを使う方法について、常時適用されるルールです。必須事項：source of truth にブロックがない場合は、対象を絞った編集も含め、すべての書き込み実行で追加し、レポートにその旨を記載します。唯一の例外は wrapper ブランチです。ブロックを追加するためだけに、すでに存在する AGENTS.md を編集してはいけません。代わりに、ブロックがないことを報告します。

ステップ完了レポート

各ステップの後に、次を出力します。

◆ [Step Name] ([step N of M])
··································································
  [Check 1]:          √ pass
  [Check 2]:          × fail — [reason]
  [Criteria]:         √ N/M met
  ____________________________
  Result:             PASS | FAIL | PARTIAL

合格には √、不合格には × を使います。各ステップに合わせてチェック名を調整します。

最終レポート

早期終了する場合も含め、実行の最後には必ず references/final-report.md の最終レポートを出力します。順序は、最初に Result:（COMPLETE、PARTIAL、または BLOCKED）、続いて Evidence:、Uncertainty:、Decision: です。各ステータスの定義と、読み手による確認項目は同ファイルに記載されています。

受け入れ条件

• ブランチ、各 CLAUDE ファイルに対する処理、および shadow-check の出力が示されている。
• CLAUDE.md の明示的な依頼がない場合、新しい CLAUDE.md は作成されていない。
• 実行後、リポジトリ内のすべての CLAUDE ファイルが AGENTS.md をインポートしているか、同ファイルへのシンボリックリンクになっている。リポジトリ外のファイルと CLAUDE.local.md は編集されておらず、ユーザーへの警告も行われている。
• リポジトリが同期されているか、同期を省略することがユーザーによって明示的に許可されている。
• wrapper ブランチでブロックがないことを報告する場合を除き、token-efficiency ブロックは source of truth にちょうど一度だけ記載されている。
• source-of-truth ファイルは200行未満で、references/agents-md-checklist.md のセクション1～3および5～7に合格している。ラッパーとルールファイルは、セクション1～3および6に合格している。
• AGENTS.md と CLAUDE ファイルに重複するルールがない。
• 新しい内容に references/anti-patterns.md のアンチパターンが含まれていない。
• ファイルを書き込んだ書き込み実行では、ステップ4の最後に Result: PASS と記載されている。監査実行では、すべてのチェックリスト項目を報告し、不合格となった各行の振り分け先を推奨し、git status を変更せず、総合判定を示している。
• すべての実行の最後に最終レポートがあり、references/final-report.md の読み手による確認項目に合格している。ユーザーからのフィードバックがない場合、レポートが人に理解されたかどうかは未確認のままとする。

期待される出力

ブランチ	実行後のファイル
agents-only	AGENTS.md：Commands、Constraints、Done when、任意のセクション、その後に ## Token Efficiency
migrate / wrapper	上記の AGENTS.md に加え、各 CLAUDE ファイルは @AGENTS.md のインポートと Claude 専用の行だけに縮約
claude-only	全内容と token ブロックを含む CLAUDE.md
audit	書き込みなし。振り分け先と Result: PASS、PARTIAL、または FAIL の判定を含むチェックリストレポート

すべてのブランチで、その後に最終レポートを出力します。サンプルファイルは references/agents-md-writing.md に、監査レポートのサンプルは references/agents-md-checklist.md に、最終レポートのサンプルは references/final-report.md にあります。

エッジケース

• モノレポ：ルートファイルが肥大化する場合は、パッケージごとに AGENTS.md を配置することを優先してください。Codex とほとんどのエージェントは、最も近いファイルを優先します。Claude はルートファイルに加えて、必要に応じて各サブディレクトリのファイルを読み込みます。また、CLAUDE ファイルが同じディレクトリ内の AGENTS.md より優先されます。編集する範囲を確認してください。
• Claude に AGENTS.md を読むよう文章で指示する CLAUDE ファイル、またはその内容を貼り付けたファイル（/init または /import によるもの）：インポートがないため、移行してください。
• AGENTS.override.md または AGENTS.local.md の作成依頼：Codex はそのディレクトリの AGENTS.md の代わりに AGENTS.override.md を読み込み、Claude はどちらも読み込みません。作成する前に、その点を伝えてください。
• 個人用ファイル（~/.claude/CLAUDE.md、~/.codex/AGENTS.md）：監査と提案のみ行ってください。リポジトリのスコープに限定された実行で、個人用ファイルを書き換えてはいけません。
• 複数ステップの手順：本文にそのまま記載しないでください。スキルを提案し、1 行の参照だけを残してください。
• 200 行を超えるドラフト：パスのスコープを限定するか、手順をスキルに切り出すか、リンク先を用意してから書き込んでください。