Codex › 設定・拡張

CodexのAGENTS.mdの書き方|日本語テンプレート付き

「日本語で書いて」「元のファイルは変えないで」「できたものは、このフォルダに保存して」。

Codexに毎回伝えている決まりがあるなら、AGENTS.mdという指示書にまとめておけます。コードを書く仕事だけでなく、資料整理やブログの作業にも使えます。

まずは、いつもの仕事を1つ選んで、短い1枚を作るところからです。

この記事の結論

AGENTS.mdには「目的・入力・保存先・作業ルール・完了前の確認」を具体的に書くのがおすすめです。

これは最初の1枚を作るための型です。書いた後は、新しいチャットと小さな作業で、伝わり方を確かめます。

AGENTS.mdとは

毎回の決まりを書く指示書

何度も伝える作業の決まりを、AGENTS.mdという1枚の指示書にまとめる図

AGENTS.mdは、Codexが仕事を始めるときに読む、ルールや前提を書いたファイルです。読み込む場所や条件は、後の節で説明します。

「今日の打ち合わせメモを整理して」は、その場の依頼。「整理したメモは出力フォルダに保存する」は、毎回の決まりです。繰り返し使う方を指示書に残します。

初心者

難しい設定用の言葉で書くんですか?

芝田

日本語の箇条書きで大丈夫です。「何をしてほしいか」を具体的に書きます。

README・スキルとの違い

READMEは人への説明、AGENTS.mdは毎回の決まり、スキルは作業の手順という役割の違い

READMEは人が仕事の全体像を知るため、AGENTS.mdはCodexに毎回の決まりを渡すために使い分けると整理しやすくなります。READMEの全文を写す必要はありません。

スキルは、特定の作業を繰り返すための手順や資料をまとめる仕組みです。共通の決まりはAGENTS.md、長い作業手順はスキルや別の文書へ。最初から全部そろえなくて大丈夫です。

日本語テンプレートで作る

まず書く5つの項目

目的、入力、保存先、作業ルール、完了前の確認という指示書の5項目

ここでは、打ち合わせメモを整理する仕事を例にします。次の内容をコピーし、自分のフォルダ名と仕事に置き換えてください。

# 打ち合わせメモを整理する仕事

## 目的
打ち合わせのメモから、要点・次の作業・未定事項を整理します。

## 入力
`入力/打ち合わせメモ.md` を読んでください。

## 保存先
結果は `出力/打ち合わせの整理.md` に日本語のMarkdownで保存してください。

## 作業ルール
- 元のメモと、このAGENTS.mdは変更しないでください。
- 入力にない日付・担当者・予算などを推測で足さないでください。
- 決まっていないことは「未定」と書いてください。
- Web検索や外部サービスへの接続はしないでください。

## 完了前の確認
- 「要点」「次の作業」「未定事項」の3つの見出しがあるか確かめてください。
- 元のメモにある事実の抜けと、入力にない情報の追加がないか確認してください。
- 保存したファイルの相対パスを最後に伝えてください。

5項目はOpenAIが指定した必須書式ではなく、この記事の始め方の提案です。コードの作業なら、起動方法やテストのコマンドも加えます。

パスワードやAPIキーは書きません。「元のメモは変更しない」のように、結果を見て確かめられる言葉にするのがポイントです。

Codexにたたき台を頼む

自分でファイルを作るのが難しければ、手元の作業フォルダを扱うCodexのチャットで、次のように頼めます。

このフォルダで使うAGENTS.mdの案を作ってください。

仕事は、入力フォルダの打ち合わせメモを整理することです。
目的・入力・保存先・作業ルール・完了前の確認の5項目に分けてください。
入力にない事実を補わないこと、元のメモを変更しないことを書いてください。

既存のAGENTS.mdがある場合は上書きせず、違いと変更案を先に見せてください。
フォルダ内から分からないことは、推測で埋めずに質問してください。

できた案は、保存先と作業ルールを自分の目で確認します。実在しないフォルダや、使っていないテスト方法を混ぜたまま保存しないようにしましょう。

確認できたら、「この内容でAGENTS.mdとして保存して」と頼みます。名前はAGENTS.md.txtではなく、AGENTS.mdです。

実演で使ったAGENTS.mdの目的・入力・保存先の部分を表示したもの

見本ファイルの内容表示です。Codexの操作画面ではありません。

置き場所と読み込み順

全体共通と案件別に分ける

全体共通の決まりと、案件A・案件Bそれぞれの決まりを置き分ける概念図

どの仕事でも使う決まりと、その案件だけの決まりを分けます。

