review-agents-md

AGENTS.md スキル

概要

段階的開示の原則に従って、AGENTS.md ファイルを作成・リファクタリングします。ファイルを最小限に保ち、焦点を絞ることで、エージェントのパフォーマンスを損なう「泥団子」化を防ぎます。

使用するタイミング

• 積極的に：プロジェクトのルートに AGENTS.md がない場合 — 新しいプロジェクトで作業を始める際に確認します
• 新しい AGENTS.md を一から作成するとき
• 肥大化した AGENTS.md をリファクタリングするとき
• 既存ファイルをベストプラクティスに照らしてレビューするとき
• モノレポ用に AGENTS.md を設定するとき
• AGENTS.md は存在するが CLAUDE.md がない場合（シンボリックリンクを作成する必要があります）

基本原則

1. デフォルトでは最小限に：あらゆるタスクに関連する内容だけを含めます
2. 段階的開示：分野固有のルールは、別ファイル、外部ドキュメント、またはエージェントスキルを参照させます
3. ファイル構成は記述しない：すぐに古くなり、エージェントのコンテキストを損ないます
4. 場所ではなく機能を説明する：「認証には JWT を使用します」であり、「認証は src/auth/ にあります」ではありません

指示の予算

最先端の LLM は、約 150～200 件の指示に一貫して従えます。AGENTS.md のすべてのトークンは、関連性にかかわらずリクエストのたびに読み込まれます。理想的なファイルは、できるだけ小さくする必要があります。

ファイルが肥大化する理由

エージェントが何かを間違える → ルールを追加する → これを何百回も繰り返す → 「泥団子」化します。開発者ごとに意見が食い違うルールを追加することもあります。全体のスタイルを見直す人はいません。自動生成ファイルは、簡潔さより網羅性を優先するため、状況をさらに悪化させます。

古いドキュメントがコンテキストを損なう理由

人間は古くなったドキュメントを疑ってかかることができます。エージェントにはそれができません。リクエストのたびに読んだ内容を信頼します。ファイルパスは特に危険です。絶えず変化するためです。代わりに、機能や分野の概念を説明してください。

プロセス

フェーズ 0：ファイルの不足を検出する

プロジェクトのルートで AGENTS.md と CLAUDE.md を確認します。

1. どちらも存在しない場合は、AGENTS.md を作成し、CLAUDE.md からシンボリックリンクを作成することを提案します
2. AGENTS.md は存在するが CLAUDE.md がない場合は、シンボリックリンクを作成します：ln -s AGENTS.md CLAUDE.md
3. CLAUDE.md は存在するが AGENTS.md がない場合は、AGENTS.md に名前を変更し、シンボリックリンクを作成します：mv CLAUDE.md AGENTS.md && ln -s AGENTS.md CLAUDE.md
4. 両方が存在するが、CLAUDE.md が AGENTS.md へのシンボリックリンクではない場合は、独自の内容を AGENTS.md に統合し、独立した CLAUDE.md を削除して、シンボリックリンクを作成します

フェーズ 1：現状を評価する

新規プロジェクトの場合：

• プロジェクトの目的を尋ねます（一文で）
• パッケージマネージャーを尋ねます（npm 以外の場合）
• 標準外のビルドコマンドを尋ねます

既存ファイルの場合：

• 現在の AGENTS.md を読みます
• 行数を数え、トークンコストを見積もります
• 別の場所に置くべき内容を特定します

フェーズ 2：必須項目のテストを適用する

ルートの AGENTS.md に含めるのは、次の内容だけです。

含める内容	理由
プロジェクトの説明（1 文）	エージェントのすべての判断の基盤になります
パッケージマネージャー（npm 以外の場合）	誤ったコマンドを防ぎます
標準外のビルド／テストコマンド	試行錯誤を減らします
分野固有のドキュメントへのリンク	段階的開示を実現します

それ以外はすべて別ファイルに移すか、削除します。

フェーズ 3：アンチパターンを特定する

次の項目は、削除または移動するものとして指摘します。

• ファイルツリー構造：常に古くなり、トークンを浪費します
• 自明な指示：「きれいなコードを書く」「意味のある名前を使う」
• 矛盾するルール：複数の貢献者によって生じることがよくあります
• 言語固有の規約：docs/TYPESCRIPT.md などに移します
• ワークフローの指示：docs/GIT.md または docs/TESTING.md に移します

