spec-driven-review

完了した仕様駆動型変更のコード品質をレビューします。

このスキルのコマンド

このスキルで使う正確なコマンドを思い出せない場合は、実行する前にここで確認してください。推測しないでください。

modify: node {{SKILL_DIR}}/scripts/spec-driven.js modify
apply: node {{SKILL_DIR}}/scripts/spec-driven.js apply <name>
audit-spec-mapping-coverage: node {{SKILL_DIR}}/scripts/spec-driven.js audit-spec-mapping-coverage <spec-path> [--implementation <repo-path> ...] [--tests <repo-path> ...]
audit-unmapped-spec-evidence: node {{SKILL_DIR}}/scripts/spec-driven.js audit-unmapped-spec-evidence [--implementation <repo-path> ...] [--tests <repo-path> ...]

前提条件

.spec-driven/ ディレクトリがプロジェクトのルートに存在している必要があります。先に進む前に、次を実行して確認してください。

ls .spec-driven/

確認に失敗した場合、プロジェクトは初期化されていません。まず /spec-driven-init を実行してください。

手順

1. 変更を選択する — node {{SKILL_DIR}}/scripts/spec-driven.js modify を実行して、アクティブな変更を一覧表示します。どの変更をレビューするか尋ねてください。すでに指定されている場合は、それを使用します。

2. 準備状況を確認する — 次を実行します。

   node {{SKILL_DIR}}/scripts/spec-driven.js apply <name>
   

   remaining > 0 の場合は中止してください。変更はまだレビューできる状態ではありません。まず /spec-driven-apply を実行するよう提案してください。

3. コンテキストを読み込む — 次を読みます。

   • .spec-driven/changes/<name>/proposal.md — 変更の範囲と変更されない動作
   • .spec-driven/changes/<name>/specs/ — 意図した動作の変更を記述する差分仕様
   • .spec-driven/changes/<name>/design.md — アプローチと決定事項
   • .spec-driven/changes/<name>/tasks.md — 実装内容
   • .spec-driven/changes/<name>/questions.md — 決定やトレードオフの説明に役立つ、解決済みの回答
   • .spec-driven/config.yaml — test ルールや fileMatch エントリを含む、プロジェクトのコンテキストとルール
   • 関連するメイン仕様ファイルと差分仕様ファイルのマッピング用フロントマター

4. 変更されたファイルを特定する — 完了したタスクとマッピング用 フロントマターから、作成または変更されたファイルを特定します。該当する仕様ファイルに関連付けられた、マッピング済みの実装ファイルとテストファイルを含め、各ファイルをすべて読みます。

5. 専門的なレビュー用チェックリストを特定する — 指摘事項を出す前に、 提案、差分仕様、設計、タスク、質問、変更されたファイル、マッピング用フロントマター、 リポジトリのコンテキストを根拠として、変更を分類します。 該当するすべてのチェックリストを適用します。チェックリストの振り分けは 追加的なものであり、基本レビュー項目の代わりにはなりません。レビュー対象のコードは、作成者に左右されないものとして扱ってください。 コードがAIによって生成された、自分が以前に作成した、または人間が書いた可能性を理由に、信頼したりレビューを甘くしたりしないでください。

   対応するチェックリストの種類：

   • セキュリティ上の影響がある変更：認証、認可、権限、シークレット、トークン、入力境界、データ露出、依存関係の信頼性、安全な失敗動作に関わる変更。
   • UI：ユーザーが目にする画面、レイアウト、インタラクション状態、アクセシビリティ、キーボード操作、レスポンシブ動作、視覚的なリグレッションに関わる変更。
   • DX：コマンド、プロンプト、生成アーティファクト、ドキュメント、運用担当者向けメッセージ、エラーメッセージ、セットアップ、ローカルでのワークフローの使いやすさに関わる変更。
   • 移行：データ変換、ファイルシステムまたはスキーマの移行、後方互換性、冪等性、ロールバック、部分的な失敗時の動作に関わる変更。
   • API：公開または内部の契約、コマンド引数、JSON の形式、エラーの意味、検証動作、バージョン管理、呼び出し元への影響に関わる変更。
   • メンテナンス：定期または手動のメンテナンス、依存関係の更新、生成ファイル、リポジトリの整理、再現性、無関係な変更の回避に関わる変更。

