ousiass/spec-review

spec-review

spec-gen で作成した仕様書をレビューし、指摘を1件ずつユーザーに確認しながら修正する。

前提条件

• Claude Code 環境
• spec-gen 形式の仕様書（docs/ または spec/ ディレクトリ）

引数

• 引数なし: 自動検出した仕様書をレビュー
• パス指定: 指定ディレクトリの仕様書をレビュー
• モード指定: 整合性 コード乖離 品質 すべて のいずれか

レビューモード

| モード | 内容 | |--------|------| | 整合性チェック | 仕様書間の矛盾検出（機能要件↔API、ER↔機能要件、コンポーネント↔API 等） | | コード乖離チェック | 実装コードと仕様書のズレを検出し、仕様書側を更新 | | 品質チェック | フォーマット、記述の曖昧さ、Mermaid図の欠落、改訂履歴の未更新 | | すべて | 上記3モードを順番に実行 |

フェーズ1: 仕様書の検出と読み込み

1-1: 仕様書の探索

引数でパスが指定されている場合:

• そのパスのファイル/ディレクトリを直接読み込む

引数なしの場合: 以下のパターンで検索（Glob を使用）:

**/spec/**/*.md
**/specs/**/*.md
**/docs/**/*.md
**/specifications/**/*.md
**/design/**/*.md

見つからなければユーザーにパスを確認する。

1-2: 全仕様書の読み込み

検出した仕様書をすべて Read で読み込み、内容を把握する。

1-3: モード選択

引数でモードが指定されていなければ AskUserQuestion で確認:

質問: どのレビューモードで実行しますか？
選択肢:
1. 整合性チェック — 仕様書間の矛盾を検出（機能要件↔API、ER↔機能要件 等）
2. コード乖離チェック — 実装コードとのズレを検出し仕様書を更新
3. 品質チェック — フォーマット、曖昧な記述、Mermaid図の欠落、改訂履歴
4. すべて — 上記3モードを順番に実行

フェーズ2: レビュー実施

選択されたモードに応じてレビューを実施する。「すべて」の場合は 整合性 → コード乖離 → 品質 の順で実行。

整合性チェックの観点

以下のクロスリファレンスを検証する:

| 検証対象 | チェック内容 | |----------|-------------| | 機能要件 ↔ API仕様 | 機能一覧の各機能に対応するエンドポイントが存在するか | | 機能要件 ↔ コンポーネント設計 | 画面一覧の各画面に対応するコンポーネントが存在するか | | ER図 ↔ API仕様 | エンドポイントのリクエスト/レスポンスがテーブル定義と整合するか | | ER図 ↔ 機能要件 | 機能で扱うデータがテーブルとして定義されているか | | アーキテクチャ ↔ 非機能要件 | 技術選定が非機能要件を満たしているか | | コンポーネント ↔ API仕様 | コンポーネントが必要とするAPIが定義されているか |

コード乖離チェックの観点

実装コードを探索し、以下を検証する:

| 検証対象 | チェック内容 | |----------|-------------| | API仕様 ↔ ルーティング/ハンドラ | エンドポイントのパス・メソッド・パラメータが一致するか | | ER図 ↔ マイグレーション/モデル | テーブル名・カラム名・型・制約が一致するか | | コンポーネント設計 ↔ 実装コンポーネント | コンポーネント名・Props・依存関係が一致するか | | アーキテクチャ ↔ ディレクトリ構成 | レイヤー構造・技術選定が実態と一致するか |

コードが存在しない場合はスキップし、その旨を報告する。

品質チェックの観点

| 検証対象 | チェック内容 | |----------|-------------| | Mermaid図 | 各ドキュメントに必要な図が含まれているか。構文エラーがないか | | 改訂履歴 | 全ドキュメントに改訂履歴セクションがあるか。日付が妥当か | | 記述の曖昧さ | 「適宜」「必要に応じて」「など」のような曖昧な表現がないか | | テーブル形式 | Markdownテーブルのフォーマットが崩れていないか | | セクション構造 | 見出しレベルの一貫性、必須セクションの欠落がないか | | リンク整合性 | ドキュメント間の相互参照が壊れていないか |

フェーズ3: 指摘の提示と修正

レビューで検出した指摘を 1件ずつ AskUserQuestion で提示する。

指摘の提示形式

各指摘について以下の情報を含める:

質問: [モード名] 指摘 N/全M件 — [対象ファイル名]

[指摘内容の説明]
[該当箇所の引用（あれば）]
[修正案の概要]

選択肢:
1. 修正する — 提案どおりに修正を適用
2. 修正内容を変更する — 修正方針を指定してから適用
3. スキップ — この指摘は対応しない
4. 残りをすべて修正 — 以降の指摘をすべて提案どおりに修正
5. レビュー終了 — 残りの指摘を破棄して終了

修正の適用

• 「修正する」: Edit で修正を適用
• 「修正内容を変更する」: AskUserQuestion で修正方針を自由入力で確認してから適用
• 「残りをすべて修正」: 以降の指摘を確認なしで順次適用
• 修正したドキュメントの改訂履歴を更新する（版を上げ、変更内容・変更理由を記載）

フェーズ4: 完了

1. 修正サマリーを表示:
   • モード別の指摘件数
   • 修正済み / スキップ / 変更修正 の内訳
   • 修正したファイル一覧
2. コミットするか AskUserQuestion で確認
3. コミットする場合は CLAUDE.md の規約に従う

ルール

• 質問には必ず AskUserQuestion を使い選択式で提示する。 テキストだけで質問しない
• 自由入力が必要な場合は AskUserQuestion の allowFreeText: true を使う
• 指摘は重要度順（高→低）に並べる
• 同じファイルの指摘はまとめて連続で提示する
• 既存ファイルの修正は Edit で行う。新規ファイルを作成しない
• 改訂履歴の日付は実行日を使用する
• TaskCreate/TaskUpdate で進捗を管理する