agents-md

AGENTS.md の管理

AGENTS.md は、コーディングエージェントに適用範囲が明確で、最新のリポジトリ固有の指示を提供します。README、手順書、アーキテクチャ文書、変更履歴、チュートリアル、証拠ログではありません。優れたガイダンスは、証拠に基づき、簡潔で、そのファイルのディレクトリツリーに適用範囲が限定され、行動を促すものです。つまり、このリポジトリでエージェントがどう振る舞うべきかを伝えます。

使用する場合

• リポジトリの AGENTS.md を作成、更新、レビュー、分割、移動、または修正する場合。
• 検証済みのローカルコマンド、リポジトリの契約、パスの所有権、またはエージェントが繰り返し犯すミスを記録する場合。
• リポジトリの証拠を、今後のエージェントが従えるルールに変換する場合。

使用しない場合

• 単独のスキル、プロンプト、グローバル指示、README、アーキテクチャ文書、変更履歴、または手順書。
• AGENTS.md が明示的な成果物ではない、広範なドキュメントの書き直し。
• 現在のリポジトリの証拠に裏付けられていない、理想論的なプロセスガイダンス。

モード

• patch：小規模なテキスト修正、誤字、古くなったパス、または限定的なルール変更。該当箇所と証拠のみを調べます。
• create：適切な AGENTS.md が存在しない場合。アナライザーを実行し、ソース、設定、ドキュメントをサンプリングしてから、必要最小限のファイルを作成します。
• update：既存ファイルに新しいガイダンスの追加または修正が必要な場合。有効なルールを維持し、古くなった内容や重複した内容を削除し、証拠に裏付けられた変更のみを追加します。
• split/move：適用範囲の境界が変わる場合。既存のルートファイルとネストしたファイルを調べてから、references/topology-and-handoff-guidance.md を使用します。
• review：依頼がない限り編集しません。重要度別に、証拠と残存リスクを示して指摘事項を返します。
• exhaustive：モノレポ、契約が多いリポジトリ、安全性に関わるガイダンス、運用引き継ぎ、大規模なトポロジー変更、または証拠が不明確な場合。

ワークフロー

1. モードと対象範囲を選びます。最も近い既存の AGENTS.md、適用範囲が重なる可能性のあるネストした AGENTS.md ファイル、利用可能な場合は git status --short を確認します。
2. create、update、split/move、または exhaustive モードでは、python <skill-root>/scripts/analyze_project.py --repo-root <target-repo> --format json を実行します。これはサンプリングの手引きとして扱い、権威ある情報源とはみなしません。
3. 通常の作成手順の詳細については、references/normal-authoring.md を参照します。記載する主張に必要なソースのみを調べます。
4. references/template-selection.md にある、適用可能な最小のテンプレートを使って草案を作成します。リポジトリに明らかに専用テンプレートが必要な場合を除き、assets/agentsmd-minimal.md を優先します。
5. 証拠は作業メモまたは最終サマリーに記録します。リポジトリに既存の証拠ファイルがある場合、またはユーザーから依頼された場合に限り、証拠ファイルを追加します。
6. python <skill-root>/scripts/validate_agentsmd.py --repo-root <target-repo> --agents-file <target-agents-file> --mode <quick|standard|exhaustive> と python <skill-root>/scripts/semantic_check_agentsmd.py --repo-root <target-repo> --agents-file <target-agents-file> で検証します。

ルールの品質基準

次の条件を満たす場合に限り、ルールを残します。

• 具体的：実際のパス、コマンド、契約、またはローカルの規約を明示している。
• 最新：現在のファイルまたはユーザーが提供した最新の事実に裏付けられている。
• 適用範囲が明確：この AGENTS.md のディレクトリツリーに適用される。
• 行動を促す：エージェントの行動を変える。
• 証拠に裏付けられている：調査したリポジトリの証拠をたどって確認できる。
• 安全：秘密情報、不正なアクセス、破壊的なコマンド、本番環境での実行を避けている。
• 重複しない：グローバル指示、言語の基礎、README の内容を繰り返していない。
• 簡潔：通常のコーディング作業中にすばやく確認できる長さである。

エスカレーションマトリクス

タスクで必要な場合にのみ、追加のリファレンスを読み込みます。

トリガー	読むファイル
ツール、CLI、MCP、API、生成ファイル、移行、スキーマ、または公開コントラクトに関するガイダンス	references/contract-bearing-agentsmd.md
分割、移動、ネストされたスコープ、古くなったトポロジー、または所有権の引き継ぎ	references/topology-and-handoff-guidance.md
ライブ運用、ツールの機能低下、手動ディスパッチ、停止状態、または環境のリセット	references/degraded-tool-surface.md、references/evidence-invalidation.md
サブエージェントまたは委任されたレビューワークフロー	references/subagent-coordination-patterns.md
Python、TypeScript、その他のスタック、Databricks/Spark、またはML固有のエビデンスプロンプト	references/language-specific/python-guidance.md、references/language-specific/typescript-guidance.md、references/language-specific/other-stack-guidance.md、references/domain-specific/databricks-spark.md、references/domain-specific/ml-projects.md
レビューのみ、または判断を多く要する監査	references/manual-audit.md

最終回答

編集モードでは、変更したファイル、追加・変更・削除したルール、確認したエビデンスの出所、検証コマンドと結果、残存リスクを含めます。

レビューモードでは、重要度の高い順に指摘事項を先に示します。各指摘事項には、該当するAGENTS.mdのセクションまたは行、裏付けとなるリポジトリのエビデンス、重要である理由、推奨する修正を記載します。その後、未解決の質問、テスト／検証の不足点を列挙し、指摘事項を示した後にのみ簡潔な概要を記載します。

決定論的ツール

ツール	用途
scripts/analyze_project.py	スタック、設定、テスト、パス、提案の一覧
scripts/validate_agentsmd.py	構造の検証
scripts/semantic_check_agentsmd.py	パス、コマンド、リンク、例の検証
scripts/check_agentsmd_templates.py	スキルテンプレートとガイダンスの品質確認
scripts/run_agentsmd_fixture_checks.py	バリデーター変更に対する既知のフィクスチャ動作

リファレンス

• references/tool-contracts.mdとreferences/template-selection.md - ヘルパーCLIのコントラクト、モード、テンプレート
• assets/agentsmd-minimal.md、assets/agentsmd-contract-bearing.md、assets/agentsmd-operational.md、assets/agentsmd-full.md - スターターテンプレート
• assets/example-validated-agentsmd.md、assets/example-contract-bearing-agentsmd.md、assets/example-operational-agentsmd.md、assets/writing-tips.md - 簡潔な例