AGENTS.md
Codex・Claude Code時代のAIエージェント用READMEの書き方

AIコーディングエージェントを使い始めると、最初は驚くほど便利です。HTMLを直す、テストを書く、ファイルを整理する、差分を作る。人間が手でやっていた作業を、AIがかなりの速度で進めてくれます。ところが、しばらく使うと別の問題が出てきます。

• 毎回「このプロジェクトはNext.jsです」と説明している
• AIが触ってほしくない生成ファイルを直してしまう
• テストコマンドを知らず、動作確認せずに修正する
• チームの命名規則やディレクトリ構成を無視する
• Claude、Codex、Copilotで指示ファイルがバラバラになる

この問題を減らすためのファイルがAGENTS.mdです。ひと言で言うと、AGENTS.mdはAIエージェント用のREADMEです。人間向けのREADMEとは別に、AIが作業前に読むべきルール、手順、禁止事項を書いておきます。

AGENTS.mdとは何か

AGENTS.mdは、リポジトリ内に置くMarkdownファイルです。AIコーディングエージェントが作業を始める前に読み、プロジェクトの前提を理解するために使います。

人間でたとえるなら、新しく入った開発者に渡す「このプロジェクトの作業ルール」です。どのコマンドで起動するのか、どのフォルダに何があるのか、どのファイルは直接編集してはいけないのか、テストは何を走らせるのか。これをAI向けに簡潔にまとめるのがAGENTS.mdです。

ファイル	主な読者	書く内容
README.md	人間	プロジェクト概要、使い方、セットアップ、貢献方法
AGENTS.md	AIエージェント	作業ルール、テスト、禁止事項、ディレクトリ構成、コーディング規約
CLAUDE.md	Claude Code	Claude向けの追加指示、作業方針、好みの進め方
copilot-instructions.md	GitHub Copilot	Copilot向けのコーディング規約や回答方針

なぜ今AGENTS.mdが重要なのか

2025年以降、AIコーディングは「チャットでコードを書いてもらう」段階から、「エージェントがリポジトリの中で作業する」段階に移っています。Codex、Claude Code、Cursor、Devin、Copilot系ツールなど、AIがファイルを読み、修正し、テストし、場合によってはPRまで作る流れが一般化しつつあります。

この時に重要なのは、AIがコードを読めることだけではありません。そのプロジェクトで守るべき暗黙知を、AIに明文化して渡せるかです。人間のチームなら口頭で伝えるルールも、AIにはファイルとして置いておく必要があります。

テック比較ジャーナルの決め台詞で言うなら、AIエージェント時代のREADMEは、人間だけに向けて書いていては足りないということです。

AGENTS.mdがあると何が変わるのか

作業	AGENTS.mdなし	AGENTS.mdあり
ファイル修正	AIが構成を推測しながら触る	どこを触るべきか最初から分かる
テスト	どのコマンドを走らせるか分からない	指定コマンドで確認しやすい
生成ファイル	誤って直接編集することがある	「編集禁止」と明記できる
命名規則	AIの好みで書く	プロジェクトの規約に寄せられる
レビュー	なぜその修正をしたか確認しにくい	作業基準が残るためレビューしやすい

どこに置くのか

基本はリポジトリのルートに置きます。

my-project/
├── AGENTS.md
├── README.md
├── package.json
├── src/
└── tests/

大きなプロジェクトでは、サブディレクトリごとに追加のAGENTS.mdを置くこともあります。たとえばフロントエンド、バックエンド、決済機能でルールが違う場合です。

my-project/
├── AGENTS.md              # 全体ルール
├── frontend/
│   └── AGENTS.md          # フロント固有ルール
├── backend/
│   └── AGENTS.md          # バックエンド固有ルール
└── services/
    └── payments/
        └── AGENTS.override.md  # 決済だけの厳格ルール

考え方はシンプルです。上の階層に共通ルール、下の階層に個別ルールです。AIエージェントは作業場所に近い指示を優先するため、危険な領域ほど近くに強いルールを置くと安全です。

まず書くべき5項目

最初から完璧なAGENTS.mdを書く必要はありません。初心者は、まず次の5項目だけで十分です。

1. Project Overview：このプロジェクトが何をするものか
2. Tech Stack：フレームワーク、言語、DB、主要ライブラリ
3. Directory Guide：どのフォルダに何があるか
4. Commands：起動、テスト、ビルド、lintのコマンド
5. Do / Do Not：やっていいこと、禁止事項

最小テンプレート

まずはこの程度で大丈夫です。長すぎるより、短くても正確な方がAIには効きます。

# AGENTS.md

## Project Overview
This is a Japanese tech media site built with static HTML/CSS.
The site publishes comparison articles about AI tools, SaaS, and gadgets.

## Tech Stack
- HTML / CSS / Vanilla JavaScript
- No build step
- Google AdSense placeholders are kept in article pages

