AGENTS.md でプロジェクトのルールを設定

Codex 学習目次に戻る

このレッスンでできること

指示ファイルには、毎回繰り返すテストコマンドやデータ保持の条件を保存できます。認証情報の保管庫ではなく、ネットワークやファイルの権限を増やすものでもありません。権限は承認とサンドボックスで扱います。「すべて許可する」と書いても実行環境の設定は変わりません。

始める前に

ToDo 練習教材をダウンロードして展開し、expected フォルダーをコピーして codex-practice と名付けます。このレッスンでは完成した参考版を使い、未実装のフィルターをルールの問題と混同しないようにします。データは架空です。個人のプロジェクトやグローバル設定はまだ変更しません。

フォルダー直下に index.html、style.css、app.js、core.mjs、core.test.mjs があることを確認します。利用できる Codex デスクトップアプリまたは CLI を用意してください。テストには Node.js、ローカルプレビューには Python 3 を使います。まず指示ファイルだけ作り、ツールの準備は最初のプロジェクトで後から行ってもかまいません。

指示はどこから読み込まれるか

Codex はグローバルとプロジェクトの指示を組み合わせます。グローバルの既定位置はホームディレクトリ内の .codex で、CODEX_HOME が設定されていればその場所を使います。プロジェクトではルートから現在の作業ディレクトリまで順に探索します。作業場所に近い指示で前の条件を具体化できますが、存在するすべての子フォルダーを自動的に読むわけではありません。

同じディレクトリでは AGENTS.override.md、AGENTS.md、設定済みの代替名の順に探します。同じ階層の候補をすべて足し合わせる仕組みではありません。README.md は通常、人にプロジェクトを説明する文書です。Markdown というだけで指示ファイルにはなりません。プロジェクト指示の合計は既定で 32 KiB が上限です。上限を増やす前に、重複した説明や大きなサンプルを整理してください。

今回は練習プロジェクトの AGENTS.md だけを追加します。グローバルな好みは他のプロジェクトにも影響するため、何が本当に共通か分かってからconfig.toml の設定と公式文書を確認します。

プロジェクトルートを見つけられない場合、指示の探索対象は現在のディレクトリだけです。Git を使わないこの例は codex-practice 直下から開始し、任意の子フォルダーからでも親のルールが見つかるとは考えないでください。リポジトリ内の比較はルールの適用範囲、長い文書の分割はルールと参考資料の役割で扱います。

手順 1：場所とファイル名を確認する

Windows ではエクスプローラーで codex-practice を開き、拡張子を表示して、テキストエディターで AGENTS.md を作ります。AGENTS.md.txt になっていないか確認してください。そのフォルダーで PowerShell を開き、次を実行します。5 個の練習ファイルが表示されるはずです。expected の一つ上にいる場合は、正しいフォルダーに移動します。

Get-Location
Get-ChildItem -Name

macOS では練習フォルダーでターミナルを開くか、Terminal に cd と入力して Finder からフォルダーのパスをドラッグします。Linux はファイルマネージャーの「端末で開く」を使います。両方とも次のコマンドで場所を確認し、プレーンテキストの同名ファイルを作ります。Linux でも見つかるよう、大文字と小文字を正確に保ちます。

pwd
ls -a

すでに AGENTS.md があれば、先に内容を読み、元の指示を残して必要な項目だけ統合します。新しい練習コピーにはこのファイルはありません。手順に合わせるために他のプロジェクトの指示を上書きしないでください。

手順 2：具体的なルールを書く

以下がファイル全体です。追加パッケージは不要です。五つの言語で同じ内容を使うため英語にしていますが、自分のルールは使いやすい言語で書けます。コマンドが実在し、範囲が具体的で、結果を確認できることが大切です。

# Small Steps practice instructions

- Work only inside this practice folder.
- Keep the existing task data format and localStorage key unchanged.
- Do not add packages or external network requests for this exercise.
- Run `node --test core.test.mjs` after changing JavaScript.
- After changing HTML or CSS, check the page at 390px and 1280px widths.
- Preserve visible keyboard focus and accessible form labels.
- In the final response, list changed files, checks run, and checks not run.
- Say why a check could not be run; do not report it as passed.

