Articles

AGENTS.md/CLAUDE.md、全文公開

Published: 2026-08-06 · First published on X

シリーズ「増幅と掃除」: 第一部 · 第二部 · 第三部 · 第四部

AGENTS.mdやCLAUDE.mdに何を書けばいいかと聞かれることが増えたので、説明するより見てもらうほうが早いと思い、私が全プロジェクト共通で使っているグローバルのAGENTS.mdを全文公開します。ホームディレクトリに置いてあり、どのリポジトリで作業するときも読み込まれる、いちばん土台のファイルです。実物の末尾にはCodex固有の運用節が数行ありますが、ツール依存の話なので本稿では省き、共通部分を掲載します。

全文

# 共通ルール

## 基本方針

- 日本語で応答すること
- MCP サーバーよりも CLI ツールの利用を優先して検討すること

## 実装と検証

- 実装前に、仮定・不明点・複数解釈・重要なトレードオフを明示し、仕様・契約・データ形式などの永続判断は既存実装・テスト・文書・ユーザー確認に基づかない限り作らず、不足時は仮実装・仮差分・コード例を提示せず確認事項と検証計画に留めること
- 要求を満たす最小の実装を優先し、依頼されていない機能・抽象化・設定項目・将来対応を追加しないこと
- 既存コードや文書を編集するときは、ユーザー依頼に直接必要な行だけを変更し、隣接する無関係なリファクタ・整形・削除を行わないこと
- 作業の成功条件を検証可能な形で定め、バグ修正や機能追加では再現・テスト・差分確認などの具体的な確認手段まで含めて完了判断すること
- 再現テストを書くときは、観測済みの失敗と既存契約だけを固定し、未確認の戻り値・エラー型・出力形式を新しい期待値として作らないこと

## Secret 管理

- secret 実値を 1Password の外へ出さないこと。コード・設定ファイル・ログ・チャット出力に書かず、CLI での受け渡しは `op://...` secret reference 経由とすること

## 指示の永続化と反映先

- 永続的に参照すべき指示や、worktree / セッションをまたいで再現が必要な情報は、Memory ではなく git 管理ファイル（作業リポジトリの `docs/`、`.agents/`、またはグローバル dotfiles。例: `~/.codex/AGENTS.md`）に保存すること
- 恒久性のあるユーザー指示、再発しやすい運用判断、複数回参照しそうな手順は、原則その作業ターン内で git 管理ファイルへ反映すること
- 反映先は、運用ルールや判断基準なら現在作業中のリポジトリの正規指示ファイル（通常は `AGENTS.md`）と AI 別指示ファイル、背景や継続判断なら `docs/adr/`、反復手順や更新フローなら対応 Skill を使い分けること
- 反映を見送る例外は、一過性の事情、既存文書との重複、ユーザーの明示的な文書化不要指示に限り、見送った理由を作業結果に残すこと

## 一時ファイルと受け渡し

- 一時ファイル、下書き、調査メモなどの一過性ファイルは作業 worktree 内の `.context/` に生成し、`/private` や `/tmp` を一時ファイル置き場として使わないこと
- AI 間や CLI 間で複数行や構造化された内容を受け渡すときは、作業 worktree 内の `.context/` に置いた実ファイル経由を標準とし、`-p` などの引数へのインライン展開や here-doc 直書きを避けること。パイプは単一コマンドが標準入力をただちに 1 回だけ読む単発処理に限ること

## スクリプト運用

- 長時間実行や外部通信を伴うスクリプトには、開始・反復・リトライ・完了・失敗を判別できる進捗ログを必須とし、静かな成功や無出力に見える待機を作らないこと。ログには秘密情報を含めず、再実行判断に足る情報を含めること
- script / skill に、主経路の失敗原因を隠す暗黙 fallback を追加しないこと。代替経路が必要な場合は目的・発動条件・観測ログ・再実行時の挙動を明示し、安定した代替経路は fallback ではなく主経路へ昇格すること。同等性と選択条件が明示された冗長 provider（同一データへの複数 RPC / mirror / replica 等）は例外とする