適用したい範囲 置き場所の例
全体共通 CodexのホームにあるAGENTS.md。既定は ~/.codex/AGENTS.md
そのプロジェクト プロジェクトのいちばん上のAGENTS.md
特定の作業フォルダ そのフォルダのAGENTS.md

アプリで共通の指示を編集する入口は、Codexの初期設定にまとめています。

Windowsの既定のCodexホームは、通常 C:\Users\ユーザー名\.codex に相当します。CODEX_HOMEを変更している環境では、そちらが基準です。

「返事は日本語で」は全体共通。「この仕事では入力フォルダを変更しない」は案件別、という分け方です。

近いフォルダの指示が優先される

全体共通、プロジェクト、作業フォルダの順に読み、競合時は近い指示が優先される図

公式ガイドでは、全体共通を読み、その後にプロジェクトのルートから現在の作業フォルダまで、順に指示を重ねると説明されています。同じ内容が競合したときは、作業フォルダに近い側が優先されます。

大事なのは「今どのフォルダで始めたか」です。起動時の探索は現在の作業フォルダで止まります。その下のフォルダの指示書は、起動時の探索では読まれません。

プロジェクトのルートは、多くはGitで管理しているフォルダのいちばん上です。Gitを使っていない場合など、ルートが見つからなければ、プロジェクト側で確認するのは開いた作業フォルダだけです。親フォルダへ置くだけでは届きません。

同じ階層に AGENTS.override.md がある場合は、通常のAGENTS.mdより先に選ばれます。同じ階層の2枚を両方読む仕組みではありません。(公式確認:2026年10月27日)

読まれたか確認する

新しいチャットで決まりを確認する

保存したら、その仕事のフォルダで新しいCodexのチャットを始めます。公式ガイドでは、指示の組み立ては実行開始時と説明されています。

まず、こう頼んでみてください。

今の作業に適用される指示書の場所と、
入力・保存先・元ファイルの扱い・完了前の確認を要約してください。
まだファイルの変更はしないでください。

返事に、自分が決めた保存先と確認事項が入っているかを見ます。ただし、要約できたことと、作業中に守れたことは別です。

小さな作業で結果を確かめる

最初は、個人情報や実際の仕事の資料が入っていない見本で試します。この記事の見本は、次の架空メモです。

実演に使った架空の打ち合わせメモのファイル内容

入力を用意したら、「打ち合わせメモを整理してください。」と頼みます。保存先や3つの見出しを、依頼文で再び指定しない形です。

保存した場所・内容・元ファイルの3つを、実物で照合してください。

確認するもの 見るところ
保存先 出力/打ち合わせの整理.mdが存在するか
内容 要点・次の作業・未定事項があり、日付や予算を補っていないか
元ファイル 入力メモとAGENTS.mdが変わっていないか

私の見本では、作業フォルダと「そのAGENTS.mdを読んで」を追加で伝えたうえで、次の結果を確認しました。

見本では、要点・次の作業・未定事項をまとめたMarkdownが、指定した出力フォルダに保存されました。 候補日を確定日にせず、担当者・台本の確定日・予算は未定のままです。入力メモとAGENTS.mdのファイル内容も変わっていませんでした。

実演で保存された要点・次の作業・未定事項を含むMarkdownファイルの内容表示

保存されたファイルの内容表示です。Codexの操作画面を再現した画像ではありません。

今回試した条件

2026年10月27日、WindowsのCodexアプリで、記事用の架空メモを使いました。最初は普段の仕事をまとめた大きなフォルダを開いていたため、メモを特定できず、作業対象のフォルダと「そのAGENTS.mdを読んで」と追加で伝えています。

これは指示書を読ませて保存先と結果を確かめた1例です。自動読み込みだけで成功した実験や、指示書単独の効果を測った比較実験ではありません。アプリの版・プラン名・使用モデルは未確認です。

「保存しました」という返事や処理の正常終了だけで、保存できたと判断しない。この確認まで含めて、指示書を整えます。

私の使い方:指示書を短くして整理した実例

共通ルールと詳しい手順を分けた

1枚に詰め込んだ指示書を、短い入口と詳しい手順に分ける整理前後の概念図

私の環境でも、Codexにフォルダや仕事の決まりがうまく伝わっていないと感じたことがありました。

2026年9月20日の作業記録では、指示書に書いてあるかだけでなく、その場所で始めたときに届くかを確認しています。全フォルダ共通の地図は、グローバル側に移しました。 作業記録には、司令塔を短く保ち、スキルの本体を別に管理する方針が残っています。

今の作業環境では、AGENTS.mdを入口にし、詳しい手順はスキルのファイルに置いています。 当時の経緯はCodexとClaude Codeの比較でも紹介しています。