「品質を良くする」だけでは確認基準がありません。この例は品質をテストコマンド、画面幅、キーボードフォーカス、報告内容に分解しています。npm test には置き換えないでください。この教材に package.json はなく、存在しないコマンドを指定すると毎回失敗します。

手順 3：新しいセッションで読み込みを確認する

保存したら、練習フォルダーから新しい Codex セッションを始めます。デスクトップではこのプロジェクトを選び、新規タスクを作ります。CLI では古い対話を終了し、このフォルダーで codex を再実行します。指示はセッション開始時に収集されるため、会話中にファイルを書き換えただけで再読み込みされたとは判断できません。

List the AGENTS.md or AGENTS.override.md files loaded for this task.
Summarize the rules that apply to this practice folder.
Do not modify any files. If you cannot establish a source, say so.

練習フォルダーの AGENTS.md の場所と、テスト、表示、報告の要件が示されることを期待します。回答だけを証拠にせず、ファイルを開いて内容を照合します。正しいパスがなく依頼文を繰り返すだけなら、変更を頼む前に作業場所とファイル名を直します。

手順 4：小さな変更で行動を確認する

In index.html, change the main heading to "Small steps, clear progress."
Keep the todo behavior, stored data, and other visible text unchanged.
Follow the project instructions. Show the changed file and report the checks.

差分は主に index.html の見出し文字列になるはずです。Windows では py -m http.server 4173 --bind 127.0.0.1、macOS／Linux では python3 -m http.server 4173 --bind 127.0.0.1 でプレビューを開始します。http://127.0.0.1:4173 を開き、見出し、二つの幅、Tab のフォーカスを確認し、Read を追加して完了にします。Codex にブラウザがなければ自分で確認し、未実施の項目を報告させます。

正常な例では、変更範囲が正しく、データが残り、報告が指示に沿っています。境界の例はブラウザが使えない場合です。制約と手動確認項目を示すのが適切で、スクリーンショットや成功を作り話にしてはいけません。ルールがあっても、実際のファイルやツールによる確認は必要です。

ルールと証拠を一つずつ対応させる

見出しだけの変更では「JavaScript を変更した後」という条件は成立しません。それだけでテスト漏れとは判断しないでください。コマンドが動くかは次の読み取り専用の依頼で別途確認できます。expected は成功 3 件、失敗 0 件になる想定です。これはコマンドと報告の確認であり、ルールの全分岐を実測したことにはなりません。

Run node --test core.test.mjs from this practice folder without editing any files.
Report the working folder, command, exit status, and test counts.
If the command cannot run, quote the error and mark the check NOT RUN.

よくある問題と元に戻す方法

見つからない場合は、選択したプロジェクト、実際の拡張子、空のファイル、同じ階層の override を順番に確認します。Windows で読めた別表記が Linux でも読めるとは限りません。修正したら新しいセッションで再試行します。

ルールが衝突する場合は、深いフォルダーやグローバル override を含め、出典の階層を確認します。共通ルールとこのフォルダーの例外を明示し、互いを否定する文を増やさないでください。階層の詳しい追跡は後のレッスンで扱い、今回は一つのプロジェクトファイルに留めます。

テストが実行されない場合は、まず JavaScript を変更したか確認します。次に node --version と作業場所の core.test.mjs を確認します。実行環境がないことと指示が未読であることは別の問題です。「通るはず」ではなく実際のエラーを求めます。

プレビューは Ctrl+C で停止します。見出しは今回の変更だけを戻します。今回作成した AGENTS.md は練習フォルダーの外に移して保存できます。既存のファイルに追記した場合は自分の項目だけ戻します。ルールを除いても、すでに行われたファイル変更は戻りません。指示の状態も新しいセッションで確認します。

練習と出典

最終回答で手動確認事項を先に示すルールを加え、新しいセッションで別の見出し変更を頼みます。出典を特定でき、差分が指定した見出しだけで、報告順が変われば成功です。追加したルールを除き、次の新規セッションと比較します。

確認日は 2026-09-14 です。探索とサイズ制限は AGENTS.md 公式文書で確認しました。教材サイトとデータテストは Windows／Edge で検証済みですが、macOS、Linux、Codex の指示読み込みを実機検証したという意味ではありません。次は Markdown、引き継ぎ、Skillsを参照してください。

Codex 学習目次に戻る

詳しい説明を読む

Global to Project to Working directory

• AIツール
• チュートリアル
• Codex