はじめに

Codexに仕事を頼むたびに、「直したらテストを回して」「元のデータは触らないで」と同じ指示を貼っていないでしょうか。貼り忘れた回に限って、決まりと違う直し方をされることもあります。

本記事では、CodexのAGENTS.mdの書き方を、毎回の指示をファイルに残す手順として解説します。あわせて、AGENTS.mdに書いても仕切りにならない権限の決め方と、役割ごとの手順の分け方まで扱います。スマートエイトは自社のリポジトリで、AGENTS.mdとCodexの役割定義18件を運用しています。

結論を先に書きます。AGENTS.mdには全員が守る共通の決まりだけを短く書きます。どこまで書き換えてよいかは起動時の設定で決め、役割ごとの手順は別のフォルダに分けます。この3つを分けると、指示の貼り忘れと権限の思い込みの両方が減ります。

本記事は、2026年10月16日時点のOpenAIの公式ドキュメントと、スマートエイトが2026年9月14日にcodex-cli 0.144.1で確かめた結果をもとにしています。設定の選択肢は版によって変わるため、手元の版でも「codex --help」で確かめてから使ってください。

CodexのAGENTS.mdとは|毎回の指示を残す置き場所

AGENTS.mdは、Codexが作業を始める前に読む指示書です。リポジトリ*に置いておけば、頼むたびに同じ前置きを貼らなくても、決まりを守った状態で作業が始まります。

図1：AGENTS.mdが読まれる順番。利用者ごとのCodex用のフォルダ、リポジトリのいちばん上、途中のフォルダ、作業中のフォルダの順につなげて読み、作業中のフォルダに近いものほど優先される

毎回チャットに貼っていた指示を、ファイルに移します

例として、経理部が「請求書と入金の突き合わせ」に使う社内の集計ツールを、情報システムの担当者がCodexで直す場面を考えます。担当者は頼むたびに、「入金データの元ファイルは書き換えない」「直したらテストを回す」と書き添えていました。

この種の前置きは、貼り忘れた1回で事故につながります。AGENTS.mdに移しておけば、Codexは作業を始める前にこのファイルを読みます。担当者の頭の中にあった決まりが、リポジトリの中に残る形に変わります。

Codexそのものの入口や契約の範囲は、OpenAI Codexのできること・使い方・料金をまとめた記事で整理しています。本記事は、そのCodexに決まりを渡すファイルの話に絞ります。

作業中のフォルダに近いほど優先されます

AGENTS.mdは1枚だけとは限りません。Codexはまず利用者ごとのCodex用のフォルダを見て、次にリポジトリのいちばん上から作業中のフォルダまで、途中のフォルダを1つずつ順に探します。見つけた分は、上から順につなげて読みます。

つなげた中で後ろに来るほど、つまり作業中のフォルダに近いほど、その内容が優先されます。全社の決まりはリポジトリのいちばん上に、経理のツールだけの決まりはそのフォルダに置くと、部署ごとの違いを1つのリポジトリの中で持てます。

*リポジトリ：プログラムや設定ファイルを、変更の履歴ごとまとめて保管する場所。社内のツールは、たいていリポジトリ単位で管理されている。

AGENTS.mdの書き方|全員が守る決まりだけを短く書く

AGENTS.mdに書くのは、そのリポジトリで作業する人とAIの全員が守る決まりだけです。役割ごとの手順や権限の指定まで積むと、ファイルが長くなるうえに、書いても仕切りにならない行が混ざります。

書くのは4項目に絞ります

業務のツールでAGENTS.mdに書いておきたい項目は、次の4つです。

  • このリポジトリが何をするものか
  • 触ってよい場所と、触らない場所
  • 作業を終える前に必ず回す確認
  • 情報の取り扱いで、例外なく守ること

突き合わせのツールなら、次のように書けます。見出しと箇条書きだけで足ります。

# 請求書と入金の突き合わせツール
経理部が月末に使う集計ツールです。

## 触らない場所
- data/raw/ の入金データは読み取りだけにする

## 終える前に
- tests/ のテストをすべて通す

## 情報の取り扱い
- 取引先名や口座番号をコードやログに書き出さない

1行には1つの決まりだけを、命令の形で書きます。「できれば」「なるべく」を付けた行は、必ず守る行との区別がつかなくなるため、付けずに言い切ります。

自社のAGENTS.mdは23行で、入口の役目に徹しています

スマートエイトのリポジトリにあるAGENTS.mdは23行です。中身の大半は、共通の決まりの正本は同じ場所にある別のファイルだという案内と、その読み方です。

それでもAGENTS.mdの本体に残した決まりが3つあります。認証情報を直書きしない、顧客情報を含む文書を外へ送らない、決まりのファイルを理由なく消さない、の3つです。正本を読み飛ばされた回でも、この3つだけは守らせたいからです。

