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エージェントに共有する作業ルールとして考える必要があります。