## 外部サービス境界とエラー対応

- 外部サービスへの作成・更新・削除・送信・承認・共有・権限変更では、失敗や権限エラーを別 principal / 別 company / 別 profile への自動切替で回避しないこと。読み取り診断でも自動切替はせず、必要なら principal を明示して再実行し、解消しなければ停止してユーザーに確認すること
- コマンドやツールのエラーは、失敗と断定する前に意味（一致なし、context 不一致、path 不存在、conflict / dirty state、検証 failure 等）で分類し、原因を確認してから続行すること
- エラーへの一時的な迂回は許容するが、同種エラーの再発、検証省略、環境・設定・権限・依存の不備、再現性低下が絡む場合は恒久対策レビューの対象とし、原因・一時迂回・恒久対策・git 反映対象・検証方法を分けて整理すること

## 委譲

- 調査、レビュー、設計評価、事業判断、秘書的整理、恒久対策レビューなど役割を切り出せる作業は、role-appropriate なサブエージェント、custom agent、runner へ積極的に委譲してよいこと。複数モデルの使い分け自体を目的にしないこと
- 委譲するときは、親 Agent が目的、背景、対象範囲、制約、許可する副作用、期待成果物、検証方法を明示し、委譲先は親の context を暗黙に継承しない前提で、委譲先の定義（description）が求める入力契約に従うこと。委譲先が利用できない場合は、委譲したものとして扱わず、理由と代替方針を明示すること
- 委譲先に secret 実値、認証情報、secret reference 自体とその解決結果、認証済みセッション情報を扱わせないこと。親が secret 閲覧を許可されていても、委譲先への共有許可とは扱わないこと
- 委譲先の判断は渡した context に基づく限定判断として扱い、親は既存実装・設定・文書・テストへ戻って妥当性を確認し、最終判断・統合・ユーザーへの報告責任を保持すること
- 複数 AI の出力を比較・相互レビューさせる場合は、独立評価が完了するまで作成者情報（モデル、provider、agent、所有関係）を伏せ、`Report A` / `Report B` などの安定した中立ラベルで渡すこと。ラベルと作成者の対応は親が別途保持し、作成者情報自体を評価する場合は匿名評価と別 Phase で扱うこと

## Skill / Runner 運用

- 外部 CLI / MCP / runner / Skill の詳細な運用ルールは、作業中リポジトリに正規 docs / Skill がある場合はそちらを優先すること
- 新しい永続的な Skill / Runner / wrapper を作る前に、既存 docs / Skill / wrapper / runner adapter で足りるか確認すること

## Artifact gate

- Phase / Step を持つ作業では、対応する中間成果物 artifact を `.context/` へ保存してから次の Phase / Step へ進むこと。口頭合意、推論上の完了宣言、Memory 内だけの状態遷移で進めてはならない
- artifact の初期必須項目は `task`、`phase_or_step`、`created_at`（Markdown は Front Matter、JSON は同名キー）とし、命名は `.context/<task-or-date>/<nn>-<phase-name>.(md|json)` を推奨すること
- Plan や依頼で Phase / Step が明示されない作業は非 Phase 作業として扱い、artifact 必須対象外とする。単発例外として artifact gate を明示的にバイパスする場合だけ `.context/single-step/<task>.json` を使い、`enabled=true`、`task`、`reason`、`expires_at` を必須とすること
- Phase / Step 遷移の最小原則は現在作業中のリポジトリの正規指示ファイル（通常は `AGENTS.md`）を、各 Skill 固有の required artifact は `SKILL.md` を正本とすること。競合時は `SKILL.md` をその Skill 実行中の具体契約として優先し、正規指示ファイルは下限ルールとして常に適用すること

## Markdown / ADR 運用

