CodexのAGENTS.mdの書き方｜仕事のルールを渡す

AGENTS.mdに書くのは、Codexへ繰り返し伝えたい「この仕事の進め方」です。最初はプロジェクトの一番上に1枚置き、正しい入力、変更してよい場所、確認方法、完了条件を決めましょう。文章を増やす前に、小さな仕事でルールが結果に表れるか確かめると、使える指示書に育てられます。

「日本語で答えて」「元データは変えないで」「作ったあとに確認して」。毎回同じ説明をしているなら、AGENTS.mdへ移せる内容があります。ただ、雛形を貼っただけでは、自分のフォルダや業務に合わないルールも残ります。この記事では、配置と読み込みの仕組みから、開発・記事制作・CSV集計の3つの雛形、反映されないときの調べ方までを扱います。

仕様確認：2026年10月10日。探索の説明はOpenAI公式ガイドに基づきます。雛形・練習課題・点検表は編集部作成の教材です。アプリや組織設定による違いは、利用中の環境で確認してください。

AGENTS.mdには何を書く？まず7項目を決める

AGENTS.mdはMarkdown形式のテキストファイルです。決まった必須見出しを埋めるフォームではありません。共通形式のAGENTS.md公式サイトでも、作業に必要な案内を自由な見出しで記述する形が示されています。編集部では、初めて作るときは次の7項目から考えることを勧めます。

7項目を全部長く書く必要はありません。大切なのは、別の担当者が読んでも同じ入力と合格条件を選べることです。「丁寧に」「いい感じに」だけでは、作業が終わったかを判定できません。

最初の1行は、直近で困ったことから作る

たとえば「公開済みの記事を直したら、初回公開日まで今日に変わった」という失敗があれば、次のように書けます。

既存記事の初回公開日は維持する。
本文を実際に更新した場合だけ、更新日を変更する。
完了時に、公開日が変わっていないことを確認する。

これは「日付に気をつける」より、対象と確認方法が明確です。自分が困ったことを、再発を見つけられる条件に変換していきましょう。

どこに置く？個人共通・プロジェクト・作業フォルダ

OpenAI公式の探索は、Codex homeの全体指示と、プロジェクトルートから現在の作業ディレクトリまでの指示を組み合わせます。同じ階層では最大1ファイルを選び、作業場所に近い内容ほど後に加わります。標準名は AGENTS.md、同じ場所では AGENTS.override.md が先に選ばれます。探索順の公式説明

最初から3階層を作る必要はありません。1つの仕事を始めるなら、そのプロジェクトの入口に置いた1枚から試す方が、どの指示が効いているか追いやすくなります。

プロジェクトルートを検出できない場合、プロジェクト側の探索は現在の作業ディレクトリだけになります。Git管理していない業務フォルダでは、親フォルダの指示も当然読まれると思わず、実際に作業するフォルダへ置いて確認してください。

monthly-report/           ← 今回のプロジェクト
  AGENTS.md              ← 全体の約束
  input/
    orders.csv           ← 入力データ
  output/                ← 成果物
  articles/
    AGENTS.md            ← 記事制作だけの追加ルール

この例で集計担当と記事担当の仕事が違うなら、全体には「入力を変えない」などを置き、記事側には「引用元を本文に付ける」などを書きます。集計の細かい条件を、関係のない記事担当へ毎回読ませる必要はありません。

置き場所で迷ったときの判断表

読み込み順で間違えやすい3つのポイント

1．overrideは「同じ階層で選ぶファイル」を変える

通常版へ追記される別冊だと思うと混乱します。同じフォルダの通常版を使うつもりでルールを書き足しても、overrideが選ばれていれば、想定どおりになりません。親フォルダの指示まで一括でなくす仕組み、と考えるのも誤りです。臨時のoverrideを用意したときは、用途と戻す時期も自分の作業記録に残しましょう。

2．ファイルの置き場所と、作業を始めた場所は両方確認する

「記事用フォルダに置いたから、どこから始めても記事ルールが自動で同じように入る」とは決めつけないでください。まず対象フォルダから新しく開始し、適用する指示を確認します。複数のクライアントや追加の読み込み機構を使っている場合も、実際の環境で確かめます。

3．分割しただけで、読み込み量の問題が消えるわけではない

読み込み量の設定は project_doc_max_bytes で、公式ガイドの既定値は32 KiBです。文字数とは異なります。関連する階層に長文を分散するだけでなく、常に必要な要点と、必要時に読む詳細資料を分けます。設定名は 公式Configuration Referenceで確認できます。

