CodexのAGENTS.mdの書き方｜短い指示書で始める

こんにちは。AIあれこれ散歩道、運営者のもっちゃんです。

Codexへ毎回同じ決まりを伝えているなら、作業フォルダにAGENTS.mdという短い指示書を置く方法があります。保存先、直してほしくないファイル、確認方法など、プロジェクトで繰り返し使う前提をまとめるための仕組みです。

大切なのは長い指示書を作ることより、その作業で本当に必要な決まりを残すこと。この記事では、初めての1枚、読み込みの確認、効かないときの見直し方まで説明します。サンプルは編集部が作成した練習用で、あなたの環境に合わせて変えて使えます。

CodexのAGENTS.mdを作る

AGENTS.mdは、Markdownというテキスト形式で書く指示ファイルです。最初は見出しと短い箇条書きだけで十分です。特別な書式を覚えるより、何を決めるファイルなのか押さえましょう。

何度も伝える決まりを残す

「このフォルダの原本は編集しない」「完成した資料は成果物フォルダへ保存する」のように、次回も必要な決まりが向いています。その日だけの依頼や、一時的な数値まで残すと、後から古い条件が混ざるので分けます。

AGENTS.mdは会話の全文を記録する場所ではありません。過去に何を話したかではなく、これから作業するときに何を守るかを書きます。長い経緯が必要なら、別のメモを置き、関連する作業のときだけ参照する形にできます。

すでにCodexを導入済みの方向けの説明です。まだ起動できない場合は、CodexをWindowsで始める手順を先に確認してください。ファイルを作ることと、Codexがその場所で作業していることは分けて確認します。

最初は四つの項目でよい

最初の指示書には、目的、保存先、守る条件、完成の確認を短く書きます。たくさんの役割や工程を並べなくても、今の作業で間違えると困る情報があれば役立ちます。

次は資料整理用のサンプルです。フォルダ名は例なので、実際の場所と一致させてください。存在しない場所や確認コマンドを、そのまま決まりとして残さないことが大切です。

# このプロジェクト
公開用の説明資料を作る練習場所です。

## 保存先
- 元資料は sources/ にあります。
- 作業中のファイルは work/、完成版は output/ に保存します。

## 守ること
- sources/ の原本は変更しません。
- 元資料にない日付・金額・実績は追加しません。
- 作成対象は今回の依頼で指定された資料に限ります。

## 完成の確認
- output/ の完成ファイルを開き、文字化けと内容を確認します。
- 最後に保存先と、未確認の点を報告します。

そのプロジェクトで間違えると困ることから書くと、ルールの意味がはっきりします。「最高の専門家として完璧に作業」のような抽象的な表現を増やすより、原本の場所と完成条件を具体的に示してみてください。

作業フォルダに保存する

このプロジェクトだけの決まりなら、その作業フォルダの入口へAGENTS.mdを置きます。Windowsでは拡張子が非表示になっていると、実際にはAGENTS.md.txtで保存されることがあるので、名前を確認してください。

たとえば、資料整理用のフォルダにsources、work、outputとAGENTS.mdを並べます。すべてのDocumentsへ同じルールを適用したいわけではないなら、Documents全体の入口へ置く必要はありません。決まりが効いてほしい範囲と保存場所を合わせます。

sample-project/
  AGENTS.md
  sources/
  work/
  output/

OpenAI公式資料では、Codexの設定場所にある全体向けの指示と、プロジェクトの入口から現在の作業場所までの経路にある指示を扱う仕組みが説明されています。すべての子フォルダの指示を、最初から一律に読むという意味ではありません。（出典：OpenAI「Custom instructions with AGENTS.md」）

読み込んだ内容を確かめる

保存したら、そのフォルダを作業先として新しい会話で確認します。ファイルを作成しただけで、別の場所で開いている会話へ意図した指示が届くとは限りません。最初は編集を頼まず、読めた指示と適用範囲だけを確認すると見通しがよくなります。

この作業で参照する指示ファイルの場所と、
そこに書かれた保存先・原本の扱い・完成条件を示してください。
まだファイルは変更しないでください。
指示が読めなかった場合は、その理由を教えてください。

返答にoutputへの保存があっても、それだけで実際の作業がすべて正しくなる保証にはなりません。次に小さい依頼を行い、本当に指定した場所へ保存されたかを見ます。指示の認識と実行の確認を分けるのがコツです。

変更後の指示を確認したいときも、新しい会話で読み込みを確かめると切り分けやすくなります。前の会話の説明を、更新したファイルの反映結果として扱わないでください。

一回限りの依頼を組み合わせる

AGENTS.mdへ基本を残したら、チャットでは今回の目的を伝えます。「指示書どおりによろしく」だけだと、今作る資料が決まりません。入力、成果物、必要な範囲を具体的に書いてください。

