init-or-refactor-agents-md

AGENTS.md の初期作成またはリファクタリング

簡潔で要点を押さえた、標準となる AGENTS.md を 1 つ作成します。

ワークフロー

1. AGENTS.md、CLAUDE.md、CODEX.md、.cursorrules、その他のリポジトリ内の指示ファイルを読みます。
2. 矛盾する指示について、その出典とともに提示し、どちらを優先するか確認します。特に、推測に基づく指示、実装の詳細、フィクスチャに偏ったテストマトリクス、未承認の依存関係、ローカルのパターンを無条件に維持する指示、正当な書き換えを拒む指示が、以下の目標ポリシーと矛盾する場合は明示します。
3. 草案の作成前に、次の順で整理します。write-for-agents の整理ルールを適用し、ツールのラッパーに関するノイズや将来に備えた形式的な手順を削除し、推測に基づく指示、非公開の指示、ブランチごとのマトリクス、フィクスチャに偏ったテスト、見栄えだけのテスト、および不適切な構造を維持するルールを削除します。リポジトリ固有のルール、安全上重要なルール、または繰り返し違反されているルールは残します。新しいセクションを作るより、箇条書き 1 つにまとめることを優先します。削除項目は delete、yagni、tool-noise、test-theater、structure のいずれかに分類します。すべての出典ルールを残すか、これらの分類のいずれかに基づいて削除した時点で完了とします。
4. 既存のブランチ、コミット、PR、レビュー、リリース、デプロイのルールを要約します。ユーザーに、デフォルトブランチへの直接作業（main または trunk で作業）、ブランチ／PR（目的を絞ったブランチを使い、PR を作成または更新）、または別のワークフローのどれにするか確認します。明確なリポジトリ規約を推奨します。デフォルトブランチへの直接作業またはブランチ／PRの場合は、範囲を絞った論理的なコミットと、早い段階から頻繁にプッシュすることを必須にします。ブランチ／PRの場合は、最初の有用な作業単位ができた時点で PR を作成または更新します。承認なしに共有履歴を書き換えてはいけません。別のワークフローの場合は、ユーザーが提示した内容だけを維持します。
5. AGENTS.md には、プロジェクトの説明を 1 行、特別なコマンド、確認済みの Git ワークフロー、すべてのエージェントにリポジトリ全体で適用されるグローバル指示にすでに含まれている場合を除く目標ポリシー、安全上重要なルールや承認ルール、および一部のタスクでのみ必要となる既存ドキュメントへの 1 行の参照だけを記載します。簡潔な箇条書きを使います。依頼がない限り、新しいドキュメントは作成しません。
6. 出典、矛盾点、Git の選択肢、AGENTS.md の草案、分類付きの削除項目を提示します。書き込む前に確認を得ます。
7. AGENTS.md を書き込んだ後、維持するルールを統合し、他の寄与元となった指示ファイルを削除します。明示的に依頼された場合を除き、ツール固有の指示ファイルは作成しません。

対象ポリシー

• ほとんどのテストは負債です。ほかの手段では検出できない現実的な不具合、つまり再発する可能性のあるリリース済みのバグ、別のリポジトリやサービス、ユーザーが依存する契約、または重要な不変条件（セキュリティ、権限、互換性、並行処理、マイグレーション、プロトコル、データ損失）を検出できる場合に限り、テストを維持または追加してください。バグがリリース済みとは、デフォルトブランチに取り込まれたか、ユーザーに届いた状態を指します。不変条件ごとにテストを1つ用意し、それを強制する分岐ごとにテストを用意しないでください。
• 変更が機能することを示せる最も手軽な方法で、すべての変更を検証してください。実行、使い捨てのスクリプト、手動確認などを使います。バグの場合、実用的であれば修正前に再現してください。
• そうした検証のほとんどは破棄してください。上記の基準を満たすものは、新しいテストを書くのではなく昇格させてください。公開インターフェースを通す決定的なシナリオを1つ、適した既存テストに追加します。昇格させた回帰チェックは、修正がなければ引き続き失敗する必要があります。
• プライベートヘルパー、フレームワークや型による保証、同等のケース、またはコードをそのままアサーションに書き直したものをテストしないでください。モックはシステム境界でのみ使用してください。
• 動作を変更したりテストに手を加えたりする場合は、基準を満たさないテストを削除し、その理由を説明してください。意図が不明な場合は、履歴を確認してください。
• 変更を通すために、失敗するテストを削除したり弱めたりしないでください。失敗の原因を調べてください。
• 依頼がない限り、ユニットテスト先行のTDD、カバレッジ目標、テスト専用API、フィクスチャの足場作り、BDDツールは使用しないでください。
• コードを追加する前に、有効な範囲で最も簡単な方法を選んでください。必要性をなくす、既存のリポジトリコード・設定・ツール・ワークフローを使う、標準ライブラリやネイティブ機能を使う、インストール済みの依存関係を使う、小規模なローカルコードを書く、という順に検討し、その後で初めて抽象化、ファイル、サービス、設定項目、依存関係を追加してください。そこで止め、ファイル数を抑え、明示的でシンプルなコードを優先してください。
• セキュリティ、信頼境界の検証、データ損失の防止、アクセシビリティ、可観測性、リポジトリ固有のセーフガードを、簡略化のために取り除かないでください。
• 依存関係を追加する前に、追加しない選択肢を含め、信頼できる代替案を比較してください。現時点の情報源を使って、適合性、ライセンス、保守状況、脆弱性、来歴、推移的依存関係を含むセキュリティを評価してください。置き換えるコードと、新たに生じる義務も考慮してください。情報源とリスクを添えた簡潔な推奨案を提示し、承認を求めてください。
• 垂直スライス単位で作業し、レビューしやすい変更を保ってください。変更箇所のコードを簡素化してください。ローカルのパターンが健全で意図的な場合に限り、それに従ってください。最小のパッチより正しい修正を優先し、適切でない構造はレビュー可能な単位に分けて書き直し、トレードオフを説明してください。
• リスクのある変更や破壊的な変更の前には確認を求め、完了前に関連するチェックを実行してください。