決まりを2か所に書き写すと、片方だけが直されて中身がずれていきます。正本を1つに決め、AGENTS.mdは入口と外せない数行だけにする形が、長く運用しても崩れにくい分け方です。

書いても仕切りにならない行は、別の置き場に移します

AGENTS.mdは指示として読まれるだけで、Codexが書き込める範囲は、OSの仕組みで区切るサンドボックスの設定が決めます。公式も役割ファイルについて、「編集しない」と頼むことはできても、読み取り専用の仕切りにはならないとしています。

レビュー役の手順や記事を書く役の手順のように、役割ごとに違う長い手順もAGENTS.mdには積みません。全員が毎回読むファイルに、一部の作業でしか使わない手順が混ざるからです。こうした手順は、4章で扱う役割定義のフォルダに分けます。

権限はAGENTS.mdでなく起動の設定で決める|サンドボックス3択と承認方式

Codexに任せる範囲は、サンドボックス*と承認方式*という2つの設定で決まります。スマートエイトは2026年9月14日、codex-cli 0.144.1の実機でこの2つの選択肢を確かめました。

図2：Codexに任せる範囲を起動の設定で決める図。読ませるだけはread-onlyとon-request、作業中のフォルダだけ直すはworkspace-writeとon-request、検証用の環境で全部任せるはdanger-full-accessで、右へ行くほど任せる範囲が広がる

サンドボックスは3択です

サンドボックスの選択肢は「read-only」「workspace-write」「danger-full-access」の3つです。手元の0.144.1では、codex、codex exec、codex resumeの3つのコマンドのヘルプに、同じ3つが並んでいました。

read-onlyはファイルを読むだけ、workspace-writeは作業中のフォルダの中だけを書き換えられる設定です。danger-full-accessは、ネットワークも含めて承認なしで動かす設定です。どれも起動するときに「-s」の短い指定で選べます。

何も指定しないCLIの既定は、ネットワークに出ず、書き込みは作業中のフォルダまでです。Gitで管理しているフォルダでは、workspace-writeと次に扱うon-requestの組み合わせが勧められています。

承認方式はon-requestを基本にします

承認方式は、Codexがいつ人に確認を求めるかを決める設定で、起動時に「-a」で選べます。基本はon-requestです。サンドボックスの外に出る操作や、ネットワークを使う操作の前に確認を求めてきます。

確認を挟まないneverは、人が画面を見ていない定型の実行に使います。手元の0.144.1のヘルプには、この2つのほかにuntrustedも並んでいましたが、untrustedはすでに廃止されています。

2026年10月15日公開の0.163.0では、選択肢はon-requestとneverの2つです。設定ファイルにuntrustedが残っていると起動しないことがあるため、古い記事を見て書いた設定があれば、on-requestに書き換えます。

承認の種類ごとに、聞くものと自動で断るものを分けたい場合は、granularという指定もあります。最初はon-requestで始め、確認が多すぎると感じてから検討すれば足ります。

業務の場面ごとに組み合わせを決めます

突き合わせのツールを例に、場面ごとの組み合わせを表にまとめます。迷ったら上の行から順に試し、読ませるだけで役に立つかを確かめてから、書き換えを任せる範囲を広げます。

業務の場面

サンドボックス

承認方式

突き合わせのツールでの例

中身を読ませて説明させる

read-only

on-request

照合の手順を、経理の担当者向けの言葉で説明させる

いつもの修正を任せる

workspace-write

on-request

照合の不具合を直させ、テストまで回させる

人が見ていない定型の点検

read-only

never

毎晩、コードの書き方の検査だけを回す

danger-full-accessは、社員の業務パソコンでは選ばず、使い終えたら捨てる検証用の環境に限って使います。どの業務をどこまでAIに任せるかを費用対効果で決める考え方は、生成AIの費用対効果を測る4つの問いの記事で整理しています。

*サンドボックス：Codexが実行するコマンドの書き込みや通信の範囲を、OSの仕組みで区切る設定。範囲の外に出る操作は、承認方式に沿って人の確認を経てから行う。 *承認方式：Codexが操作の前に人へ確認を求めるかどうかと、そのタイミングを決める設定。

役割ごとの手順は.codex/agents/に分ける|18件を運用して分かったこと

点検役や調べ物役のように、同じリポジトリで性格の違う作業を頼むなら、役割ごとの手順は.codex/agents/のフォルダに1役割1ファイルで置きます。ファイルの形式はTOML*です。

図3：決まり・権限・役割の置き場を分ける図。全員が守る決まりはAGENTS.md、書き換えてよい範囲は起動時の設定、役割ごとの手順は.codex/agents/に置き、役割は起動時の設定の権限を引き継ぐ

自社では18の役割を、3つの項目だけで書いています