## Directory Guide
- /ai/      AI category pages
- /saas/    SaaS category pages
- /gadget/  Gadget category pages
- /blog/    Journal articles
- /css/     Shared styles
- /js/      Shared scripts

## Commands
No build command is required.
Check pages by opening the HTML file in a browser.

## Editing Rules
- Preserve existing header, footer, AdSense placeholders, and cookie-consent script.
- Do not remove canonical URLs unless the slug changes.
- Do not change affiliate links unless explicitly instructed.
- Keep Japanese tone natural and practical.
- For comparison articles, include real usage scenarios, not only spec tables.

## Do Not Edit
- Do not edit /css/style.css unless the task explicitly asks for style changes.
- Do not remove Google tag or AdSense scripts.
- Do not invent hands-on claims that were not provided.

CLAUDE.mdとの使い分け

Claude Codeを使っている人は、CLAUDE.mdも見かけるはずです。混乱しやすいですが、役割分担を決めれば難しくありません。

内容	AGENTS.md	CLAUDE.md
全エージェント共通のルール	書く	必要なら参照
Claudeにだけ守らせたい進め方	書かない	書く
技術スタック・構成	書く	重複させない方が楽
回答スタイルや確認頻度	最低限	Claude用に細かく書く

おすすめは、AGENTS.mdに共通ルール、CLAUDE.mdにClaude固有の好みです。たとえばAGENTS.mdには「広告コードは消さない」「テストコマンドはこれ」と書き、CLAUDE.mdには「変更前に要約を出す」「日本語で説明する」「大きな変更は段階的に提案する」と書きます。

良いAGENTS.mdと悪いAGENTS.md

観点	悪い例	良い例
長さ	社内規約をそのまま何千行も貼る	AIが作業で使う要点だけを書く
禁止事項	「注意して作業」だけ	「/generated は編集禁止」と具体的に書く
テスト	「適宜テスト」	「JS変更後は npm run test を実行」
更新	初回作成後に放置	構成変更時にAGENTS.mdも更新
表現	曖昧な精神論	ファイル名、コマンド、条件を明記

サイト運営者向けAGENTS.md例

このサイトの読者には、ブログや比較サイトを運営している人も多いはずです。そういう人向けには、次のような指示が効きます。

## Editorial Rules
- 記事はテンプレート感を避け、実際の利用シーンを必ず入れる。
- 比較記事では「誰に向くか」「どの場面で使うか」を明記する。
- AdSense審査を意識し、薄い紹介文だけで終わらせない。
- アフィリエイトリンクがある場合、URLとIDは勝手に変更しない。
- 公式情報が変わる可能性がある料金・仕様は、確認日を明記する。

## HTML Rules
- header / footer / breadcrumb / cookie-consent script は維持する。
- 広告枠や広告コードの追加・削除は、作業指示がある場合だけ行う。
- FAQを追加する場合は、本文側とFAQPage JSON-LDの内容を揃える。
- title と meta description は検索意図に合わせて更新する。

こう書いておくと、AIに記事改修を頼む時にかなり安定します。特に「アフィリエイトリンクを勝手に変えない」「広告枠を消さない」は、サイト運営ではかなり重要です。

チーム開発でのAGENTS.md運用

チームで使う場合、AGENTS.mdは単なるAI向けメモではなく、人間チームの暗黙知を明文化する場所にもなります。新しく参加した人間も読めますし、AIエージェントも読めます。つまり、人間とAIの両方に効く作業ルールになります。

• 新しいメンバーが最初に読む作業ルールになる
• AIエージェントごとの指示のばらつきを減らせる
• レビュー時に「このルールに沿っているか」を確認しやすい
• AIが作った差分の事故を減らせる

ただし、AGENTS.mdを万能な憲法のように巨大化させると逆効果です。長すぎるとAIも重要な指示を見落としやすくなります。AGENTS.mdは短く、詳しい規約は別ファイルへが基本です。

作成手順：まず30分で作るなら

1. READMEを読む：人間向け情報から、AIにも必要なものを抜き出す。
2. package.jsonや設定ファイルを見る：使用フレームワーク、テスト、lint、buildコマンドを確認する。
3. 触ってはいけない場所を書く：generated、dist、vendor、環境設定、広告コードなど。
4. よく頼む作業を書く：記事修正、テスト追加、UI修正、API変更など。
5. 短いAGENTS.mdとして保存：最初は100〜200行以内でよい。
6. AIに読み上げさせる：「このAGENTS.mdを読んで、守るべきルールを要約して」と確認する。

AGENTS.mdの失敗例

やりがちな失敗も整理しておきます。

