CodexのAGENTS.mdの書き方｜残す・分ける・削る判断基準

Codexを使ってWebサイト制作や執筆、資料整理を進めていると、毎回同じ指示を入力する手間を省くために AGENTS.md を使い始めます。

しかし、「何から書けばいいか分からない」「注意書きを足すうちに長くなりすぎる」「本当に読まれているのか手応えがない」といった悩みにぶつかりがちです。

こうした迷いに対する答えはシンプルです。

毎回必ず守るべき共通ルールだけを短く残し、特定の作業でしか使わない詳しい手順は既存資料へ案内する

指示書を整理するとき、文字数を減らすこと自体を目的にしてはいけません。作業の前提条件や、完成した成果物を勝手に消させない保全ルールまで削ると、意図しない変更や推測による補完を招く原因になります。

現在の目的に合わせて気になるところから確認してみてください。

• これから初めて作る方：第1章の4つの観点と最小構成、第2章の配置と読み込みの仕組み
• 長くなって整理したい方：第3章の工程ごとの役割分担、第4章の「残す・分ける・削る」判断表
• 読まれたか確かめたい方：第5章の確認・点検プロンプトと照合方法、第6章の仕事の進め方

AGENTS.mdには毎回必要な仕事のルールを書く

Codexとの対話で、毎回プロンプトに「推測で書かないで」「指定フォルダ以外のファイルは触らないで」と打ち込むのは手間がかかりますよね。

AGENTS.md は、Codexが作業開始前に自動で探索して読み込む指示ファイルです。あらかじめ共通ルールを書いておくことで、毎回同じ説明を繰り返す手間を省けます。

実務で整理しやすい4つの観点

最初は何を書けばよいのでしょうか。OpenAI公式で形式が固定されているわけではありませんが、実務で破綻しにくく組み立てやすいのが以下の 4つの観点 による整理です。

1. 目的：何を作る作業か、今回のゴールを簡潔に定義する
2. 正しい情報源：どの資料を基準にし、何を勝手に補ってはならないかを指定する
3. 変更範囲：どのファイルを編集してよく、どこを触ってはいけないかを明示する
4. 完了条件：作業終了の基準や、最後に何を報告させるかを定める

この4観点は実務に合わせた整理例で、OpenAI公式の必須形式ではありません。しかし、「何のために」「どこを見て」「どこを変え」「どう終わるか」を揃えることで、作業や報告のズレを減らせます。

実際の仕事で使える最小構成の記述例

無関係な機能や過剰なリファクタリングを追加させない実務ルールを含めた、最小限の記述例です。

# プロジェクト基本作業ルール

## 目的
Webサイトに掲載する解説記事の作成・更新を行います。
目的と完了条件を満たす最小構成とし、不要な機能追加や無関係なリファクタリングは行いません。

## 正しい情報源
- 執筆に必要な事実は、指定された資料および既存ファイルからのみ確認してください。
- 手元資料で確認できない事実や不明な点は推測で補わず、未確認事項として報告してください。

## 変更範囲
- 編集対象は、指定された記事ファイル（`content/` 配下の指定ファイル）のみです。
- サイト共通設定や指定外の過去記事は変更しないでください。
- 対象外の改善案を見つけた場合は勝手に実装せず、報告にとどめてください。

## 完了条件
- 依頼された構成と要件がすべて満たされていること。
- 編集ファイル一覧と、判断に迷った点・人間への確認事項を出力すること。

細かな好みを詰め込む前に、「推測させない」「関係ないファイルを触らせない」という安全条件を整えることが基本です。

どこに置くか、どの指示が読まれるかを確認する

Codex起動時に行われるローカル指示探索の仕様は公式ドキュメントで公開されています。

出典：OpenAI公式：Custom instructions with AGENTS.md

探索の要点は以下の通りです。

• 個人の共通指示：既定は ~/.codex。Windowsの標準例は C:\Users\<ユーザー名>\.codex\AGENTS.md です（環境変数 CODEX_HOME やユーザー名で変動）。全案件共通の方針を置きます。
• 探索経路：プロジェクトルート（Gitルート等）から現在地まで探索します（ルート未検出時は現在地のみ）。
• 同一階層の優先度：AGENTS.override.md、AGENTS.md、設定された代替名の順で最大1ファイルを採用。通常ファイルに追記されずoverrideが優先されますが、空ファイルは読み飛ばすため、存在だけで有効とは断定できません。
• 後勝ちの原則：ルートから順に結合され、矛盾時は現在地に近い階層が上書きします。システム指示や権限は無効化できません。

なお、任意に作成した別ファイルは配置するだけでは自動探索の対象にはなりません。作業中に参照させたい場合は、繰り返す参照なら AGENTS.md で読む工程と節を指定し、単発の参照なら依頼文で直接指定します。

