bootstrap-agents-md

AGENTS.md を初期作成する

有能なコーディングエージェントが自力では確実に推測できないプロジェクト知識を伝える、最小限のルート指示セットを作成します。厳密な契約は正確に保ち、リポジトリ内の現状の根拠から判断できる実装や提示方法の選択肢は残しておきます。

出力契約

ユーザーからより広範な指示階層を求められていない限り、リポジトリのルートに次のファイルを作成します。

• AGENTS.md：永続コンテキストに記載する価値のある、重要度の高いリポジトリの事実、境界、検証要件。
• CLAUDE.md：@AGENTS.md の後に改行を1つだけ付けた内容。

既存のルート指示ファイルを置き換える場合は、既存の文言に追記するのではなく、一貫性のある新しいファイルを書きます。古いファイルの構成ではなく、根拠のある意図を維持します。

リテラルな形式がエージェントの動作を変え、リポジトリの根拠から安定していると判断できる場合は、正確なコマンド、リポジトリ相対パス、ツールや依存関係の名前、バージョン、URL を AGENTS.md に記載してもかまいません。シークレット、マシン固有の絶対パス、過去のセッション履歴のコピー、変動する一覧、または有能なエージェントがリポジトリから容易に確認できる詳細は除外します。

1. 範囲とベースラインを確定する

1. ワークスペースの根拠からリポジトリのルートを特定します。
2. 作業ツリーの状態を記録し、無関係な変更を保持します。
3. 既存のルート AGENTS.md と CLAUDE.md を根拠として読みます。維持、変更、削除すべき重要な意図を記録します。
4. ネストされた指示ファイルを探し、それぞれの限定された適用範囲を尊重します。ユーザーが指定した場合に限り、変更します。

複数のルートや指示の所有者が競合し、結果に重大な違いが生じる場合に限り、確認を求めます。

完了条件： 対象のルート、変更を許可されたファイル、既存の重要な意図、ネストされた指示の優先関係、無関係な作業について、推測せずに記述できるだけの理解が得られていること。

2. プロジェクトを必要な範囲だけ調査する

プロジェクトの目的、長期にわたって維持されるアーキテクチャやドメイン用語、公開境界、テスト、設定済みチェック、リリースや移行のリスク、外部への影響、繰り返し現れるローカル規約など、ルート指示のうち自明でない内容を明らかにする根拠を調べます。生成物、ベンダー提供物、キャッシュ、バイナリ、シークレットを含む可能性のある領域は、中身を不必要に読み込まずに分類します。

リポジトリとタスクに応じて調査の範囲を調整します。単独の例よりも、繰り返し使われているコード、テスト、自動化、保守されている設計記録を優先します。記載するルールに影響する矛盾は解消し、永続コンテキストに含める必要のない不確かな主張は省きます。

目的は最終的な指示を書くのに十分な根拠を得ることであり、すべてのファイルを網羅したり、作成作業の記録を恒久的に残したりすることではありません。

完了条件： 提案するプロジェクト固有のルールすべてに根拠があり、これ以上調査してもルート指示が大きく変わる可能性が低いこと。

3. 永続的なコンテキストに値する内容を判断する

プロジェクト全体に適用され、自明ではなく、動作に影響し、根拠があり、常に読み込まれる注意事項として正当化できるだけの持続性があるルールを残します。ユーザーが明示的に求めている場合や、能力の高いモデルにも追加の指針が必要だと示す失敗が観察された場合も、そのルールを含める価値があります。

影響の大きさに応じて具体性を調整します。

指針	扱い
厳格な契約	正確性、安全性、互換性、またはハーネスが求める場合は、構文、適用範囲、禁止事項を正確に示します。失敗時の損失が大きい場合のガードレールには、安全な対応も併記します。
プロジェクト固有のヒューリスティック	プロジェクト固有の理由と望ましい結果を説明します。エージェントが現在得られる根拠に基づいて手段を選べるようにします。
判断の余地がある選択	リポジトリやユーザーによる制約がない限り、見出し、順序、実装設計、テストの形、抽象化、ドキュメントの分量はエージェントに委ねます。

最小限のルールから始めます。正確な形式が重要な場合や、明確な文章でも実証された曖昧さが残る場合に限り、例を追加します。一般的な表現やレイアウトの例が、意図せずテンプレートになることがあります。

