AGENTS.mdとは？Codex・Copilot code reviewにプロジェクトルールを伝える基本

冒頭の結論：AGENTS.mdはAI向けの作業ルール

AGENTS.mdとは、CodexのようなAIエージェントに対して、プロジェクトの前提、作業ルール、禁止事項、確認方法を伝えるための指示ファイルです。人間でいえば、開発前に読む作業メモや運用ルールに近いものです。

毎回チャットで「このサイトはReact + Viteです」「公開URLは変えないでください」「buildを通してください」と説明するより、AGENTS.mdにまとめておく方が安定します。個人開発でも、AIに作業を頼む回数が増えるほど効いてきます。

この記事で分かること

• AGENTS.mdとは何か、Codexのプロジェクト設定でなぜ重要なのか
• AGENTS.mdの書き方と、書くべき項目
• 書かない方がいい内容と、更新を放置する危険
• 個人開発サイト向けのAGENTS.md例

AGENTS.mdに書くべきこと

AGENTS.mdには、AIが作業を始める前に知っておくべきことを書きます。プロジェクト概要、使用技術、ディレクトリ構成、実行コマンド、やってはいけないこと、デザイン方針、SEO方針、ビルド確認方法、デプロイ時の注意点などです。

Codexでなぜ重要なのか

Codexは実際のファイルを読んで修正できるため、毎回のチャット指示だけに頼ると作業範囲や確認手順がぶれます。AGENTS.mdに「触ってよいフォルダ」「buildコマンド」「upload反映の有無」「push前に人間が確認すること」を書いておくと、AIに任せる作業と人間が判断する作業を分けやすくなります。

個人開発サイト向けのAGENTS.md例

# Project Rules

- This is a React + Vite static site.
- Run `npm run build` before finishing changes.
- Do not change public URLs without confirmation.
- Keep the design clean and readable.
- SEO title, description, canonical, and OGP must be checked when adding pages.

Obsidianや作業ログとの違い

Obsidianや作業ログは、人間が後から経緯を振り返るための場所です。一方でAGENTS.mdは、Codexに作業前提を伝えるための場所です。判断ログや会話全文を詰め込むのではなく、AIが作業時に守るべきルールだけを短く置くと使いやすくなります。

この例は短いですが、最初はこのくらいで十分です。AGENTS.mdに禁止事項を書く前に、Codexのフルアクセス相当の権限で危険になりやすい操作を確認し、よく起きる事故、毎回確認してほしいこと、触ってほしくないファイルを少しずつ足していく方が続きます。

個人開発者にとって重要な理由

個人開発では、開発者、編集者、デザイナー、運用担当が同じ人になりがちです。Codexに依頼するたびにルールが変わると、サイトの文体、デザイン、URL、SEO設定がぶれます。AGENTS.mdは、そのぶれを減らすための足場です。

向いているケース

• 同じプロジェクトでCodexに何度も作業を頼む
• 記事追加、CSS調整、SEOメタ修正など定型作業がある
• 公開URLや納品フォルダなど、守るべき運用ルールがある
• AIに触ってよい範囲と触ってほしくない範囲を分けたい

向いていないケース・注意点

• 長すぎるルールは読みにくく、重要事項が埋もれる
• 古いコマンドや古いディレクトリ構成を放置すると逆効果
• Codexが必ず完璧に守るとは限らないので最終確認は必要
• プロジェクトごとに内容を変えず使い回すと、誤作業の原因になる

よくある誤解

AGENTS.mdを書けばAIが絶対にミスをしない、というわけではありません。AGENTS.mdは事故を減らすための補助線です。最終的には、人間が差分、ビルド結果、公開前の表示を確認する必要があります。

まとめ：AGENTS.mdは短く、具体的に、更新する

AGENTS.mdとは、Codexにプロジェクトルールを伝える基本のファイルです。完璧な長文を書くより、守ってほしいことを短く具体的に書き、運用しながら更新する方が実用的です。

AGENTS.mdにはレビューを軽くする情報を書く

AGENTS.mdは、AIにプロジェクトの作法を伝えるだけでなく、レビューしやすい差分を作らせるための安全装置です。禁止ファイル、build/check、upload/sitemap、完了報告フォーマットを短く固定します。