- `*.md` ファイルを編集した際は、ファイル全体を見直し、矛盾・重複・ルール漏れがないか確認し、必要なら同じターンで修正すること
- `*.md` ファイルのメタデータは本文に書かず、必ず Front Matter で管理すること
- アーキテクチャ、運用方針、永続設定、複数ファイルにまたがるワークフロー変更などの大きめの変更では、作業リポジトリの `docs/adr/` に ADR を作成・更新し、作業日時と作業した Agent のモデル名を記載すること

# Plan 共通ルール

- Phase を含む Plan では、各 Phase ごとに使用する Skill を明示し、使用しない Phase は `なし` と明記すること
- Phase を含む Plan は、実行時に途中確認を前提にせず完走できる粒度で提示し、Phase 提示後は不測の事態がない限り追加許可を求めず停止せず最後まで進めること。ただし、既存 Skill や repo ルールで明示された事前確認は例外として維持すること

CLAUDE.mdは、このAGENTS.mdをimportするのみでAgentの差異を設けないようにしています。以下、本文の表記はAGENTS.mdに統一します。

@~/.codex/AGENTS.md

AGENTS.mdは、コーディングエージェントへプロジェクトの前提を渡す共通フォーマットで、Codexなどが直接読み、Claude CodeでもCLAUDE.mdからimportして共用できます。目的だけ与えてAIを自走させる使い方が広がるほど、タスクのたびに会話で渡す指示は減り、AIに毎回渡る指示はAGENTS.mdとその参照先だけになっていきます。つまりこのファイルの書き方は、AIの自走品質にそのまま効きます。「AIに任せる」とは、会話ごとに渡していた指示をAGENTS.mdと正本群という常設の仕組みへ前払いすることでもあり、タスクの数で償却される固定費なので、繰り返しが多いリポジトリほどこの投資は効きます。

私の環境でも繰り返し指示のたびにルールは増え続けてきましたが、それでも守られないルールは守られない。試行錯誤の結果としてこの形に落ち着いた理由を、書き方のTips 7つとして説明します。読者は、AGENTS.mdやCLAUDE.mdを書き始めたエンジニアと、チームの規約を整備するテックリードを想定しています。

Tipsはばらばらの小技ではなく、根は一つです。AGENTS.mdはAIへの説明書ではなく、次のAI出力を条件づける入力である。まずこの性質から押さえます。

書いたものは増幅される

AIに小さな機能追加を頼むと、既存コードから似た実装を探してその形に合わせて差分を作るので、プロジェクト固有の命名やレイヤーを毎回説明しなくても周囲のコードから推測してくれます。これが速さの源泉ですが、参照された既存コードが急場のworkaroundだった場合、AIは事情を知らないまま標準パターンとして別の場所へ展開します。

急場の workaround
  ↓
AI が標準パターンとして模倣
  ↓
複数箇所へ展開
  ↓
test が現在の挙動を固定

ルールも同じ経路をたどり、AGENTS.mdに書かれた記述は、良いものも古いものも矛盾したものも、等しく次の出力の前例になります。従来の技術的負債は将来の変更コストでしたが、AIが継続的に読む環境では、次の生成へ複製される負債が加わります。

AGENTS.mdはこの増幅の入口に置かれたファイルなので、書き方の問いは、何を書けば伝わるかではなく、何が増幅されてよいかになります。以降のTipsはすべてここから導いたものです。

1. ハブにして、全集にしない

AGENTS.mdはセッションのたびに読み込まれ、長くなるほど1行あたりの注意は薄まり、私の環境では、コンテキスト圧縮の際に落ちやすくもなります。CLAUDE.mdを索引にする話は前作に書きましたが、AGENTS.mdでは増幅の理由が加わります。長い全集は矛盾を抱え込みやすく、矛盾ごと増幅されるからです。