能力のあるエージェントなら理解できる一般的な助言、緊急性の繰り返し、ツールで既に適用されているスタイル上の好み、一時的な手順、推測に基づくアーキテクチャ、重複するソース資料は除外します。リポジトリで機械的に保証できる内容は、自動化に移します。

サブシステム、依存関係、ワークフローが存在しないことは、プロジェクトの根拠またはユーザーが意図的に境界を定めていない限り、恒久的な禁止事項ではなく現状として扱います。

**完了条件：**残した指示にはすべて重要な理由があり、省いた選択肢はすべてリポジトリから把握できるか、エージェントの判断に意図的に委ねられています。

4. テンプレートではなく、プロジェクトに合わせて草案を作成する

このリポジトリで最も使いやすい指針となる構成を選びます。小規模なプロジェクトなら、少数のルールだけで十分な場合があります。複雑なサービスでは、ドメインの不変条件、運用上のリスク、検証、指示の優先順位を個別に扱う価値がある場合があります。セクション名、順序、数は成果物の選択事項であり、リリース要件ではありません。

曖昧な標語と、融通の利かない実装手順の中間の粒度で記述します。プロジェクトの事実、その重要性、維持すべき結果を明示します。抽象化によって指示が実行しにくくなる場合は具体的に記述し、詳細がルートコンテキストには変動しやすい場合は、より限定的な情報源を示します。

**完了条件：**草案が簡潔で、プロジェクトに即しており、内部で一貫し、根拠のない決定を未確定のまま残しています。

5. ペアを作成して検証する

1. ユーザーが許可した既存ファイルの置き換え、または新規ファイルとして、ルートのAGENTS.mdを作成します。
2. CLAUDE.mdを、末尾に改行を付けた正確なインポート行として作成します。
3. 両方のファイルを読み直し、無関係な変更がないか差分を確認します。
4. Pythonを利用できる場合は、scripts/validate_agents_md.pyを実行します。構造チェックとレビュー時のシグナルは補助として扱い、意味上の品質を証明するものとは見なしません。
5. 残した各主張をリポジトリ内の根拠と照合し、ネストされた指針との矛盾を確認し、能力のあるモデルなら既定で理解できる内容を言い換えただけの項目は削除します。

一貫性を保って両ファイルを作成できない場合は、部分的な状態を報告し、安全であれば一貫性を回復します。検証ツールだけを根拠に、意味上の検査に合格したと主張しないでください。

**完了条件：**両方のファイルが一貫したペアとなり、構造検証に合格し、意味上の監査で根拠のないルートルールや矛盾するルートルールが見つかっていません。

6. 重要な判断を報告する

確認した根拠の所在、残した重要な事実、変更したファイル、実施した検証、未解決の不確実性やリスクを要約します。以前の指示がある場合は、重要な項目群について、維持、再構成、削除、またはより限定的な管理範囲への移動のいずれかを説明し、その理由も示します。

網羅的な行単位の置き換え記録は、ユーザーから求められた場合、または以前の指示が安全上重要であるか、争点となっているか、項目群ごとの監査には複雑すぎる場合に限り作成します。

メンテナンスの参考情報

このスキルをメンテナンスするとき、CLAUDE.md のインポート規約を再確認するとき、またはコンテキスト設計の根拠を見直すときは、references/source-notes.md を参照してください。生成されるプロジェクト向けの指示に、調査の経緯を含めないでください。

ハーネスの規約が機能しない場合や、ガイダンスがプロジェクトの証拠と矛盾する場合は、インストールされているハーネスと、関連する最新の公式ドキュメントまたは信頼できる一次情報を確認してください。そのような証拠を入手できない場合は、不明であることを明記してください。かつて検証済みだったという理由だけで、古い表現を残さないでください。

ルールが有用なガイダンスをもはや加えない場合は、該当する記述、出典・バージョンまたは反例、意図が維持されていることを確認するチェックを添えて、標準スキルの修正または削除を提案してください。インストール済みのコピーを黙って編集したり、変更を公開したりしないでください。生成されるプロジェクト向けのガイダンスでは、新たな調査手順を追加する代わりに、実際の信頼できる情報源を示すことができます。