AGENTS.md入門——AIコーディングエージェント向けリポジトリ説明書の書き方と60,000件採用の実績

AGENTS.md とは何か

AGENTS.mdは、AIコーディングエージェントがリポジトリで作業するための「取扱説明書」だ。

README.mdが人間の開発者向けに書かれているのに対し、AGENTS.mdはエージェントが確実に動作するために必要な情報——ビルド手順、テストの実行方法、コーディング規約、禁止パターン——を提供することに特化している。

AGENTS.md の役割:

  README.md  → 「このプロジェクトは何をするものか」（人間向け）
  AGENTS.md  → 「このプロジェクトでどう作業するか」（AIエージェント向け）

2025年にAnthropicが主導して策定され、2025年12月にLinux Foundationの**Agentic AI Foundation（AAIF）**に寄贈されたオープン標準だ。2026年4月時点で60,000以上のオープンソースリポジトリが採用している。

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

エージェントは「暗黙の了解」を知らない

優秀なエージェントでも、プロジェクト固有の事情は知る術がない。

エージェントが AGENTS.md なしに犯しがちな失敗:

  ❌ テストを npm run test で実行しようとする
     → 実際は pnpm run test:unit && pnpm run test:e2e の2ステップが必要

  ❌ コンポーネントを src/components/ に作る
     → 実際は機能別ディレクトリ構成で src/features/auth/components/ が正しい

  ❌ ESLint の設定を無視してコードを書く
     → CI で lint エラーが出てPRが壊れる

  ❌ 型エラーを any で回避する
     → プロジェクトポリシーで any 禁止

これらの「暗黙の了解」をAGENTS.mdに書くことで、エージェントの精度が大幅に改善する。

実測された効果

arXiv に投稿された研究（2026年）によれば、詳細なAGENTS.mdを持つプロジェクトでは：

エージェント生成コードのバグが平均**35〜55%**少ない（コミュニティリーダーボード調べ）
CIが初回で通る割合が有意に向上
コードレビューコメント数が減少

GitHubが2,500以上のリポジトリを分析した調査でも同様の傾向が確認されている。

サポートするエージェント

AGENTS.md を公式サポートするエージェント（2026年4月）:

  Anthropic  : Claude Code（このリポジトリもCLAUDE.mdで同等の仕組みを使用）
  OpenAI     : Codex（openai.com/codex）
  Google     : Gemini CLI
  GitHub     : GitHub Copilot（Coding Agent）
  Anysphere  : Cursor
  Cognition  : Devin
  Factory    : Factory
  Augment    : Amp
  Jules      : Jules（Google）
  VS Code    : VS Code Agent Mode

CLAUDE.mdやCOPILOT_INSTRUCTIONS.mdなどのエージェント固有ファイルも引き続き動作するが、AGENTS.mdは一つのファイルで全エージェントをカバーできる標準として急速に普及している。

AGENTS.md の基本フォーマット

ファイルは単純なMarkdownで書く。6つのコアセクションをカバーすることが推奨されている。

最小構成の例（Astro/TypeScriptプロジェクト）

# AGENTS.md

## Build & Test

\`\`\`bash
# 型チェック・lint
pnpm check

# 自動修正
pnpm check:fix

# テスト実行
pnpm test

# ビルド
pnpm build
\`\`\`

## Project Structure

\`\`\`
src/
  content/posts/   # ブログ記事（Markdown）
  components/      # Astroコンポーネント
  layouts/         # ページレイアウト
  pages/           # ルーティング
tests/             # Vitestテスト
\`\`\`

## Code Style

- TypeScript strict mode 有効
- `any` 型は禁止（`unknown` を使うこと）
- インポートパスは絶対パス（`@/` エイリアス）

## Article Conventions（このリポジトリ固有）

- 記事ファイル: `src/content/posts/YYYY-MM-DD-{slug}.md`
- フロントマターの `pubDate` は引用符なし: `pubDate: 2026-04-27`
- `draft: false` でないと本番にデプロイされない

## Git Workflow

- ブランチ命名: `feature/` `fix/` `chore/`
- コミットメッセージ: Conventional Commits（`feat:`, `fix:`, `chore:`）
- PRはsquash merge

## Boundaries（触れてはいけないもの）

- `src/content/content.config.ts` はスキーマ定義、変更前に必ず確認
- `vercel.json` は触らない
- `package.json` の `engines` フィールドは変更しない

効果的な書き方のポイント

コマンドはバッククォートで囲む

# ❌ 曖昧な表現
テストを実行してください

# ✅ コピー&ペーストできる形式
テストを実行する: `pnpm test`
型チェック: `pnpm check`

エージェントはバッククォートで囲まれたコマンドを「実行すべきシェルコマンド」として認識する。

150行以内に収める

AGENTS.md のサイズガイドライン:

  50行以下  → 情報不足（エージェントが推測で補完する）
  50〜150行 → 最適（具体的で簡潔）
  150行以上 → 過剰（エージェントの指示追従品質が低下し始める）

長くなりすぎる場合は、ファイルを分割して docs/AGENTS_BACKEND.md のように参照させる。

禁止事項は明示的に書く

## Boundaries

- `node_modules/` は直接変更しない
- `*.generated.ts` ファイルは手書きしない（ビルド生成物）
- テストのスナップショットは `pnpm test:update-snapshots` で更新
  （手動編集禁止）

「やってはいけないこと」は暗黙にせず明示することで、エージェントが間違いを犯す前に気づける。

このリポジトリへの AGENTS.md 追加手順

# リポジトリのルートに作成
touch AGENTS.md

# または既存の CLAUDE.md を AGENTS.md にリネームして
# 標準形式に沿って書き直す
cp CLAUDE.md AGENTS.md

# 変更をコミット
git add AGENTS.md
git commit -m "chore: add AGENTS.md for AI coding agent guidance"

既存のCLAUDE.mdやCOPILOT_INSTRUCTIONS.mdと共存させることも可能だ。エージェントは両方を読む。

注意点・未確認情報

**「35〜55%バグ減少」**の数字はコミュニティリーダーボードのデータに基づくもので、二重盲検試験ではない
エージェントがAGENTS.mdを完全に従うかどうかはエージェントの実装依存（無視されるケースも存在する）
AGENTS.mdとCLAUDE.mdが矛盾する記述を持つ場合の優先順位は各エージェントの実装に従う
Linux Foundation AAIFへの寄贈はDecember 2025だが、採用は2026年春に急増した

まとめ

AGENTS.mdは全主要AIコーディングエージェントが読むオープン標準のプロジェクト説明ファイル
ビルド・テスト・コーディング規約・禁止パターンを150行以内で記述する
採用リポジトリではエージェント生成バグが35〜55%少ないという実績がある
既存のCLAUDE.mdやCOPILOT_INSTRUCTIONS.mdを標準化するか、新規に作成することを推奨

S	公式ソース確認済み
A	成功実績多数・失敗例少数
B	賛否両論
C	動作未確認・セキュリティリスク高
Z	個人所感