AGENTS.md ナビゲーションガイド記述標準調査 | BizLinkPartners 社内ドキュメント

調査日: 2026-05-15 調査者: [email protected] (Claude Sonnet 4.6 調査) 目的: ADR-0041 遡及リサーチ。Anthropic 公式 CLAUDE.md ガイドライン・OSS AGENTS.md ベストプラクティスとの整合性検証 調査モデル: Claude Sonnet 4.6（Gemini/GPT 追加調査は別途）

1. サマリー（結論・採用判断）

現行 AGENTS.md の基本構造（ディレクトリマップ・検索方法・作成ルール・ナビゲーション例）はベストプラクティスと整合している。採用継続。ただし3要素を追加する。

追加必須:

三層境界ルール（always/ask first/never）の明示 — OSS 2,500+ リポジトリ分析で「最重要要素」と特定
エスカレーションパス — 「見つからない場合の次の行動」が現行では未定義
コマンド例を冒頭付近に移動 — 現行は後方配置。AI エージェントは前半を優先参照

2. 調査内容

2.1 Anthropic 公式 CLAUDE.md / AGENTS.md ガイドライン

公式推奨の必須記載事項:

必須	現 AGENTS.md の対応
Claude が推測できないコマンド	✓（bash コマンド例あり）
デフォルトと異なるコードスタイル	✓（frontmatter 必須ルール）
破壊的操作の禁止明示	△（禁止ディレクトリのみ）
アーキテクチャ上の意思決定	△（ADR へのリンクのみ）
非自明な罠・アンチパターン	未記載

「この一行を削除すると Claude がミスをするか？」テストを通過しない行は削除が推奨。300行以下が推奨上限（本プロジェクトは 200行制限で整合）。

@path/to/file インポート構文で詳細を委譲する「Progressive Disclosure」が推奨 → 現行の参照リンク方式と整合。

2.2 OSS AGENTS.md ベストプラクティス（2,500+ リポジトリ分析）

GitHub Blog 分析による優秀な AGENTS.md の構成要素:

要素	重要度	現 AGENTS.md の対応
実行可能コマンド（冒頭配置）	最高	△（後方配置）
三層境界ルール（always/ask/never）	高	未記載
ディレクトリマップ（バージョン入り）	高	✓
実コードスニペット	高	✓（bash 例あり）
エスカレーションパス	高	未記載
アンチパターン（よくある誤探索）	中	未記載
frontmatter（name/description）	中	△（id/type のみ）

2.3 AI エージェント向けコンテキスト最適化

LLM が安定的に従える命令数は 150〜200 件が上限
全トークンが全リクエストでロードされるため肥大化は思考容量を圧迫
「能力と探索ヒント」を記述 → 構造より目的別の探索ガイドが保守性高い
実例 1 つ > 抽象的説明 3 段落（認知負荷低減・理解精度向上）

200行制限への対応方針: ルートの AGENTS.md は「入口のみ」、詳細はリンク先サブドキュメントへ。

2.4 AGENTS.md vs README の差別化

README	AGENTS.md
人間向け概要説明	エージェントの動作パラメータ設定
Why（プロジェクトの目的）	How（探索手順・コマンド・境界）
読み物として設計	実行可能スニペット優先
低更新頻度	最新ファイル構造に追随必須

3. 参照元

Best practices for Claude Code — Anthropic — 2026-05 参照
How to write a great agents.md — GitHub Blog — 2026-05 参照
A Complete Guide To AGENTS.md — AI Hero — 2026-05 参照
AGENTS.md Best Practices — agentsmd.io — 2026-05 参照

4. プロジェクトへの示唆

現行 AGENTS.md への最小変更で最大効果が得られる3点:

1. 三層境界ルールセクションを追加（最重要）:

## 境界ルール

| 区分 | 内容 |
|---|---|
| **Always** | frontmatter 付与 / `_meta/templates/<type>.md` 確認 / 関連ファイルの読み取り |
| **Ask first** | 既存ファイルの大幅改訂 / 新ディレクトリ作成 / _config.json 変更 |
| **Never** | `docs/dev/` `docs/arch/` `docs/spec/` への新規作成 / frontmatter なしでコミット |

2. エスカレーションパスを追加:

## 見つからない場合

1. `grep -r "<キーワード>" docs/` で全文検索
2. `docs/_config.json` の nav セクションで登録状況確認
3. `_nav/traceability.md` で legacy_id を確認
4. `implementation/legacy-dev/` に旧仕様書がある可能性

3. ナビゲーション例セクションを冒頭付近に移動（コマンド例を早期配置）。200行制限内での再配置のみ。コンテンツの追加なし。