ルールを足す前に、どの工程で必要かを考える

意図しない記法や表示崩れを防ごうと注意書きをその都度継ぎ足すと、ファイルが肥大化し、重要な基本原則が埋もれてしまいます。

実際の制作資料に見る役割の分担

僕のWebサイト制作用の資料を確認してみると、すべての指示が1ファイルに集約されているわけではなく、工程や役割ごとに分けて管理されています。

• 全体の基本方針：作業の目的、完了条件、変更禁止範囲などの共通前提
• 構成の基準：見出しの組み立て方や、ページ全体における画像の役割・配置の設計
• 文体や表現の基準：見出しの付け方やトーン＆マナー
• 実装・表示の仕様：Markdown装飾のルールや表セル内のHTML記法
• 検証と確認の基準：成果物の点検項目や整合性の照合方法

手元の指示は不要だから消すのではなく、参照すべき工程がそれぞれ異なっています。

ファイルを分ければ解決というわけではない

注意したいのは、単にファイルを分割しても、AGENTS.md で「開始時に全ファイルを読んでください」と指定すれば、巨大な1ファイルを毎回読ませるのと変わらない点です。

例えば、構成案を考える段階では表セル内のHTML記法まで読む必要はありませんが、「どこにどんな役割の画像を配置するか」という設計は欠かせません。そして執筆・マークアップ段階になって初めて、HTML記法の詳細仕様が必要になります。

ルールを足すときは、「全作業で共通して守るべきことか、特定工程でのみ必要な詳細仕様か」を見極めることが大切です。

制作ルールを「残す・分ける・削る」で整理する

手元のルールが長くなってきたら、以下の3つの基準で仕分けを行います。

1. 残す：全作業で共通して守るべき前提、変更範囲、保全のルール
2. 分ける：特定作業でのみ必要な詳細な手順・仕様（工程別資料へ案内）
3. 削る：意味や条件が重複している指示、現状に合わなくなった古い記述

手元のルールを仕分ける簡易チェック

このツールは仕分けのたたき台を整理するもので、ファイルの自動編集や外部送信は行いません。意味や例外の最終確認はご自身で行ってください。

実務ルールを仕分ける判断の目安

以下の表は、僕の制作資料にあるルールを要約し、仕分けの考え方を示した例です（実務ルールの要約と今回の整理案であり、過去にすべて移動・削除した実績を示すものではありません）。

手元のルールの例	判断	理由と具体的な扱い方
手元の資料で確認できない事実は推測で補わない	残す	全工程に共通する安全と正確性の根幹ルール。文字数を減らすために削らない。
完成・承認済みの成果物を勝手に変更・削除しない	残す	過去の作業成果を保護するための保全ルール。意図しない上書きを防ぐため最優先で残す。
表セル内のHTML記法や細かなマークアップ仕様	分ける	構成検討では不要な実装詳細。執筆や表示確認の工程でレイアウト資料の該当節を読むよう案内する。
見出しごとの装飾記法やテキストの強調ルール	分ける	文体や装飾の工程でのみ必要な詳細ルール。共通指示からは外し、執筆資料へ移す。
「推測で書かない」と「事実のみ書く」の重複	削る（統合）	意味が同じ記述は1つにまとめる。ただし「未確認事項として報告する」といった例外・報告条件が含まれているか照合し、必要な条件は落とさない。
過去の単発トラブル対策として追加した注意書き	削る（削除）	現在のプロンプトや基本ルールで同様の問題に対処できるか、問題自体への対処が不要になったかを確認した上で削除する。

「残す」ときの判断：保全ルールを削らない

整理の際、文字数を減らそうとして安全の前提や保全ルールまで削ってはいけません。

削る対象はあくまで重複した表現や、対処が不要になった古い指示です。「承認済み成果物を書き換えない」「指定外ファイルを触らない」「手元にない事実を補わない」といった保全・安全の条件は、必ず AGENTS.md に残しておきます。

「分ける」ときの書き方：既存資料と読む工程・節を指定する

ルールを分ける場合、単にファイル名を書くだけでは不十分です。「どんな作業をするときに、どの資料のどの節を読むか」を対応付けて指定します。

また、手元に仕様書などの既存資料があるなら、新規ファイルを増やす必要はありません。既存資料の該当見出しへ案内すれば足ります。

## 工程別の参照資料

担当作業に応じて、以下の資料の該当箇所を参照してください。関係のない資料をあらかじめ読む必要はありません。

- **記事の構成案を作成するとき**：
  `docs/composition_policy.md` の「見出し設計の基準」「画像の配置方針」を参照