置くのは、全Agentが常に守る短い不変条件と、正規文書への入口だけにします。冒頭の全文に手順書やプロジェクト固有の事情がないのはこのためで、手順はSkillへ、プロジェクトの事情は各リポジトリの文書へ行き先があります。プロジェクト側のAGENTS.mdはさらに薄くなり、そのリポジトリのRuleやSkillへの入口、つまりリンク集が本体になります。ハブを意志だけで保つのは難しいので、私が運用する別のリポジトリでは、入口ファイルごとの行数上限をvalidatorで固定しています。AGENTS.mdは60行、docsの索引は100行という粒度です。常時読み込まれる文書の総量も予算として定点観測していますが、こちらは超過で機械的に止めず、肥大化の観測指標に留めています。上限で止めるのは入口だけ、総量は観測だけ、という線引きです。

2. 現在形だけを書く

「以前はRESTだったが、現在はgRPCを使う」という書き方は、旧方針への言及そのものが前例として読まれます。AGENTS.mdには現在の正解だけを置き、そう決めた理由や却下案はADRへ、生の変更履歴はGit logへ分けます。

通常の作業は現在の記述だけで判断できる状態が望ましく、理由不明の制約やregressionを調べるときだけ履歴へ遡ります。履歴から得た説明が現在のルールと矛盾するなら、過去を採用するのではなく、現在の正本に不足があると判断します。履歴を捨てるわけではありません。理由の分からない制約に出会ったAIがgit logやADRへ遡って調べること自体は健全で、問題なのは、通常作業の入力に履歴が常に混ざっている状態のほうです。

3. 書かないことを決める

会話でAIに伝えたことをすべてAGENTS.mdへ書きたくなりますが、意図には種類ごとに適した行き先があります。

AGENTS.mdに残るのは、この表のどれでもないもの、つまり全Agentが毎回守る不変条件と、上の正本群への入口だけです。逆に、どこへも書かれなかった意図はセッション終了とともに消え、次のAIは残ったコードから意図を推測することになります。

表の中で見落とされがちなのがIssue trackerの行です。未完了のタスクをAGENTS.mdやREADMEのTODOとして書きたくなりますが、終わったTODOが消されずに残ると、それ自体が古い前例になります。未完了の作業は期限と担当を持てるIssue trackerに置き、文書には現在の正解だけを残します。

4. 例外には範囲と解除条件をつける

例外はいちばん増幅されやすい記述で、「このモジュールでは直接SQLを書いてよい」とだけあると、次のAIはそれを標準の選択肢として読みます。だから例外には、理由、適用範囲、解除条件をセットで書きます。

- orders モジュールに限り直接SQLを許可する
  (ORM が複合キーに未対応のため。対応後にこの項目ごと削除)

解除条件まで書いてあれば、条件が満たされた時点でAI自身に削除を提案させることもできます。無条件の例外は、書いた瞬間から標準へ昇格し始めると考えたほうがよいです。例外が別の場所へ増えたときも件数を昇格の根拠にはせず、昇格させるかどうかはSpec側の判断とします。増えた例外はむしろ、元の制約がまだ解消されていないことを示すシグナルです。解除条件を構造化した形で書いておけば、期限切れの例外をvalidatorで検出して失効させるところまで機械化できます。例外は書いた本人の記憶より長生きするので、消す仕組みは書く時点で仕込んでおくのが確実です。

5. 失効したルールを消す

追記だけで運用されたAGENTS.mdは、時間とともに矛盾集になります。矛盾した指示を渡されたAIはエラーにならずに都合のよい方を選び、どちらが選ばれるかはタスク次第なので、挙動が安定しない形で現れます。

ルールの変更は、新しいルールの追加と古いルールの削除で1つの変更です。私は「*.mdファイルを編集したら、ファイル全体を見直して矛盾・重複・ルール漏れを確認する」というルール自体を、このファイルに入れています。冒頭の全文の、Markdown / ADR 運用の節にその行があります。消す作業をAIに促す仕掛けまで含めて、このファイルの設計のうちです。

6. 書くだけでは守られない

自然言語のルールは忘却、誤読、都合のよい解釈をされるもので、何度言っても守られないルールを太字にしてもあまり変わりません。守らせたい不変条件は、層を分けて機械検査へ落とします。