たとえば、全商品の説明を本文に並べる代わりに「商品情報は docs/products.md を参照し、未記載の料金を推測しない」と書きます。ただし、参照先が存在すること、必要な場面で実際に参照したことの確認は必要です。

そのまま編集して使えるAGENTS.mdの雛形3種

以下は編集部の教材です。自分の仕事に必要な1つを選び、パスと確認方法を実在するものに置き換えてください。全部を結合すると、関係のない指示が増えてしまいます。

雛形1：Webサイト・アプリ開発

# このプロジェクトの作業ルール

## 作業の入口
- READMEと対象フォルダの構成を確認してから編集する。
- 既存の実装・命名・依存関係を先に調べる。
- 今回の目的と無関係な一括整形はしない。

## 変更と検証
- 入出力の仕様が変わる場合は、影響を受ける呼び出し元も確認する。
- package.json、Makefile、CI設定から実在する確認コマンドを選ぶ。
- 存在しないテストコマンドを、実行済みと報告しない。
- 表示を変えたら、対象画面をPC幅とスマホ幅で確認する。
- 修正に関係する失敗と、変更前からある失敗を分けて記録する。

## 完了時
- 変更した動作、実行した確認、その結果を報告する。
- 未実施の確認と残っている制約を明記する。
- 本番への公開は、この作業の許可範囲を確認してから行う。

この雛形には、適当に選んだ npm test を埋め込んでいません。プロジェクトで使うコマンドが分かったら、「対象フォルダ・コマンド・何を確かめるか」を追記します。UIの微修正と、課金処理の変更では必要な確認が違います。全変更へ同じ確認を機械的に要求するより、変更の影響と結びつけてください。

雛形2：記事・資料制作

# 記事制作フォルダの作業ルール

## 入力と保存先
- 元資料は input/、原稿は drafts/ に保存する。
- 出典の名称、URL、確認日を原稿と対応づける。
- 元資料にない実績、発言、数字を事実として補わない。

## 編集
- 冒頭で読者の疑問に答え、その後に手順と具体例を置く。
- 製品の公式仕様、編集部の提案、実施した検証を区別する。
- 既存記事の初回公開日は維持する。
- 引用箇所と自分の説明が混ざらないようにする。

## 確認と完了
- 重要な主張を、対応する一次資料と照合する。
- リンクの着地先、図のラベル、表と本文の数値を確認する。
- 原稿をプレビューし、見出し・画像・スマホ表示を確認する。
- 公開前の原稿は「下書き」として報告する。

「高品質な記事を書く」だけでは、元資料にない体験談を増やすことで文章を立派に見せてしまう可能性もあります。この例では、根拠と原稿を対応づけ、実施した作業を区別することで、確認しやすい成果物を目指しています。

雛形3：CSV集計・定型レポート

# 受注レポートの作業ルール

## 入力と出力
- 入力は input/orders.csv。入力ファイルは変更しない。
- 出力は output/summary.md に保存する。

## 集計条件
- statusがconfirmedの行だけを合計する。
- amount_yenは円単位の整数として扱い、通貨換算しない。
- cancelledの行は除外し、その件数と金額を別記する。
- 金額欠損、不明なstatus、重複したorder_idがあれば列挙する。
- これらの異常が1つでもあれば確定集計を保留し、
  問題の行と理由だけをoutput/summary.mdへ保存する。
- 不明値を推測で補って、確定結果として報告しない。

## 完了条件
- 対象件数、除外件数、合計額、未確認事項を記載する。
- 元CSVが変更されていないことを確認する。
- 保存した成果物を読み直し、集計値を照合する。
- 作成したレポートの保存先を報告する。

集計は答えが合っているだけでなく、「どの行を含めたか」が分かることも大切です。キャンセルを除外するかどうかを依頼のたびに変えていると、同じCSVでも集計が変わります。業務として固定した条件はAGENTS.mdへ、今月だけの対象期間などは今回の依頼へ分けると管理しやすくなります。

練習：架空のCSVから、ルールどおりのレポートを作る

ここでは3つ目の雛形を使います。Codexの導入がまだの方は、先にインストールと初回設定を確認してください。実在の顧客データを使わず、ZIP内の practice/ を作業フォルダとして開きます。

ステップ1：入力と期待値を先に見る

期待値は、対象2件・30,000円、除外1件・8,000円です。これは架空データの算術的な期待値であり、実業務の売上実績ではありません。元CSVと期待値の対応は編集部で照合しています。