- **本文の執筆・マークアップを行うとき**：
  `docs/composition_policy.md` の「Markdownテキスト装飾」「表のセル内HTML記法」を参照
- **文体やトーンの確認を行うとき**：
  `docs/editorial_policy.md` の「共通文体ルール」を参照

作業ごとに参照すべき資料や節を明記しておくことで、その工程に必要な指示を参照しやすく整理できます。ただし、記述したからといって不要な資料を必ず読まなくなる、指定した資料だけを確実に読むとは断定できません。指示が実際に認識されているか、意図通りに成果物が作られているかは、後述の通り分けて確認します。

整理後は「読まれたか」と「仕事ができたか」を分けて見る

ルール整理後に思い通りに動かないと感じたら、次の2つを切り分けて観察します。

1. 指示が正しく認識されているか（ファイルの読み込みや指示の把握）
2. 指示の内容を正しく実行できているか（作業の遂行）

指示自体は読み込まれていても、プロンプトの追加指示と衝突していたり、指示の言葉が曖昧で解釈が分かれていたりすることもあるためです。

読み込みの認識を確認する要約プロンプト

指示を把握しているか確かめるには、「AGENTS.mdを読みましたか？」と尋ねるのではなく、「読み込んだ指示の出所と要約」 を出力させます。

現在読み込んでいる指示について、以下の点を確認して回答してください。
分からない点や確認できない項目がある場合は、推測せず「確認できない」と答えてください。

1. 参照している指示ファイルの出所（ファイル名、分かる場合は配置場所）
2. あなたが認識している今回の作業の「目的」
3. 参照すべき「情報源」と、手元資料にない場合の扱い
4. 編集してよい範囲と、禁止されている「変更範囲」
5. 作業完了とみなす「完了条件」

ただし、プロンプト直貼りでも要約は返せるため、要約が出たこと自体が自動読み込みの完全な証明にはなりません。確実な探索状況を確かめたい場合は、公式ドキュメントに記載されているログ確認なども併用します。

機械検証と目視確認を組み合わせて照合する

指示の把握を確認したら、実際の成果物とルールを照合します。自己申告やテスト終了コードを鵜呑みにせず、新しい検証制度を無理に作ることもせず、既存の処理と目視を組み合わせます。

• 機械的に確認できる点：Gitの差分（diff）、編集対象外ファイルの有無、リンク切れや指定フォーマット等は、既存のツールや差分チェックを活用します。
• 人間の目で読み比べる点：手元資料に基づいた事実か、推測の補完がないか、文脈が目的に適しているか等は、実際の原稿と元資料を読み比べて確認します。

手元のAGENTS.mdを点検するプロンプト

手元の記述を整理する際は、Codex自身に仕分けのたたき台を作らせるのも有効です。ファイルを直接編集させず、既存資料の活用を優先させるプロンプトを使います。

以下の指示に従い、現在読み込んでいるAGENTS.mdの内容を点検してください。

【依頼内容】
現在の記述を「残す・分ける・削る」の観点から見直し、整理の候補案を提案してください。
1. 全工程で共通して守るべき前提・安全・保全ルール（残す候補）
2. 特定の作業でのみ読めばよい詳細なルール（分ける候補、読む工程、既存資料の該当節の案内案）
3. 意味や条件が重複している記述、または現在の運用に照らして不要な記述（削る・統合の候補）

【重要事項】
- ファイルを直接編集・更新しないでください。
- 移動先は新しいファイルを無駄に増やさず、既存の資料や節への案内を優先してください。
- 条件が同じか判断できないものや未確認の事項は、削除候補とせず「人間への確認事項」として残してください。
- 「どの記述を」「どう分類するか」「その理由」「人間が確認・判断すべき点」を箇条書きで出力してください。

出力された提案をもとに、最終的な採否を自分で判断していきましょう。

AGENTS.mdに仕事のすべてを背負わせない

AGENTS.md を丁寧に作り込んでも、指示書だけで実務のすべてが思い通りに進むわけではありません。日々の作業は、基本指示書（AGENTS.md）、正しい入力資料、作業ごとの明確なプロンプト、そして機械検証と人間の目による照合の4つが揃って初めて安定します。AGENTS.md にすべてを背負わせず、「毎回必要な共通の前提」として役割を担わせることが大切です。

長くなった指示書を前にしたら、まずは手元の AGENTS.md を開き、気になるルールを1行だけ選んでみてください。「どの作業でも共通して必要な『残す』ものか、特定工程でのみ確認する『分ける』ものか」を仕分けるだけでも、指示書の整理は確実に前に進みます。判断に迷うルールは無理に消さず「確認中」として残しながら、大切な仕事の前提を少しずつ整えていきましょう。