読者の方が同じ規模の仕組みを作る必要はありません。最初の1枚には、今の仕事で繰り返す決まりだけを残す。長い手順が増えたときに、別の文書へ分ける順で十分だと考えています。

反映されないときの確認ポイント

ファイル名・置き場所・優先ファイルを調べる

名前と場所、優先ファイル、長さと内容の順に指示書の読み込みを確認する図

まずは、次の順で確認します。

  1. ファイル名がAGENTS.mdになっているか。
  2. 新しいチャットが、意図した作業フォルダを開いているか。
  3. 同じ階層にAGENTS.override.mdがないか。
  4. ほかの階層の指示と矛盾していないか。
  5. プロジェクトの信頼設定で、読み込みが制限されていないか。

2026年10月27日に参照した公開実装には、信頼しない(untrusted)と設定されたプロジェクトの指示書を渡さない処理があります。知らないフォルダを、読み込ませるためだけに信頼済みに変えないでください。まず内容と出どころを確認します。

CLIでファイルの読み取り自体が拒否されるような実行権限の問題は、指示書の文章だけでは解決しません。制限を外す前提にせず、どの操作が拒否されたかを確認します。

長い指示と曖昧な表現を見直す

分かりやすく整理という曖昧な依頼を、要点・次の作業・未定事項という出力の指定に直す図

「分かりやすく整理して」より、要点・次の作業・未定事項の3つに分けてと書く方が、確認する形をそろえられます。

長い指示書なら、重複や今は使わない決まりを見直します。詳しい手順は別ファイルに移し、いつ読むかと場所を指示書に残す方法もあります。

容量の上限について

project_doc_max_bytes の既定値は32KiBです。公式の詳細ガイドは、連結した指示の合計に上限があると説明しています。2026年10月27日に参照した公開実装では、プロジェクト側の指示書を合計して制限する処理を確認しました。

公式の詳細設定ページには「各ファイル」と読める表現も残っています。文書間の表現差があるため、上限まで詰め込むより短く保ち、読まれた内容を確認してください。記事の準備で使ったCLI 0.154.0と、参照した実装の版対応は未確認です。

「消さないで」と書くことと、削除を技術的に止めることも別です。権限設定や検査と組み合わせ、作業後の変更を確認します。

よくある質問

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

はい。日本語の箇条書きで、対象と作業を具体的に書けます。英語の見出しや専用の構文を覚えるところから始めなくて大丈夫です。

CLAUDE.mdはそのまま使えますか?

Codexの通常の探索名はAGENTS.mdです。CLAUDE.mdを代替名にするには、project_doc_fallback_filenames への設定が必要です。同じ階層でAGENTS.mdが選ばれた場合に、両方が自動で足されるわけではありません。

共通の作業ルールは参考にできますが、Claude専用の機能名や手順は見直してください。併用の全体像はClaude CodeとCodexの連携方法で紹介しています。

内容を変えた後はどう確認しますか?

保存して、その作業フォルダで新しいチャットを始めて確認します。指示の要約だけでなく、小さな仕事を頼んで保存先と内容も見ます。

どのくらいの長さにすればよいですか?

一律の推奨行数より、その仕事で毎回必要なことに絞るところからです。この記事の5項目を埋め、長い説明や作業手順は別の文書へ分けます。

まとめ

最初のAGENTS.mdは、いつもの仕事1つを対象に、短い日本語で作ります。

テンプレートの入力と保存先を置き換えたら、新しいチャットで確認。その後、見本の作業で内容と保存先を照合します。

書いて終わりではなく、実物を確かめながら、自分の仕事に合う指示書へ直していきましょう。

参考資料・出典

公式資料は2026年10月27日に確認しました。仕様の説明は公式を根拠にし、公開実装の確認は下記の版に限定しています。

第三者の公開投稿・記事も、構成を考える際に参照しました。次は発信者自身の観測や提案であり、公式仕様や私自身の実績とは区別しています。

企業・事業者のかたへ

自社の業務に AI エージェントを取り入れたい企業・事業者のかた向けに、無料の AI 業務診断を行っています。

無料のAI業務診断を申し込む

個人で学びたいかたへ

Claude Code を自分の仕事で使えるようになるまで、1対1で伴走します。

個別伴走の申込ページへ

この記事を書いた人

芝田拓望のイラスト芝田拓望DevAIse 代表

DevAIse(ディバイズ)代表。毎日5〜15時間、Claude Code と Codex を使い、記事づくり・情報の整理・毎朝のまとめを AI の仕組みにしています。コードを書かずに作ってきたやり方を、1対1の個別伴走でもお伝えしています。

著者ページへ

関連記事

URL をコピーしました