AGENTS.mdで始める実践的エージェント設計ガイド

こんにちは、JS2IIUです。
本記事では、AGENTS.mdの目的と作り方、実装・運用で役立つテンプレートをわかりやすく解説します。実例とチェックリスト付きで実務ですぐ使えます。今回もよろしくお願いします。

はじめに

2025年8月20日にOpenAIがAGENTS.mdのサイトを公開しました。この公開によってAGENTS.mdの存在が広く知られるようになりました。

AGENTS.md

AGENTS.md is a simple, open format for guiding coding agents. Think of it as a README for agents.

agents.md

AGENTS.md は、リポジトリ内でコーディングエージェントが確実かつ安全に作業できるように、実行可能な手順や運用ルールをまとめるフォーマットです。具体的には、ビルド／テスト／実行コマンド、CI や PR の手順、コードスタイルやセキュリティ上の注意点、依存関係と権限制限などを明記します。これにより、エージェントと人間の双方が同じ手順で動けるようになり、再現性と自動化の安全性が高まります。

注: AGENTS.md は README を補完します。最寄りの AGENTS.md が優先して参照されるため、サブプロジェクトごとに設置することを推奨します。AGENTS.md に記載されたコマンドはエージェントが実行する可能性があるため、実行可能なコマンドと権限は慎重に記載してください。

AGENTS.mdが役立つシチュエーション

agents.md の主な目的は「リポジトリ内でコーディングエージェントが確実に動けるように、ビルド/テスト/実行コマンドやコーディング規約、PR手順などの運用情報を与える」ことです。

主なユースケース

• 開発ワークフローの自動化（PRのラベル付け・初期レビュー）
  • リポジトリ内の実行コマンド、テスト、PR手順、コードスタイルなどを明記することで、コーディングエージェントがPRの解析や自動ラベリング、テスト実行を安全に行えます。
  • 推奨する AGENTS.md の内容: ビルド/テストコマンド、PR タイトル・ラベル規約、静的解析の実行手順、エスカレーション（人間レビュー）条件。
• インシデント検知と初動対応支援（開発運用チーム向け自動化）
  • 監視・運用用リポジトリや運用プレイブックがある場合、実行手順や権限、ログ取得コマンドなどを AGENTS.md に明記すると、エージェントが期待どおりに補助作業を行えます。
  • 推奨する AGENTS.md の内容: 実行可能なコマンド、アクセス権限の制約、サンドボックス化の方針、ログ参照手順。
• 定期レポート生成と配信（開発/運用の自動集計）
  • レポート生成スクリプトの実行コマンドや依存関係、出力場所を AGENTS.md に記載すれば、エージェントが安全にレポートを作成・配信できます。

適用・拡張（agents.md の考え方を応用する実業務ユースケース）

以下は実務で有効なユースケースですが、agents.md の公式ページに直接の事例として列挙されているわけではありません。とはいえ、agents.md のフォーマット（手順や実行コマンド、権限、制約を書く）を応用すれば、これらの業務エージェントにも適用できます。

• カスタマーサポートの一次対応自動化
  • 注記: agents.md はあくまでリポジトリ／コード実行のためのドキュメントですが、サポート用エージェントをリポジトリ内で管理する場合、応答生成フローやエスカレーション基準、テスト手順を AGENTS.md にまとめることが有効です。
• ドキュメントからの情報抽出（契約書・請求書）
  • 注記: 文書処理パイプラインや検証スクリプトの実行手順、機密データの取り扱い方針を AGENTS.md に記載すれば、エージェントが安全に処理を実行できます。ただし個人情報の取扱いは別途コンプライアンス文書と組み合わせる必要があります。
• コンテンツモデレーションの前処理
  • 注記: モデレーションルールや閾値、誤検知時の人間対応フローを AGENTS.md に落とし込むことで、自動化の安全性を高められます。
• 法務・コンプライアンス向けの事前チェック
  • 注記: 規約チェックやスコアリング基準をドキュメント化する点は agents.md の趣旨に沿いますが、法務判断ルールは必ず人間審査と組み合わせてください。
• 社内ナレッジ検索＋サマリー提供
  • 注記: 検索インデックスの更新手順、データソースの場所、権限を AGENTS.md に記載することで、エージェントの動作が安定します。

各シチュエーションで重要なのは、agents.md の基本方針に従って「実行コマンド」「前提（依存）」「権限」「失敗時の挙動（エスカレーション基準）」を明記することです。業務系ユースケースについては、AGENTS.md 単体よりもプロジェクト固有の運用ドキュメント（例: Runbook、コンプライアンス方針）と組み合わせて運用することが推奨されています。

