AGENTS.md 詳解

AGENTS.mdの仕様フォーマット、ツール別の実装方式、作成原則、検証手順を整理する。第5章で概念的に紹介したAGENTS.mdを実務の観点から詳しく掘り下げる。

標準仕様: agents.md · 実習例: 第4章 §2-A / 第4章 §2-B

仕様フォーマット

AGENTS.mdの各エージェント項目は、## Agent: {名前}で始まるMarkdownセクションである。このセクション内に役割・入力・出力・権限・handoffなどのフィールドを自由形式で記述する。標準仕様は厳密なスキーマを強制せず、ツールが共通して認識する慣例(convention)に依存する。

完成例

第4章の実習(G-1、D-1)で作成した2つのエージェントを含むAGENTS.md全体の姿である。

## Agent: reviewer

役割: テキストファイルの誤字脱字、論理的な欠陥、改善点をレビューする。
入力: レビュー対象のテキストファイルパス
出力: 誤字脱字・論理的欠陥・改善点のリスト
権限: 読み取り専用 — ファイルを直接修正しない。

## Agent: writer

役割: 与えられたテーマで3〜5文程度の短い草稿を作成する。
入力: テーマ、保存先のファイルパス
出力: 草稿テキストファイル
権限: 書き込み許可 — 指定されたファイルにのみ保存する。
handoff_to: reviewer(草稿完成後にレビューへ引き継ぐ)

ツール別実装マッピング

AGENTS.mdはツール中立な共通仕様である。しかし、実際にサブエージェントを「実装」する方式は、Claude系とAntigravity系で根本的に異なる。

作成ガイド

1. セクションから始める

## Agent: {名前}でエージェント項目を開始する。名前は英語の小文字とし、複数の単語は-で連結する(code-reviewer、api-tester)。この名前はClaude系ではsubagent_typeの値として使用される。

2. 役割を簡潔に

役割は「何をするか」を1〜2文で明確に記述する。他のエージェントとの重複を避け、各エージェントが独立して責任を持つ領域が明確になるようにする。

3. 最小権限で権限を設定する

権限フィールドはファイルアクセスの範囲を制限する。この原則を守らないと、サブエージェントが誤って重要なファイルを上書きしてしまう可能性がある。Claude系では、この権限は.claude/agents/*.mdのtoolsフィールド(Read, Grep、Writeなど)に変換される。

4. handoffで前後関係を宣言する

handoff_toは「このエージェントが作業を終えたら結果をどこに引き渡すか」を宣言する。これは命令ではなくヒントである。実際に順次パイプラインを構成するのは、メインセッション(オーケストレーター)の役目である。

## Agent: draft-writer
役割: 与えられたテーマで草稿を作成する。
handoff_to: reviewer(草稿完成後にレビューへ引き継ぐ)

## Agent: reviewer
役割: テキストの誤字脱字と論理をレビューする。
handoff_to: editor(レビュー完了後に最終編集へ引き継ぐ)

## Agent: editor
役割: フィードバックを反映して最終文書を完成させる。

5. 検証

作成が完了したら、bun run agent:verifyで構造を検証する。このスクリプトは、エージェントfrontmatterの完全性、必須セクションの存在、AGENTS.mdロスターとの整合性を確認する。

検証とライフサイクル

AGENTS.mdにエージェントを登録することは、ライフサイクルのCreate段階に該当する(第8章§2参照)。登録されたエージェントは以下の段階を経る。

エージェントを新規作成または変更するたびにagent:verifyを実行することを習慣化すれば、「ロスターにはあるが実際の定義ファイルが存在しない」や「handoff_toが指すエージェントが削除されている」といった不整合を早期に発見できる。

この検証フローの自動化は、第8章§1(デプロイとSSOT)で扱うCI/CDパイプラインにvalidate-templates.tsのステップとして統合できる。