write-agents-md

AGENTS.md の作成

このファイルを自動的に受け取るエージェント向けに、小さく、長く使える指示ファイルを作成します。このスキルはガイダンスを作成するものであり、アプリケーションの実装や QA は行いません。

採用基準

AGENTS.md に記載するのは、次の 3 つの条件をすべて満たす内容に限ります。

1. 対象者： このディレクトリに入るすべてのエージェントが、タスクにかかわらず知っておく必要があること。ルート階層ならリポジトリ全体、ネストされた階層ならその配下全体が対象です。
2. 価値： エージェントが誤った判断をする可能性を減らすこと。一般的なツールの知識、明白な構成、マニフェストやソースからすぐに確認できる内容は含めません。
3. 安定性： 継続的な慣例または不変条件であり、その場限りの観察、変動するバージョン、タスクの進捗、一時的な回避策、マシン固有の事実ではないこと。

対象者の条件を満たさない内容は、タスク固有のスキルに記載します。詳細な説明や根拠はドキュメントに、実行状況はプロジェクトのトラッカーに記録します。安定したドキュメントの入口は AGENTS.md に残せますが、タスクごとのドキュメントやスキルの一覧は記載しません。許可なくスキル名を作ったり、スキルを追加したりしないでください。

TDD、7 段階の手動 QA 手順、新しいエンドポイントのキャプチャ、検証、コミットポリシー、誠実な完了報告は、すべての貢献者に適用される継続的な義務です。これらは、シナリオ別の手順書にせずに、ランタイム作業とドキュメント作業を区別するものです。これらの品質ゲートは AGENTS.md に記載し、コマンド、フィクスチャの手順、個別のフロー、復旧手順はスキルに記載してください。

該当するワークフローを選択する

• Web： Web ワークフローを読み、Web テンプレートをコピーします。
• デスクトップ： デスクトップワークフローを読み、デスクトップテンプレートをコピーします。

この 2 つが標準テンプレートです。ユーザーの TDD とコミットに関する文言は維持し、プロジェクト、クライアント、ブランドの詳細、技術、自然言語の選択肢は一般化されています。プロジェクトに両方のサーフェスがある場合を除き、もう一方のワークフローは読み込まないでください。複合型プロジェクトでは、共通のルート指示を最小限にし、異なる継続的な規則がある場合に限り、サーフェス固有のガイダンスをネストして配置します。CLI やライブラリのみのプロジェクトを、グラフィカルアプリのワークフローに無理に当てはめず、その境界を明確にしてください。

まずコピーし、その後に適応する

1. 既存の指示、ユーザー要件、ドキュメントのエントリーポイント、および明白でない制約を確認するために必要なメタデータのみを調べます。人間による判断を維持します。指示を書くためだけに、ソース全体の監査を求めないでください。
2. Web／デスクトップと、ルート／ネストされたスコープを選びます。適応を始める前に、選んだファイルをバイト単位でそのままコピーしてください。開始ファイルを記憶から再構成したり、言い換えたり、書き起こしたりしないでください。
3. バンドルされたヘルパーを使用します（Python 3.9 以降、標準ライブラリのみ）。

   python <skill-directory>/scripts/copy_template.py --workflow web --project-root <project-root> --candidate
   python <skill-directory>/scripts/copy_template.py --workflow desktop --project-root <project-root> --scope <existing-relative-subfolder> --candidate
   

   このヘルパーは常に AGENTS.md.candidate をステージングし、上書きおよびプロジェクト外の対象を拒否し、バイト列を検証して SHA-256 の受領情報を出力します。明示的な --candidate フラグは互換性のために維持されていますが、省略しても同様に安全です。受領情報は実行の証拠であり、AGENTS.md に記載するテキストではありません。
4. 新規・既存を問わず、ルート／ネストされたファイルには必ず --candidate を使用してください。 有効なガイダンスが存在しないか、変更されない状態を保ちながら、AGENTS.md.candidate を適応します。差分を確認し、プレースホルダーが残っていないことを検証した後、新しいガイダンスは上書きを拒否するファイルシステム操作で公開するか、既存のガイダンスは人間による指示を保持したレビュー済みの編集で調整します。適応が中断された場合、残るのは候補ファイルのみです。その旨を報告し、読み込んだり公開したりしないでください。公開に成功したら候補ファイルを削除してください。候補ファイルや受領情報をコミットしないでください。
5. ヘルパーを実行できない場合は、利用可能なファイルシステムのコピー機能を使い、編集前にバイト列／ハッシュを比較します。テンプレートを読み取る／コピーすることができない場合は、阻害要因を報告してください。近似物を作成しないでください。
6. ワークフローと採用ルールを適用します。検証済みのプレースホルダーは埋めます。任意のブロックは、事実を捏造するのではなく削除します。項目とネストに関するルールについては、スコープと適応を読んでください。
7. 最終差分をテンプレートおよび既存のガイダンスと比較します。スコープ、維持された必須の品質ゲート、Markdown／リンク、未解決のプレースホルダーがないこと、祖先の指示が重複していないことを確認します。重要な削除や移動について説明します。