作成するメリット

• 期待する振る舞いの共有による実装ミスの削減
• セキュリティ・プライバシー要件の予めの定義
• テストケース/評価指標の明文化でCIに組み込みやすくなる
• 監査や説明責任（explainability）対応が容易になる

推奨フォーマット（テンプレート）

以下は実務で使える最小限のテンプレートです。リポジトリの docs/agents/ またはルートに AGENTS.md として置くことが推奨されています。

エージェント名（短い識別子）

1. 概要（Summary）

• 1行サマリ: エージェントが何をするか
• 目的・背景: ビジネス価値や自動化の意図

2. スコープ（Scope）

• 対象ケース: どのタスク／ドメインを扱うか
• 除外事項: 明示的に扱わない事柄（境界）

3. 利用者と権限（Actors & Permissions）

• インタラクションする主体（ユーザー、他サービス）
• 必要な API キーやアクセス権限と範囲

4. 入力 / 出力（Interface）

• 入力スキーマ（例: JSON スキーマ）と必須/任意項目
• 出力フォーマット（成功/エラー時）とサンプル

5. 振る舞いフロー（Behavior / Flow）

• 概要シーケンス（ステップ列挙、図があれば添付）
• 主要ロジック（例: retrieve → plan → act → observe の流れ）
• 再試行/タイムアウト/バックオフの方針

6. プロンプト & ポリシー（Prompts, Rules, Safety）

• 使用するプロンプトテンプレート（テンプレート例を掲載）
• 禁止事項（例: 個人情報の外部送信、断定的回答の禁止など）
• モニタリング対象（unsafe action の検知ルール）

7. 非機能要件（NFRs）

• レイテンシ目標、スループット、可用性目標
• コスト上限やリソース要件（GPU/メモリ）

8. セキュリティ & プライバシー

• データ保持方針、マスキング方針
• ログに記録する情報と保持期間
• アクセス制御・監査ポイント

9. テストと評価（Testing & Metrics）

• 受け入れ基準（成功条件）
• 推奨テストケース（ハッピーパス、境界値、攻撃的入力）
• KPI（例: 正答率、誤作動率、平均レイテンシ）

10. 運用手順（Runbook）

• デプロイ手順、ロールバック方法
• 監視・アラート閾値と対応フロー
• 緊急停止（kill switch）の条件と手順

11. 依存関係（Dependencies）

• 使用する LLM/モデル名とバージョン
• 外部 API、データベース、コネクタ

12. 参考資料（References）

• 関連論文、実装サンプル、仕様リンク

テンプレートのサマリ表

記入例

以下では、agents.md の主旨（人間が読んで実行できる手順が中心）に合わせて、簡潔な人間向け Markdown 例と、必要に応じて併記できる機械向け YAML マニフェストの両方を示します。AGENTS.md 自体は Markdown で問題ありません。YAML/JSON は機械で読み取りたい場合の「補助データ」として併記する形が推奨です。

Markdown（人間向け・実行手順を明示）

# knowledge-search-agent

## 概要: 社内ナレッジを検索して、回答候補を返すエージェント