• 古い情報が残る：Next.js 14から15に上げたのにAGENTS.mdが古いまま。
• 禁止事項が曖昧：「重要ファイルに注意」ではなく、具体的なパスを書くべき。
• テストコマンドがない：AIが修正後に確認できない。
• 個人の好みを書きすぎる：重要なルールが埋もれる。
• 各ツール専用ファイルと矛盾する：AGENTS.mdとCLAUDE.mdで違うルールを書くとAIが迷う。

総評

AGENTS.mdは、これからAIコーディングエージェントを使う人にとって、かなり重要なファイルになります。派手な機能ではありませんが、AIに作業を任せるなら、最初に整えるべき土台です。プロジェクト概要、技術スタック、ディレクトリ構成、テストコマンド、禁止事項。この5つを書くだけでも、AIの迷い方は大きく変わります。

テック比較ジャーナルとしての決め台詞はこれです。AIにコードを書かせる前に、AIが迷わない地図を置く。それがAGENTS.mdです。 エージェント時代の開発では、コードを書く力だけでなく、AIに正しく作業させるための説明力も重要になります。

そのまま使える：AGENTS.md作成プロンプト

最後に、実際に使える最低限のプロンプトを置いておきます。下の 【 】 の中だけ自分のプロジェクトに合わせて編集し、Claude Code、Codex、ChatGPT、Geminiなどに貼り付ければ、AGENTS.mdのたたき台を作れます。

あなたはAIコーディングエージェント運用に詳しいエンジニアです。
以下の情報をもとに、私のプロジェクトで使う AGENTS.md を作成してください。
目的は、Codex / Claude Code / Cursor / Copilot などのAIエージェントが、リポジトリの構成・作業ルール・禁止事項を正しく理解できるようにすることです。

# プロジェクト概要
【例：AI/SaaS/ガジェット比較サイト。静的HTMLで記事を管理している】

# 技術スタック
【例：HTML / CSS / JavaScript。ビルド工程なし。共通CSSは /css/style.css】

# ディレクトリ構成
【例：/ai はAI記事、/saas はSaaS記事、/gadget はガジェット記事、/css は共通CSS、/js は共通スクリプト】

# AIに任せたい作業
【例：HTML記事のリライト、FAQ追加、meta description調整、内部リンク追加、表の整理】

# 特に守ってほしいこと
【例：AdSenseコード、Google tag、canonical URL、cookie-consent script、既存のアフィリエイトリンクIDは勝手に削除・変更しない】

# 触ってほしくないファイル・注意が必要なファイル
【例：/css/style.css は明示指示がない限り変更しない。/js/cookie-consent.js は変更しない】

# 確認方法・テスト方法
【例：ビルドなし。HTML構文を確認し、ブラウザ表示で崩れがないか確認する】

# 出力条件
- Markdown形式で AGENTS.md の本文だけを出力してください。
- 長すぎる規約集ではなく、AIが作業前に読んで迷わない実用的な内容にしてください。
- 「Project Overview」「Tech Stack」「Directory Guide」「Editing Rules」「Do Not Edit」「Commands / Checks」の見出しを入れてください。
- 禁止事項は曖昧にせず、具体的なファイル名・ディレクトリ名・作業例で書いてください。
- 日本語で書いてください。
- 最後に、今後AGENTS.mdを更新すべきタイミングも短く書いてください。

このプロンプトで出てきたAGENTS.mdをそのまま置くのではなく、最後に人間が一度だけ確認してください。特に、触ってはいけないファイル、広告コード、アフィリエイトリンク、環境変数、デプロイ手順は、プロジェクトごとに事故になりやすい部分です。AIに任せる前に、ここだけは人間が固めるのが安全です。

よくある質問

AGENTS.mdとは何ですか？

AGENTS.mdとは、AIコーディングエージェントにプロジェクトのルール、構成、テスト方法、禁止事項を伝えるためのMarkdownファイルです。AI向けのREADMEのような役割を持ちます。

AGENTS.mdとREADME.mdの違いは何ですか？

README.mdは人間向けの説明、AGENTS.mdはAIエージェント向けの作業指示です。セットアップ、テスト、触ってはいけないファイル、コーディング規約など、AIが作業前に読むべき情報を書きます。

AGENTS.mdとCLAUDE.mdの違いは何ですか？

AGENTS.mdはCodexなど複数のAIエージェントが参照しやすい汎用ファイルで、CLAUDE.mdはClaude Code向けの専用指示として使われることが多いです。

AGENTS.mdはどこに置きますか？

基本はリポジトリのルートに置きます。サブディレクトリにも置け、より深い階層のAGENTS.mdやAGENTS.override.mdでその範囲の指示を上書きできます。

AGENTS.mdに最低限書くべきことは何ですか？

プロジェクト概要、技術スタック、主要ディレクトリ、テスト・ビルドコマンド、禁止事項の5つです。特に禁止事項とテストコマンドはAIエージェントの事故防止に効きます。

← JOURNALに戻る ｜ AIツール一覧を見る →