6. コード品質をレビューする — 変更された各ファイルについて、ベースラインのレビュー項目と、ステップ 5 で特定した専門チェックリストの項目を実行します。

   • 公平性：誰が書いたかではなく、実際に存在するコードを評価します。AI が作成したコードや自分が作成したコードの指摘事項を抑制、緩和、または省略してはいけません。
   • 可読性：明確な命名、適切な関数の長さ、不必要な複雑さがないことを確認します。
   • セキュリティ：インジェクションの脆弱性やハードコードされたシークレットがなく、システム境界で適切に入力を検証していることを確認します。
   • エラー処理：外部呼び出しとユーザー入力を適切に処理し、エラーを握りつぶしていないことを確認します。
   • パフォーマンス：明らかな N+1 クエリ、不必要な割り当て、非同期コンテキストでのブロッキング呼び出しがないことを確認します。
   • ベストプラクティス：プロジェクトの規約（config.yaml のコンテキストに基づく）に従い、デッドコードや残存するデバッグ用の成果物がないことを確認します。
   • セキュリティ重視のチェックリスト：認可の境界、シークレットの取り扱い、インジェクション耐性、データ漏えい、検証、安全なフェイル動作を確認します。
   • UI チェックリスト：主要なインタラクション、アクセシビリティ、レイアウトの安定性、状態遷移、レスポンシブ動作、ユーザーに見えるリグレッションのテスト範囲を確認します。
   • DX チェックリスト：コマンドの使いやすさ、ドキュメントやプロンプトの明確さ、対応可能なエラーメッセージ、セットアップとの互換性、既存のワークフローとの一貫性を確認します。
   • 移行チェックリスト：冪等性、後方互換性、ロールバックまたは復旧の要件、部分的な失敗への対処、データの保持を確認します。
   • API チェックリスト：コントラクトの互換性、検証、エラーの意味、バージョニングまたは移行の要件、呼び出し元への影響を確認します。
   • 保守性チェックリスト：再現性、依存関係や生成成果物の安全性、リポジトリの整理状態、無関係な変更がないことを確認します。

7. テストの品質を確認する — この変更に関連するテストファイルを読みます。

   • テストでは、差分仕様にある主要なシナリオを網羅していますか？
   • テストは独立していて、繰り返し実行できますか？
   • テストは config.yaml の rules.test に従っていますか？
   • mapping.tests の項目は最新で、今後の検証に役立つものですか？
   • 関連する専門チェックリストのリスクのうち、観察・テスト可能なものをテストで網羅していますか？

8. マッピングの品質を監査する — この変更に関連する、変更された各仕様ファイルについて、以下を確認します。

   • mapping.implementation と mapping.tests を、この変更の主要な実装ファイルおよび直接検証するテストファイルと照合します。
   • 変更されたファイル、差分仕様、完了したタスク、およびすでに読み込んだマッピング済みファイルから、確実性を保てる最小限の証拠セットを使用します。
   • 比較を明確にするうえで役立つ場合は、node {{SKILL_DIR}}/scripts/spec-driven.js audit-spec-mapping-coverage <spec-path> [--implementation <repo-path> ...] [--tests <repo-path> ...] を実行します。
   • レビュー対象の実装ファイルやテストファイルがすべてのメイン仕様マッピングから漏れていないか確認するうえで役立つ場合は、node {{SKILL_DIR}}/scripts/spec-driven.js audit-unmapped-spec-evidence [--implementation <repo-path> ...] [--tests <repo-path> ...] を実行します。
   • 古くなったマッピングや誤解を招くマッピングは、少なくとも SHOULD FIX として報告します。
   • 不一致が今後の検証やアーカイブ準備に重大な誤解を招く場合は、MUST FIX に引き上げます。
   • 未マッピング監査で、このレビュー対象の変更に関する主要な実装ファイルまたは直接検証するテストファイルが、すべてのメイン仕様マッピングから漏れていることが判明した場合は、MUST FIX として扱います。
   • 未マッピング監査で、このレビューの範囲外のファイルや関連性の弱い候補しか見つからなかった場合は、SHOULD FIX またはリポジトリ上の課題として別途報告します。

9. レビュー報告を出力する：

   MUST FIX（アーカイブを妨げる項目）：
     - [一覧、または「なし」]
   
   SHOULD FIX（推奨事項）：
    - [一覧、または「なし」]
   
   NITS（任意）：
    - [一覧、または「なし」]
   

10. Recommend next step:

    • If MUST FIX issues: address them before archiving
    • If only SHOULD FIX: ask user if they want to address them or proceed
    • If clean: suggest /spec-driven-archive <name>

Rules

• Read every changed file before commenting on it — never review code you haven't read
• Focus on real issues, not style preferences already handled by linters
• Review code based on evidence in the code and tests, never on authorship or assumed intent
• MUST FIX = security vulnerabilities, data loss risks, broken functionality
• SHOULD FIX = maintainability concerns, missing error handling, unclear logic
• NITS = naming suggestions, minor simplifications, documentation gaps
• Do not re-review code that was not changed by this change
• Respect config.yaml rules — violations of project rules are SHOULD FIX at minimum
• Report stale or misleading spec mappings when they would make future verification unreliable
• Specialized checklist findings use the same severity model as the baseline review: MUST FIX for archive blockers, SHOULD FIX for recommended fixes, and NITS for optional cleanup
• Never give self-authored or AI-authored code lighter treatment than human-authored code