この構造は、OpenAIが説明するCodex harnessや、Anthropicの長時間Agent向けharnessの解説とも重なります。ただし、意味の判断までvalidatorへ押し込むと、今度はルールの保守が開発を圧迫します。機械で止めるのはリンク切れや禁止パターンのような検出可能なものに絞り、妥当性の判断はreviewと人間に残す線引きが運用しやすいはずです。

この表に載らない執行上の注意がもう一つあります。AIは、自分が守るべきルールやテストそのものを書き換えられます。実装を通すためにassertionが緩められていないか、失敗するテストが消されていないか——Specやテストの変更には、コードの変更とは別の目を通すことです。自分の審判を自分で書き換えられる構造は、自走させるほど効いてきます。

7. コールドスタートで試す

良いAGENTS.mdかどうかは、読み返しではなく実験で判定できます。新しいセッションを開き、会話履歴なしで代表的なタスクを頼み、AGENTS.mdとその参照先だけで完了できるかを見ます。途中で口頭の補足が必要になったなら、その補足こそが、どこかへ書かれるべきだったものです。コールドスタートは受け入れテストであると同時に測定でもあり、目的だけ与えて自走させる使い方ではAIは毎回この条件から立ち上がるので、成功率はそのまま、そのリポジトリにどこまで自走を任せられるかの見積もりになります。

同じ補足を2回した時点で、ルール化を検討する合図になります。冒頭の全文にも、恒久性のあるユーザー指示は原則その作業ターン内でgit管理ファイルへ反映する、という趣旨の行があり、この反映自体をAIの義務にしています。

全文を読み直す

Tipsが出そろったので、冒頭の全文をセクションごとに読み直します。1行ずつの注釈ではなく、それぞれの塊がなぜ必要で、どう効くのかの答え合わせです。連作で書いてきた、蓄積は待っても直らず掃除が要るという話が、ファイルのあちこちに実装として埋まっています。なお、この答え合わせは読み返しで書いたものではありません。Tip 7の方法どおり、この全文だけを読ませた白紙のAI複数に各セクションが想定する状況のタスクを与え、ここに書いた挙動が実際に出ることを確認してあります。条件だけ書いておくと、掲載ルールだけを与えた新規セッションに、過剰実装への誘惑、チャットに貼られたsecret、権限エラーと別アカウントの誘惑、Phase付きのPlanといった状況を仕込んだ課題を解かせ、各セクションの想定挙動がすべて出ることを確認する形です。

基本方針 — 毎ターン適用される既定値です。応答言語のような、モデルやセッションが変わるたびに揺れる項目は、土台で1回だけ固定します。CLI優先は観測可能性の選択で、CLIは引数と終了コードとログが残るので、AIが何をしたかを後から検証できます。

実装と検証 — AIの失敗の多くは能力不足ではなく過剰性で起きます。頼まれていない永続判断を作る、頼まれていない機能を足す、隣の行を善意で直す。前半の3本はこれを止める行です。後半の2本は完了の定義で、成功条件を検証可能な形に固定し、再現テストには観測済みの失敗だけを固定させます。Tip 6で触れた、自分の審判を自分で書き換える問題への事前の手当てでもあります。

Secret 管理 — 1本だけなのは、境界が単純なほど守られるからです。実値は保管庫(私の場合は1Password)の外へ出ない。動いてよいのはop://参照だけ。チャット出力への記載を名指しで禁じているのは、AIとの会話ログが新しい漏洩経路になったためです。保管庫の名前以外は特定ツールに依存しない書き方なので、CLIやエージェントが入れ替わっても失効しません。

指示の永続化と反映先 — この連作の主張をいちばん直接に実装している塊です。セッションの記憶は次のAIの入力になりません。git管理ファイルだけがなります。だから恒久的な指示はその作業ターン内に反映し、反映先は種類で使い分け(Tip 3の表はこの行の展開です)、見送るときは理由を残します。反映を気づいたときの善行ではなく毎ターンの義務にしているところが要点で、Tip 7で引いた行もここにあります。