譲れないテスト方針

7 つの TDD ステップ、7 つの手動 QA ステップ、テスト層の定義を維持してください。E2E と手動 QA では、実際の LLM 呼び出し、関連サービス、永続化された結果を含め、モックを一切使わず完全に動作するアプリケーションを使用します。 ユニットテスト／統合テストでは、有用な場合に依存関係を分離してもかまいません。エンドポイントまたはデータベースのモックを新規作成／更新するたびに、許可されたローカル／テスト環境で新たに実クエリを行い、完全な応答をそのままファイルに保存してください。モックはそのファイルから作成し、ドキュメントや捏造したオブジェクトから作成しないでください。秘密情報を含めず、出所情報は別途記録してください。既存のフィクスチャは、新たなキャプチャの代わりにはなりません。古いドキュメントを使うと、実際のエンドポイントとリクエスト／レスポンスの形式が異なるモックが作られるおそれがあります。許可された合成テストデータを使用してください。非公開の応答や認証情報をコミットしないでください。この取り決めに適応する際は、エンドポイントのモック方針を読んでください。アクセス権／予算が不足している場合は、モックの作成／更新や必要な実動作確認は実施できませんが、合格したと偽ることは許されません。

規模と範囲

ルートでは550～800語、ネストされたファイルでは40～120語を目安にし、不変条件が少ない場合はさらに短くします。ルートの語数枠には、7段階の手動 QA 手順、明示的な新規キャプチャのモック方針、および変更しない TDD／コミットのゲートを盛り込む余地があります。200～400語では、必要な確認項目が省かれてしまいます。これらはレビューの目安であり、要件を弱めたり、埋め草を追加したりする許可ではありません。

ルートには、目的／範囲、合意済みの言語方針、わかりにくい共通制約、ドキュメントへの入口を1つ、共通の品質／コミット／完了ゲートのみを記載します。ネストされたファイルには、フォルダー全体に適用される独自のルールが必要です。通常のソース／テスト／リソース用ディレクトリごとにファイルを作成しないでください。

ネストされたコピーは、ルート／プロジェクトに関する節と、すでに適用されている親階層の品質ゲートを削除して調整します。サブツリーの目的と固有の不変条件に関する指示は残します。親の指示を繰り返したり、指示が自動的に読み込まれることを説明したり、ほかの AGENTS.md ファイルへのリンクを記載したりしないでください。フォルダー内だけに適用されるルールをルートに持ち込まないでください。

原則として除外する項目

• 依存関係／ツールの正確なバージョン、ソース数、日付、ブランチ、コミット、ホストのパス／ユーザー名、ローカルサンドボックスのエラー、ツールの利用可否。
• 標準的なレイアウト、パッケージの説明、マニフェストの依存関係一覧、基本的な Git／ツールの使い方、指示読み込みの説明、一般的な能力に関する助言。
• 機能／プロトコルの移行計画、インシデント修正、条件付きテスト手順、プラットフォームのセットアップ、長大なドキュメント参照条件の一覧。
• 依頼されていない PRD／ADR ファイル、架空のコマンド、環境変数、ブランディング、対応 OS の一覧、導入が確認されていないスキル／ツール。

内部フレームワーク、非公開の互換性境界、または標準外のルートは、対象となるすべてのエージェントに必要な場合に限り、記載対象になり得ます。強制されるバージョンはマニフェスト／ドキュメントに記載してください。必要な場合にのみ、安定した互換性ポリシーを参照します。

完了

AGENTS.md.candidate は内部ドラフトであり、納品物ではありません。最終ファイルを提示したり PR を作成したりする前に、同じ作成タスク内で調整、検証、公開／整合性の確保を完了し、AGENTS.md としてください。完成した AGENTS.md のみをコミットし、候補ファイルは削除します。中断した場合は、タスクが未完了であることを報告してください。

実際に変更したファイル、コピーしたテンプレート、調整／移動した内容、実施した確認を示してください。許可がない限り、アプリケーションコードには手を加えないでください。無関係な作業とツール固有の指示は保持してください。CLAUDE.md のインポートは、依頼された場合、または既存の方針として定められている場合にのみ作成してください。ガイダンスを重複させたり、ツール固有の内容を上書きしたりしないでください。

永続的な事実／ポリシーが変更された場合は、影響を受ける指示とドキュメントも、同じ論理的な変更の中で更新するよう求めてください。このスキルを無視するエージェントに対して強制できると主張してはいけません。ヘルパーが保証するのは開始時のコピーまでであり、最終的な範囲と意味はレビューで確認する必要があります。