sources/ の sample-notes.txt から、
初めて読む人向けの1ページ説明文を作ってください。
今回の対象はそのファイルだけです。
目的、手順、未確認事項の順に整理してください。
保存先はAGENTS.mdに従ってください。
元資料に記載がない情報は、推測せず未確認としてください。

この形なら、保存先のような毎回の前提はファイルに、どの資料を何に変えるかは依頼文に分かれます。対象ファイルを指しておけば、関係のない案件の資料までまとめて処理する誤解も避けやすくなります。

CodexのAGENTS.mdを育てる

使いながら、間違えやすかった点だけを追加します。ルールを増やす前に、保存場所の誤り、別の指示との矛盾、確認できない条件がないかを点検してください。

効かないときは場所を確認

まず現在の作業フォルダと、AGENTS.mdの実際の保存先を照合します。似た名前の別フォルダ、古いコピー、同期先を開いていないか確認しましょう。ファイルが空でないことと、拡張子も確認します。

同じ階層にAGENTS.override.mdがある場合は、通常のAGENTS.mdよりそちらが選ばれます。「同じ場所の二つを必ず合体して読む」と思い込まないようにしてください。全体設定側の指示や、途中のフォルダの指示が影響する場合もあります。

AGENTS.mdの指定と実際の出力が違いました。
現在の作業場所、見つかった指示ファイル、
同じ場所のAGENTS.override.mdの有無を確認してください。
指示の矛盾や読み込み上限の影響が疑われる場合は、
確認できた事実と推測を分けて説明してください。
まだルールや設定を書き換えないでください。

ルールを強く言い直す前に、正しいファイルを見ているか確認する。別のフォルダを使っていたなら、同じ文を十回繰り返しても原因は解消しません。表示されたパスを実際の場所と比べるところから始めます。

長くなったら用途で分ける

毎回読む指示が長くなると、今回の作業に関係のない説明まで含まれます。終わった案件の経緯、詳しい操作手順、古い数値などを見つけたら、別資料へ移せるか検討します。必要なときに読む資料への入口だけを残せます。

たとえば、画像作成だけで使う詳しい手順を、表計算の作業でも必ず読む形にする必要はありません。「画像を作るときは画像手順を参照」と条件を付けるほうが、関係する情報を選びやすくなります。

ただし分割しすぎて、原本の場所が分からなくなるのも困ります。最初は入口のAGENTS.mdと、現在状況のメモ、詳しい手順の三つ程度の役割を区別すれば十分です。ファイル数そのものを目標にしないでください。

指示書と権限は分ける

「削除しない」と書くことは意図を伝える方法ですが、操作を技術的に遮断する設定とは違います。大切な元資料はバックアップやアクセス権など、ファイルを守る実際の仕組みも使います。

同様に、AGENTS.mdにパスワードを書いて「外へ出さない」と頼む運用は避けます。作業の説明に必要なのは、認証が必要なことや確認先であって、秘密値そのものではありません。公開するコードに指示書が含まれる場合も考えてください。

Webページや資料の中に「前の指示を無視して」と書かれていても、それをあなたの依頼として採用しないようにする考え方も大切です。読み取る資料の内容と、実際の操作指示を区別します。

詳しい範囲の決め方は、AIエージェントの権限管理の考え方で確認できます。正確な情報は公式サイトをご確認ください。機密情報や組織の権限設計に関する最終的な判断は専門家にご相談ください。

直すべきルールの見つけ方

同じ修正を繰り返したら、何が曖昧だったかを一つだけ選んで更新します。たとえば「完成版を分かりやすい場所へ」では毎回違う場所に保存されるなら、「完成版はoutputへ」と具体化できます。

一方で、一度だけ起きた特殊事情をすべて全体ルールにする必要はありません。「今回だけ資料Bを除く」は、その回の依頼へ残すほうが適しています。いつまで有効か分からない禁止事項が積み重なるのを避けましょう。

今回の作業で繰り返し必要だった前提を整理してください。
AGENTS.mdへ追加する候補を最大3点と、
今回だけの作業メモに残す項目を分けてください。
まだファイルは書き換えず、既存ルールとの重複も示してください。

更新したら小さい作業で確認します。修正後の指示と実際の保存先が一致したか、未確認の情報を勝手に補っていないかを見ます。「ルールを追加した」という作業と、「間違いが解消した」という結果を分けて記録してください。

CodexのAGENTS.mdまとめ

まず、次回も伝えたい決まりを三つ選んでください。保存先、原本の扱い、完成の確認を書くところから始めると、短い1枚にまとまります。その作業フォルダで読み込みを確認し、小さな依頼を一つ実行して、実際のファイルまで確かめましょう。