ステップ2：今回だけの依頼を渡す

このフォルダのAGENTS.mdに従って、
input/orders.csvから受注レポートを作ってください。
最初に、適用する指示ファイルと集計条件を短く確認してください。
保存したレポートを読み直し、結果と保存先を報告してください。

AGENTS.mdには毎回のルール、依頼文には今回作るものを書きます。ルールを全文もう一度貼らなくても仕事が成立するか、確認する練習になります。

ステップ3：回答と保存ファイルを照合する

1. output/summary.md が実際にあるか確認する。
2. 対象2件・30,000円、除外1件・8,000円になっているか読む。
3. 入力CSVが最初の3行から変わっていないか確認する。
4. Codexの完了報告と、保存されたファイルの内容が一致するか見る。

「できました」と言ったことと、成果物が条件を満たすことは別です。金額だけを合わせ、キャンセルの説明が抜けていたら、完了条件のどこが足りなかったかを調べます。答えを会話で直すだけでなく、次回も必要な条件なら指示書へ戻して整理しましょう。

ステップ4：失敗しやすい入力でも確かめる

正常な3行で動いたら、コピーした別のCSVで「金額の空欄」「同じorder_id」「未知のstatus」を1つずつ試します。期待するのは、勝手な補完ではなく、問題の行と未確定の理由が分かる報告です。練習用ファイルの変更も、最初のCSVを残して別名にしてください。

この教材では、異常が一つでもあれば確定集計を保留するルールです。たとえばDEMO-003,confirmed,18000をもう一行追加した場合、48,000円を確定額として出すのではなく、DEMO-003の重複と集計保留を報告するのが期待結果です。正常行だけを暫定集計する運用にしたい場合は、その条件と表示方法を別に決めてください。

この教材は、Codexが必ず同じ回答を返すことを証明するものではありません。利用モデル・権限・作業場所を記録し、自分の環境で指示と成果物の対応を確かめるための課題です。

曖昧な指示を、確認できる指示へ直す

ルールを直すときは、「条件→行動→確かめ方」の順にすると考えやすくなります。条件がなければ常に実行するのか分からず、確認方法がなければ守ったか分かりません。反対に、簡単な作業へ大掛かりな確認を毎回要求すると、完了までの負担だけが増えます。

長くなったら、AGENTS.md・Skills・資料を分ける

AGENTS.mdを改善することと、AGENTS.mdを長くすることは同じではありません。OpenAIのプロンプトとSkillsの見直しに関する記事も、必要な情報を必要なときに読み、過剰な指示を見直す考え方を示しています。

Skillは、特定の仕事に使う指示・資料・スクリプトなどをまとめる仕組みです。公式説明では、最初に名前と説明を読み、必要なときに詳しい指示を読み込む形です。繰り返し使う長い作業手順が増えたら、公式のSkillsガイドと、Codex Skillsの実践記事を確認してください。

同じ失敗が続いたときの直し方

まず「読まれていない」「読まれたが曖昧」「別のルールと矛盾」「確認方法がない」のどれかを切り分けます。新しい禁止文を足すのは、そのあとです。

1. 失敗した入力と結果を残す。
2. 原因に関係するルールを1つ選ぶ。
3. 条件と合格条件が分かる表現へ直す。
4. 同じ入力で再確認する。
5. 問題が解消したら、重複する古いルールを整理する。

たとえば「税込と税抜を混ぜた」問題なら、「正確に計算する」を3回書くより、入力の列名と単位、集計対象を明確にする方が、原因に近い改善になります。

読み込まれたかは、説明と成果物の両方で確認する

対象フォルダで新しく作業を開始し、最初に次のように依頼します。ファイルの置き方を変えた直後は、以前の会話だけを頼りに判定しないことが大切です。

今回の作業に適用する指示ファイルのパスと、
作業時に守る主なルールを挙げてください。
読み込んだと確認できないファイルは、その旨を区別してください。
まだ成果物の編集はしないでください。

その説明が正しそうでも、検証は終わりではありません。次に、元へ戻せる小さな作業を頼み、指定した保存先・形式・確認項目が成果物に反映されるか見ます。指示ファイルの一覧を答えたことだけで、「今後も必ず守られる」とは判断できません。

AGENTS.mdが効かないときの確認順

最初から内容を全部書き直すと、原因が見えなくなります。次の順に、1つずつ確認してください。

