spec-best-practices

命名

必ず SPEC.md にします。主要な仕様ファイルに例外はありません。feature.spec.md でも SPEC-feature.md でもありません。

SPEC.md の目次からリンクされる補足ドキュメントには、説明的な名前（例：commands.spec.md）を使用できます。ただし、ルートに SPEC.md があり、そこからリンクされている場合に限ります。

配置

仕様書は、説明対象のコードと同じ場所に配置します。プロジェクト全体の範囲にはルートの SPEC.md、アプリの範囲には apps/foo/SPEC.md、パッケージの範囲には packages/bar/SPEC.md を使用します。

• spec/、docs/specs/、docs/plans/ ディレクトリは避けてください。同じ場所に配置した SPEC.md ファイルを優先します。
• 計画ドキュメントは一時的なものです。長期的に有効な決定事項は該当する SPEC.md に取り込み、計画ドキュメントを削除してください。
• 仕様書が長くなったら、隣接する補足ファイル（./commands.spec.md など）へのリンクを含む目次を追加してください。補足ファイルはサブディレクトリではなく、SPEC.md と同じ場所に配置します。

内容

仕様書は自由形式の Markdown です。固定テンプレートや YAML フロントマターはなく、必須のセクション順もありません。次の要素は必ず含めてください。

問題と解決策 -- このシステムや機能が存在する理由を説明する背景を記述します。問題から書き始めてください。

ドメインモデル -- 型、関係、データフローを記述します。既存コードに基づいて遡及的に仕様書を作成する場合は、調査したコードから導き出してください。

REQ-* ID 付きの要件 -- 動作に関するすべての要件に、安定した識別子を付与します。形式：REQ-{DOMAIN}-{NNN}（例：REQ-AUTH-001）。追記のみとし、番号を振り直してはいけません。各要件はテスト可能で、トレーサビリティを確保できるものにしてください。

不変条件 -- 常に満たす必要がある条件です。

対象外 -- 明示的なスコープ境界です。この仕様書で意図的に扱わない内容を記述します。

受け入れ基準 -- 説明文ではなく、Markdown のチェックリストにします。

- [ ] Auth endpoint returns JWT with tier claim
- [ ] Rate limiter rejects >100 req/min per IP

リスクタグ（条件付き）-- スキーマの移行、認証の変更、公開 API の契約、インフラの変更などの高リスク項目が存在する場合、または ADF PLAN ゲートで承認が必要な場合は、その項目にフラグを付けます。

テストのトレーサビリティ（条件付き）-- REQ-* とテストファイルの行番号の対応付けです。初回の作成時ではなく、TDD 中またはその後に追加します。

作成ルール

証拠に基づくこと：仕様書の内容を書く前にコードを読みます。動作、シグネチャ、ファイルパスを捏造してはいけません。既存コードに基づいて遡及的に仕様書を作成する場合は、実際の実装から要件を導き出してください。

主張の強さを適用されるチェックに合わせること：「表現不可能」、「できない」、「構造的に検出される」、「どんな回帰もチェックで検出される」といった断定的な表現は、実際にチェックが証明できる内容と一致させます。レビュー担当者が60秒以内に反例（コメント中の偽装、文字列リテラル、シャドーイングされたバインディング、計算されたパス）を作れるなら、SPEC は過剰な主張をしています。チェックを強化するか、主張の範囲を狭める（例：「リテラルな spawn の回帰を防止し、コメント・文字列・シャドーイングのケースは補完テストでカバーする」）か、未解決項目としてギャップを記録してください。証拠に裏付けられた慎重な表現は、却下の繰り返しを招く強い表現よりも優先されます。

遡及的な仕様書も第一級の成果物として扱うこと：既存の動作を文書化することは妥当であり、推奨されます。実装を読み、実際の動作から要件を抽出し、不整合は黙って省略せず未解決項目として記載し、既存のテストに対応付けてトレーサビリティを示してください。

変更ポリシー：ユーザーから明示的な指示がない限り、仕様書を編集してはいけません。仕様書と実装の乖離を見つけたら、すぐに明らかにしてください。乖離を黙認したり修正したりしてはいけません。仕様書とコードのどちらを更新するかは、ユーザーが決定します。

仕様書と計画書：仕様書では「何を」「なぜ」を記述し、計画書では「どのように」「いつ」を記述します。計画書は一時的なものです。長期的に有効な決定事項は仕様書に取り込み、計画書を削除してください。

ライフサイクル

作成（SPEC ゲート）：ゲートの要件については、CLAUDE.md の ADF SPEC ゲートを参照してください。配置場所を決め、既存のファイルを読み、抜け漏れを特定するか（または正しい同じ場所のパスに作成し）、必須要素がすべて含まれていることを確認します。

保守：動作が変わったら仕様を更新します。新しい REQ-* ID は追記し、番号を振り直さないでください。テストの作成に合わせてテストとのトレーサビリティを追加し、仕様と実装の両方がコンテキストにある場合は必ず照合して、乖離があれば明らかにします。

廃止：機能を削除したら、その SPEC.md を削除またはアーカイブします。削除済みの動作を説明する古い仕様を残さないでください。