フェーズ 4：段階的開示の構成を作成する

削除すべきでない内容については、次のようにします。

docs/
├── TYPESCRIPT.md    # TS conventions
├── TESTING.md       # Test patterns
├── API.md           # API design rules
└── GIT.md           # Commit/PR conventions

AGENTS.md から簡潔なポインターで参照します。会話的なトーンを保ち、「必ず」や大文字だけの強制的な表現は避けてください。

For TypeScript conventions, see docs/TYPESCRIPT.md

各ファイルから次のファイルを参照できます。エージェントは必要に応じてツリーをたどり、関連する内容だけを読み込みます。

外部ドキュメントが正式な情報源である場合は、内容を繰り返さず、外部ドキュメントにリンクしてください。

For database migrations, follow the Prisma migration guide.

エージェントスキルも、段階的開示のもう一つの層です。手順を AGENTS.md に埋め込む代わりに、必要なときにエージェントが取り込むスキルとしてパッケージ化します。ルートファイルでは 何を、どこで 行うかに集中し、スキルでは どのように 行うかを扱います。

フェーズ 5：モノレポに対応する

モノレポでは、ネストした AGENTS.md ファイルを使用します。

ルートの AGENTS.md：

Monorepo for [purpose]. Uses [pnpm/yarn] workspaces.
See each package's AGENTS.md for specifics.

パッケージの AGENTS.md（例：packages/api/AGENTS.md）：

GraphQL API using Prisma. See docs/API_CONVENTIONS.md for patterns.

フェーズ 6：出力

次の内容を提示します。

1. 新規作成またはリファクタリングした AGENTS.md の内容
2. 段階的開示のために作成した新しいファイル
3. 削除した内容とその理由の一覧

出力形式

新しい AGENTS.md を作成する場合：

# [Project Name]

[One-sentence description of what this project does.]

[Package manager if not npm]

[Non-standard commands if any]

[Light-touch pointers to separate docs if needed]

例：最小限の AGENTS.md

# Acme Dashboard

React admin dashboard for managing customer accounts and billing.

Uses pnpm. Run `pnpm check` for type checking.

For API conventions, see docs/API.md
For component patterns, see docs/COMPONENTS.md

わずか 6 行です。すべてのトークンに意味があります。

リファクタリングのプロンプト

肥大化した既存のファイルをリファクタリングする場合は、次の手順に従います。

1. 矛盾を見つける：競合する指示を特定します。どれを残すか確認します。
2. 必須事項を特定する：ルートに含めるべきものだけを抽出します。プロジェクトの説明、パッケージマネージャー、標準外のコマンド、すべてのタスクに関係する内容です。
3. 残りを分類する：論理的なカテゴリに整理し、個別のファイルを作成します。
4. 構成を作成する：個別のファイルへのリンクを含む、最小限のルート AGENTS.md を出力します。
5. 削除対象に印を付ける：重複している、曖昧な、または自明な指示を特定します。

判断基準

AGENTS.md に何かを追加する前に、次の基準を確認します。

場所	使用する場合
ルートの AGENTS.md	あらゆるタスクに関係する
個別のファイル	1 つの領域に関係する
ネストしたドキュメント	階層的な構成に適している
削除する	自明、重複、または曖昧である

ツール間の互換性

AGENTS.md は、次のような 20 以上のツールがサポートするオープンスタンダードです。

• GitHub Copilot（コーディングエージェント）
• Cursor
• Codex（OpenAI）
• Gemini CLI（Google）
• Windsurf、Devin（Cognition）
• Zed、Warp、VS Code
• Aider、goose、RooCode

Claude Code では代わりに CLAUDE.md を使用します。常に AGENTS.md を信頼できる唯一の情報源とします。CLAUDE.md は必ず AGENTS.md を指すシンボリックリンクにします。

ln -s AGENTS.md CLAUDE.md

単独の CLAUDE.md は作成しないでください。AGENTS.md にない内容を CLAUDE.md に記載しないでください。

リソース

• https://agents.md — AGENTS.md の仕様
• https://www.aihero.dev/a-complete-guide-to-agents-md — このスキルのベストプラクティスの参考にしたガイド