CLIを使う場合、pwd は現在地、git rev-parse --show-toplevel はGitプロジェクトのルート確認に使えます。Git管理していないフォルダでは後者が失敗するので、その結果をファイル破損と混同しないでください。WindowsのPowerShellでは現在地を Get-Location で確認できます。

別のCodex homeを使う環境では、標準の ~/.codex/ を編集しても意図したプロファイルに届かないことがあります。プロファイルの切り替えや組織管理がある場合は、利用環境の設定場所も確認します。

禁止事項を書くだけで、操作の権限は制限できる？

AGENTS.mdは作業の指示であり、アクセス権を強制する設定とは役割が違います。OpenAIは、サンドボックスを操作の技術的な境界、承認ポリシーを境界を越える際の確認の仕組みとして説明しています。サンドボックスの公式説明

業務で「入力を変更しない」と決めるなら、指示書に書いたうえで、入力のコピーやアクセス権、変更差分の確認も組み合わせます。「顧客へ送る前に確認する」なら、下書き作成と送信を工程として分け、宛先と本文を確認できる状態にします。

また、パスワードやAPIキーそのものをAGENTS.mdへ貼る必要はありません。誰でも読む共有ファイルには、認証の正規手順や管理担当など、仕事に必要な案内を残します。指示書をチームで配るときは、内容が共有先に適しているかも見てください。

チームで使うなら、更新者と確認課題を決める

各自が同じAGENTS.mdを別々に直すと、「どれが現在のルールか」が分からなくなります。チーム共通の版を1つ決め、更新理由と確認結果が追える形にしてください。Gitを使う場合も、ファイルをコミットしただけで運用の合意が取れたとは限りません。

編集部が勧める確認課題は3つです。普段の正常な仕事、入力が不足している仕事、変更範囲が曖昧な仕事。この3つで、普通に進めるところ・相談するところ・成果物の合格条件を点検できます。

変更したルール：
変更の理由：
確認に使った入力：
期待した結果：
実際の結果：
未確認の環境・条件：
確認した人・日付：

「精度が上がった」だけでなく、何の入力で、どの失敗が減ったかを書くと、次の担当者も判断できます。実行時間や成功率を比べる場合は、同じ条件で複数回確認し、1回だけの成功を全体の効果に広げないようにしましょう。

AGENTS.mdのよくある質問

日本語で書いてもよいですか？

このページの雛形は日本語で書いています。大切なのは担当者が維持できることと、パス・列名・コマンドなどの正確な表記を崩さないことです。英語へ訳しただけで品質が上がるとは決めず、自分の業務の確認課題で判断してください。

READMEがある場合も必要ですか？

READMEへ必要な情報が揃っているなら、同じ説明を丸ごと複製する必要はありません。人向けの導入説明をREADMEへ残し、Codexに特に伝えたい変更範囲や確認方法をAGENTS.mdへまとめると、修正箇所が増えにくくなります。

何行・何文字が最適ですか？

この文字数なら必ず良い、という基準は設けません。必要なルールを探せるか、矛盾がないか、実際の仕事が完了するかで見ます。長い仕様書や過去の経緯が増えたら、本文をさらに増やす前に分け方を見直します。

Claude Codeにも同じものを使えますか？

ルールの内容は再利用できても、ファイルの探索条件まで同じとは限りません。両方の製品を使うなら、共通の業務ルールと製品固有の設定を分け、CLAUDE.mdの配置・読み込みの解説でClaude Code側の条件も確認してください。

CodexにAGENTS.md自体を書かせてもよいですか？

下書きを頼むときは、既存のREADMEや設定を読ませ、根拠のあるコマンドとパスだけを使わせます。その後、不要な一般論、存在しない手順、勝手に増えた承認条件を人が確認してください。運用ルールの変更は、その業務の担当者が判断できる形にします。

まず1つの仕事で、使える指示書に育てる

最初の到達点は、長いAGENTS.mdを完成させることではありません。1つの仕事について、入力・保存先・判断ルール・合格条件が揃い、別の作業でも同じ前提から始められる状態です。

• 最初の1枚を、作業するプロジェクトへ置く。
• 雛形のパスと条件を、実際の仕事に合わせる。
• 小さな確認課題で、保存された成果物を見る。
• 失敗した条件を具体化し、重複する指示を整理する。

同じ仕事の手順まで再利用したくなったらSkillsへ、資料の整理を進めるならObsidianとの連携へ進めます。会社の仕事に広げるときは、Codexの法人・業務活用で、対象業務と効果の確かめ方を整理してください。