スマートエイトのリポジトリには、Codexの役割定義が18件あります。開発とコードレビューが2件、事実確認や見た目の検収などの点検役が5件、調査や提案の設計などが7件、記事の執筆やメールの仕分けなどが4件です。

18件とも、使っている項目は名前、いつ使うかの説明、役割の手順の3つだけです。この3つは、役割ファイルの必須項目と同じです。モデルや考える深さも役割ごとに変えられますが、今は使っていません。

ファイル名は、Claude Code*側の役割定義と同じ名前で1対1にそろえています。どちらのツールから頼んでも、同じ名前で同じ役割を呼べるようにするためです。

役割ファイルでは権限を変えられません

9月14日の実機の確認では、役割ファイルにサンドボックスや承認方式を宣言する項目はありませんでした。役割は、それを呼んだ親のCodexの権限をそのまま引き継ぐ仕組みです。役割ファイルにサンドボックスの指定を書いても、親の設定は上書きされません。

点検役の手順に「ファイルを編集しない」と書くことはできますが、それだけでは読み取り専用の仕切りになりません。点検役を本当に読むだけにしたいなら、親のCodexをread-onlyで起動してから頼みます。

突き合わせのツールなら、直す作業はworkspace-writeで起動して開発役に頼みます。直った結果の点検は、別にread-onlyで起動し直してから点検役に頼む、という順に分けます。

説明の1行が、いつ呼ばれるかを決めます

役割ファイルの説明は、Codexがどの場面でその役割を使うかの手がかりになります。「点検役」と書くだけでなく、「直した後に、元のデータを書き換えていないかを確かめる」のように、呼ぶ場面まで書きます。

名前は、Codexがその役割を呼ぶときの正式な名前です。ファイル名と合わせておくと管理が楽になります。

役割を足すかどうかは、AGENTS.mdに同じ種類の手順を何度も書き足していないかで判断します。書き足しが続いている手順が、役割に切り出す候補です。

*TOML：設定を「項目名 = 値」の形で書くファイルの形式。人が読んでも、プログラムが読んでも分かりやすい。 *Claude Code：Anthropic社のAIで、Codexと同じくリポジトリの中の作業を任せられる道具。

よくある質問|Claude Codeとの併用・長さの上限・読み込みの確かめ方

Claude CodeのCLAUDE.mdと、両方置く必要がありますか？

必ずしも両方は要りません。Claude CodeはCLAUDE.mdが無ければAGENTS.mdをそのまま読み、Codexも設定のproject_doc_fallback_filenamesにCLAUDE.mdを足せば読めます。

両方置く場合は、中身をどちらか一方に決め、もう一方は正本を読むよう案内するだけにします。スマートエイトはCLAUDE.mdを正本にし、AGENTS.mdから案内しています。Claude Code側で役割を分ける頼み方は、Claude Codeのサブエージェントの使い方でまとめています。

AGENTS.mdが長くなったら、どうしますか？

Codexが読み込むAGENTS.mdの合計には上限があり、既定は32KiBです。上限を超えた分は読まれないため、部署やツールごとの決まりは下のフォルダのAGENTS.mdに分けます。上限そのものは、設定ファイルのproject_doc_max_bytesで引き上げられます。

AGENTS.mdが読み込まれているか、確かめる方法はありますか？

あります。Codexに「いま読み込んでいる指示を要約して」と頼むと、読み込んだ決まりを挙げてくれます。下のフォルダで起動して読み込んだファイルの一覧を出させれば、どの順につながったかも確かめられます。

エンジニアがいない部署にも、AGENTS.mdを書く意味はありますか？

あります。決まりの中身を一番よく知っているのは、ツールを使う部署の側だからです。突き合わせのツールなら、書き換えてはいけないデータを経理の担当者が文章で挙げ、情報システムの担当者がAGENTS.mdに写す、という分担で進められます。

さいごに

本記事では、CodexのAGENTS.mdの書き方を、権限と役割の分け方とあわせて解説しました。AGENTS.mdには全員が守る決まりだけを短く書き、書き換えてよい範囲は起動時のサンドボックスと承認方式で、役割ごとの手順は.codex/agents/で分けます。

毎回同じ前置きを貼っている作業があれば、その前置きがAGENTS.mdの最初の数行になります。まずは1つのリポジトリで、読ませるだけの設定から試してください。スマートエイトは、社内のツールにAIを組み込む開発と、社員が自分で決まりを書けるようになる生成AI研修の両方を支援しています。

どの業務から手を付けるかで迷っている場合は、AIに任せられる業務が分かる無料診断から始めてください。3分で終わり、登録もメールアドレスも要りません。 ※生成AI研修資料/導入事例も無料ダウンロードいただけます。

AIを組み込んだ社内ツールの開発の詳細