## 適用スコープ:
- path: docs/knowledge/**
- scope: project-root (ルートAGENTS.md とマージ)

## コードスタイル:
- Format: black --line-length 88
- Lint: flake8

## テストと品質:
- CI テストコマンド: make test-agent (pytest tests/)
- カバレッジ閾値: 90%
- 失敗時: 自動リトライ 1 回、結果は human_review にエスカレート

## ビルド/実行:
- ローカル実行: ./scripts/run_agent.sh --query "..."
- Docker (開発): docker compose up --build
- 本番デプロイ: GitHub Actions workflow: release.yml

## 権限:
- 読み取り: docs/knowledge/*
- API キー: INTERNAL_SEARCH_KEY (read-only)

## PR/コミット規約:
- Commit: Conventional Commits (feat:, fix:, chore:)
- PR テンプレート: 変更概要・テスト結果・影響範囲必須

## メンテナンス:
- AGENTS.md 更新フロー: Issue → チームレビュー → CI反映 → 周知
- 定期レビュー: 6 か月ごと

## 実行コマンド（サンプル）:
- make test-agent
- ./scripts/run_agent.sh --query "請求書の期日を教えて"

## エスカレーション条件:
- 信頼度 < 0.6 または出力に個人情報が含まれる場合は human_review

# knowledge-search-agent

## 概要: 社内ナレッジを検索して、回答候補を返すエージェント

## 適用スコープ:
- path: docs/knowledge/**
- scope: project-root (ルートAGENTS.md とマージ)

## コードスタイル:
- Format: black --line-length 88
- Lint: flake8

## テストと品質:
- CI テストコマンド: make test-agent (pytest tests/)
- カバレッジ閾値: 90%
- 失敗時: 自動リトライ 1 回、結果は human_review にエスカレート

## ビルド/実行:
- ローカル実行: ./scripts/run_agent.sh --query "..."
- Docker (開発): docker compose up --build
- 本番デプロイ: GitHub Actions workflow: release.yml

## 権限:
- 読み取り: docs/knowledge/*
- API キー: INTERNAL_SEARCH_KEY (read-only)

## PR/コミット規約:
- Commit: Conventional Commits (feat:, fix:, chore:)
- PR テンプレート: 変更概要・テスト結果・影響範囲必須

## メンテナンス:
- AGENTS.md 更新フロー: Issue → チームレビュー → CI反映 → 周知
- 定期レビュー: 6 か月ごと

## 実行コマンド（サンプル）:
- make test-agent
- ./scripts/run_agent.sh --query "請求書の期日を教えて"

## エスカレーション条件:
- 信頼度 < 0.6 または出力に個人情報が含まれる場合は human_review

YAML（機械読み取り用・任意）

name: knowledge-search-agent
summary: "社内ナレッジを検索して、回答候補を返すエージェント"
scope:
  path: "docs/knowledge/**"
  merge_strategy: "hierarchical" # root/subdir merge
code_style:
  format: "black --line-length 88"
  lint: "flake8"
commands:
  run: "./scripts/run_agent.sh --query \"{query}\""
  test: "make test-agent"
  build: "docker compose up --build"
ci:
  workflow: ".github/workflows/release.yml"
  coverage_threshold: 0.90
permissions:
  - resource: "docs/knowledge/*"
    access: "read"
inputs:
  query:
    type: string
outputs:
  answer:
    type: string
  sources:
    type: array
    items: url
metrics:
  accuracy: 0.85
  latency_ms: 500
maintenance:
  update_flow: ["issue", "review", "ci", "announce"]
  review_interval_months: 6
escalation:
  confidence_threshold: 0.6
  action: "request_human_review"

name: knowledge-search-agent
summary: "社内ナレッジを検索して、回答候補を返すエージェント"
scope:
  path: "docs/knowledge/**"
  merge_strategy: "hierarchical" # root/subdir merge
code_style:
  format: "black --line-length 88"
  lint: "flake8"
commands:
  run: "./scripts/run_agent.sh --query \"{query}\""
  test: "make test-agent"
  build: "docker compose up --build"
ci:
  workflow: ".github/workflows/release.yml"
  coverage_threshold: 0.90
permissions:
  - resource: "docs/knowledge/*"
    access: "read"
inputs:
  query:
    type: string
outputs:
  answer:
    type: string
  sources:
    type: array
    items: url
metrics:
  accuracy: 0.85
  latency_ms: 500
maintenance:
  update_flow: ["issue", "review", "ci", "announce"]
  review_interval_months: 6
escalation:
  confidence_threshold: 0.6
  action: "request_human_review"

注: 上記は Codex 記事が推奨する「五つの柱（コードスタイル／テスト／ビルド／ドキュメント更新ポリシー／コミット・PR 規約）」や「階層的スコープ」「CI 連携」「メンテナンスフロー」を反映した例です。実運用ではさらに詳細（CI の環境変数名、テストサブセットの指定、pre-commit フック、権限の最小化ルールなど）を明記してください。

実装上の注意

• 小さなフィードバックループを作って評価（A/B テスト）し、誤動作を早期に検出してください。
• プロンプト変更やモデル差し替え時は必ず回帰テストを実施してください。
• エスカレーション基準（低信頼度、規約違反）を明確にしておいてください。

参考リンク

• AGENTS.md（参考）: https://agents.md/
• LangChain Agents: https://python.langchain.com/en/latest/modules/agents/
• Auto-GPT: https://github.com/Significant-Gravitas/Auto-GPT
• ReAct 論文: https://arxiv.org/abs/2210.03629

最後まで読んでいただきありがとうございます。
ご意見、ご感想、ご質問は是非コメント欄へお願いします。