agents-md

Agents.md

エージェントがプロジェクトの目指す姿、作者の考え方、作業中に繰り返し避けるべきミスを理解できるよう、簡潔なプロジェクト概要を一つ維持します。

プロセス

1. 対象範囲を定めます。 プロジェクトのルート、作成・監査・更新の意図、対象言語、対象となる実際のハーネスを特定します。適用される指示ファイルを読み、検出方法と優先順位を、ローカルでの動作または最新の公式ドキュメントに基づいて確認します。ルートの AGENTS.md を標準の正本として使用しますが、確立済みの移植可能なソースがある場合は維持します。ハーネス間でファイル名、階層、インポート、シンボリックリンクのサポートが共通しているとは想定しないでください。
2. 維持されている根拠を調べます。 README、製品ビジョン、用語集、ADR、コントリビューター向けガイド、設定、コード、既存の指示を必要な範囲だけ読み、権威ある情報源、矛盾、人間に尋ねなくても確認できる事実を見つけます。現在の実装から分かるのは存在するものです。プロジェクトが目指すべき姿が定まるわけではありません。
3. プロジェクトの指針を明確にします。 プロジェクトの目的、対象ユーザー、目指す方向、守るべき品質、重要な緊張関係、作者の判断基準やエージェントとの望ましい関係について、簡潔で合意済みの意味を得ます。権威ある維持管理対象のソース、またはユーザーがすでに示した意図を優先します。人間が決めるべき重要な不足が残る場合は、利用可能なら grilling を使い、その不足だけに限定します。そうでなければ、要点を絞った質問を必要最小限だけ直接尋ねます。指針がすでに十分明確な場合は、再度聞き取りを行いません。通常の範囲に絞った監査や更新に grilling を使わないでください。
4. 運用上のつまずきを特定します。 既存の合意済み指示、明示的な人間の判断、または実際に繰り返されたエージェントの失敗によって裏付けられる具体的な指針だけを残します。会話履歴やハーネスの履歴を調べるのは、ユーザーがその情報源と範囲を許可している場合に限ります。一度限りのミスや仮定上のリスクだけでは不十分です。
5. 適切な管理元を選びます。 プロジェクトの指針や運用ガイダンスは、作業中のエージェントの行動に影響させるべき場合に限り、ここに記載します。他の資料は変更せず、次の適切な場所に割り当てます。
   • 機械で検証できる動作は、実行可能な設定または CI に記載します。
   • レビュー担当者が判断するプロジェクトのルールは、正本となるコーディング規約に記載します。
   • 機能要件や実装状況は、一時的な作業成果物に記載します。
   • アーキテクチャ、ドメイン上の意味、長期的に有効な判断理由は、それぞれの維持管理対象の情報源に記載します。ただし、エージェントが参照すべき場合は、ここに短い条件付きの参照先を記載します。
6. 成果物や差分を最小限に提案します。 残す各記述がエージェントの行動をどう変えるか、なぜこのファイルが最適な管理元なのかを説明します。指針には簡潔で自然なプロジェクトレターを、運用上のつまずきには安全な代替手段を含む直接的な指示を優先します。古くなった記述、重複、一般論、推測、すでに強制されている指針は削除します。他の作者の文体を模倣したり、テンプレートを無理に適用したりしないでください。
7. 承認を得ます。 提案する内容全体または正確な差分、正本のパス、対象言語、対応するハーネス、移植性の限界を提示します。人間から明示的な承認を得てから書き込みます。修正が承認されたとみなされるのは、ドラフトへの影響が明確になった後だけです。
8. 書き込み、検証します。 無関係な指示を維持し、承認された変更だけを適用します。正本のソースを直接利用できない名前付きの対象ハーネスに限り、最小限のアダプター、インポート、リンクを作成します。生成されたすべてのファイルを読み直し、参照先を解決し、差分に矛盾する重複や無関係な変更がないことを確認します。

コンテンツフィルター

有用なコンテンツには、次のようなものがあります。

• プロジェクトが何を、誰のために、なぜ実現しようとしているのかについての簡潔な説明と、それが実装の選択にどう影響すべきか。
• 複数の解決策が妥当に見える場合に、エージェントが維持すべきプロダクトの特性やトレードオフ。
• 作成者が長期にわたって用いている判断基準と、コラボレーションへの期待。
• 発生条件と、具体的で安全な対処方法が示された、繰り返し起こる危険。
• 関連するほぼすべての作業で必要となる、複数の領域にまたがる責務や用語。
• 維持管理されている情報源と、それを読むべき状況の両方を示す、条件付きの参照先。

次のものは除外してください。

• リポジトリを調べれば把握できる、スクリプト、依存関係、フレームワーク、ディレクトリ、ファイルの一覧。
• パッケージ、ビルド、タスク、CI の設定からすでに確認できる開発コマンド。
• 実行可能なツールやコーディング規約が定めている、フォーマッター、リンター、型、テスト、レビューのルール。
• 機能仕様、実装の作業単位、現在の進捗、一時的な例外、網羅的なアーキテクチャの説明。
• 条件付きの参照先で十分な場合に、用語集や ADR の履歴を重複して記載すること。
• 一般的なエンジニアリングの助言、エージェントの能力の説明、このプロジェクトと無関係な個人的な好み、承認された権限のない指示。
• ユーザーが対象に含めていないハーネス用の互換ファイル。

結果

• No instructions needed：常に読み込むコンテキストとして必要な、長期的なプロジェクトの指針や運用上の差分がないため、ファイルは作成されません。
• No changes needed：既存の指示チェーンが最新かつ簡潔で、適切に管理され、指定されたハーネス間で利用可能です。
• Agree-ready：人間による承認を受けるための、完全な成果物または最小限の差分が用意されています。ファイルは変更されていません。
• Updated：承認された変更が書き込まれ、報告されたパスで検証されています。
• Inconclusive：意図、権限、所有者、ハーネスの検出に関する具体的な競合と、それを解消する条件を明示します。

完了基準

最終的な指示はすべて、実装からは判断できない、承認済みのプロジェクトの意図を伝えるか、実際に確認された運用上の問題の再発を防ぐものです。その意味、言語、パス、対象とするハーネスの範囲について人間の承認を得ており、より優先される所有者の内容を重複して記載していません。また、対象となる各ハーネスが、検証済みの検出経路を通じて、一貫した単一の正規指示セットを受け取ります。