一時ファイルと受け渡し — 消してよいものの置き場を先に決めておく、という掃除の設計です。中間状態は.context/の1箇所に集まり、システムの/tmpへ散りません。AI間の受け渡しをファイル経由に固定しているのは、引数へのインライン展開はエスケープや切り詰めで壊れやすく、壊れたことが観測できないためです。ファイルなら残り、検証できます。

スクリプト運用 — 2本とも「観測できない失敗を作らない」と読めます。進捗ログのないスクリプトは、実行中とハングを区別できません。暗黙のfallbackは失敗を成功に見せます。成功に見えた失敗は直されないまま、冒頭の機構に乗って前例として増幅されます。

外部サービス境界とエラー対応 — 1本目は、権限エラーを別のアカウントやprofileへの切替で回避しない、というハード境界です。サービス名を挙げていないのは、固有名詞の列挙が「名指しされていないものは対象外」という逆読みを誘発するからで、抽象化した原則のほうが名指しのないサービスにも拘束が及びます。続く2本は、エラーを失敗と断定する前に意味で分類すること、同種エラーの再発は個別対処で終わらせず恒久対策として扱うこと。再発をルールと環境の欠陥シグナルとして扱う後者は、掃除をループとして回すための行です。

委譲 — サブエージェントは親の会話を引き継がない、という事実からすべてが出ています。まず、役割を切り出せる作業は積極的に委譲してよいと許可を書きます。委譲をためらう方向の失敗もあるからです。そのうえで、渡すものは契約として明示する、secretは実値も参照も渡さない、返ってきた判断は渡したcontextの範囲での限定判断として親が検証する。最後の匿名比較は、複数のAIに相互レビューをさせると作成者名で評価が歪む、という観測への対処です。委譲先ごとの細かな契約をここに書かないのは、それが各エージェント定義のdescriptionの仕事だからです。

Skill / Runner 運用 — Tip 1のハブ原則の実働部分です。詳細な手順は正規docsとSkillが正本を持ち、新しく作る前に既存で足りるかを確認します。増幅されるのはルールだけではありません。重複したwrapperや似た用途のスクリプトも、重複したルールと同じ速度でゴミになります。

Artifact gate — 「完了しました」という宣言は状態ではありません。Phaseを持つ作業では、中間成果物がファイルとして存在することを遷移の条件にし、hookが存在と必須キーだけを機械検査します。このhookの線引きは冒頭に併載したCLAUDE.mdの側に明文化してあり、Tip 6の役割分担どおり、中身の妥当性は機械に判定させません。Phaseが明示されない作業は対象外という既定値を置き、バイパスする単発例外にはexpires_atを必須にする。Tip 4の範囲と解除条件です。Skillが固有のartifactを要求する場合の序列も決めてあり、SKILL.mdが実行中の具体契約、このファイルは常に適用される下限です。

Markdown / ADR 運用 — Tip 5の消す義務がここに入っています。mdを編集したらファイル全体の矛盾と重複を見直す。メタデータはFront Matterに置いて、validatorが読める形にする(Tip 6の前提です)。大きめの決定はADRに日時と作業したモデル名つきで残す。理由をADRへ逃がすから、本体は現在形だけを保てます(Tip 2)。

Plan 共通ルール — 計画段階の2本です。PhaseごとにSkillを明示させるのは、道具の解決を実行中の裁量に残さないため。途中確認なしで完走できる粒度を求めるのは、自走の単位を計画時に確定するためです。この粒度が適切だったかは、Tip 7のコールドスタートがそのまま測ってくれます。

書き方の半分は消し方

AGENTS.mdはAIへの説明書ではなく、次のAIが読む前例でした。だから7つ並べたTipsの半分は、書かない、絞る、消すという話になっていますし、冒頭に公開したファイルも、書き足した結果ではなく消し続けた結果です。

ルールを1行足す前に、この1行は増幅されてよいかを見る。それがいちばん効くTipsだと考えています。