ZCodeもAGENTS.mdを読むが、CLAUDE.mdとは役割が違う

ZCode公式docsでは、~/.zcode/AGENTS.mdと現在workspaceのAGENTS.mdを読むと説明されています。CLAUDE.mdは継続的に読むのではなく、既存Claude Code projectのonboarding時の移行元として扱われます。

AGENTS.mdは、長時間エージェントに仕事の境界を渡すファイルになる

AI利用が委任タスクへ寄るほど、毎回の口頭指示だけでは足りません。AGENTS.mdには、触ってよい範囲、禁止操作、検証コマンド、commit/push、本番反映の扱いを書き、レビュー可能な作業へ寄せます。

AGENTS.mdは増やすより測る

SWE-Skills-Benchは、Agent Skillsが常にpass-rateを上げるわけではなく、token overheadやversion mismatchで悪化する場合もあることを示します。AGENTS.mdも同じで、禁止事項、確認コマンド、作業範囲のように効くルールへ絞り、古い手順や重複は減らします。

GitHub Copilot code reviewもAGENTS.mdを読む時代に

GitHubは2026年6月18日のChangelogで、Copilot code reviewがrepository-level AGENTS.mdに対応し、repo rootのAGENTS.mdを読み、関連する指示をレビューコメント生成に使うと案内しました。AGENTS.mdはCodexだけの説明書ではなく、複数のAIエージェントに共有する作業ルールとして考える必要があります。

AGENTS.mdは階層と現在の作業ディレクトリで効き方が変わる

AGENTS.mdを1枚置けば常に同じ指示になるわけではありません。Codexはglobal guidanceとproject-specific guidanceを分け、project rootから現在の作業ディレクトリへ向かってinstructionを結合します。後から結合される下位ディレクトリの指示が、上位の一般的な指示を上書きするため、repo全体のルールはroot、特定サービスのルールは対象ディレクトリの`AGENTS.override.md`などに分けます。

探索結果が古い・足りないときの確認

• Codexを対象repoの意図したdirectoryから起動し、`CODEX_HOME`が別profileを指していないか確認する。
• `AGENTS.override.md`が上位ディレクトリやglobalに残っていないか確認する。通常名が無視されている場合はfallback filenameの設定を確認する。
• 指示が切れている場合は、長文を詰め込むのではなく、`project_doc_max_bytes`を確認して重要なルールを分割・先頭配置する。
• 設定やファイルを変更した後は新しいcommandまたはTUI sessionで再確認し、実際に読み込まれたinstruction sourceをログで監査する。

AGENTS.mdとRulesは、指示とcommand policyを分けて使う

AGENTS.mdはプロジェクトの前提、禁止事項、確認手順を伝える指示ファイルです。一方、Rulesはsandbox外でcommandを実行するときのdecisionを制御する層です。Rulesを追加しただけでrepoの指示、sandbox、permission profile、MCP、secret管理、diff確認が不要になるわけではありません。project-local rulesは、その`.codex/` layerをtrustedと判断した場合だけ読み込まれるため、初見repoのRulesを自分の許可設定として受け入れないようにします。

Rulesを追加・変更する前の停止条件

• Rulesはexperimentalと明示されているため、長期運用の前に現行公式Docsと実際のCodex versionを確認する。
• 初見repoの`.codex/rules/`をそのままuser layerへコピーせず、project layerをtrustedにする判断と所有者を分けて記録する。
• allowはsandbox外のmatching commandのpromptを省く設定であり、repo全体、filesystem、network、MCP、secretへの広い許可とは扱わない。
• ruleを追加した後はCodexを再起動し、`codex execpolicy check --pretty --rules ~/.codex/rules/default.rules -- git status`のように安全なcommandでstrictest decisionとmatched rulesを確認する。
• Smart approvalsが提案するprefix_ruleは自動承認せず、patternが広すぎないか、justificationが代替手段を示しているかを確認する。
• requirements.tomlで管理者がrestrictive ruleを強制できるため、組織policyと矛盾するallowをローカルで足して回避しない。
• Rulesを確認しても、secret、外部送信、生成物、diff、test、push、deployの人間レビューは省略しない。

codex execpolicy check --pretty --rules ~/.codex/rules/default.rules -- git status