ousiass 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: 完了
- 修正サマリーを表示:
- モード別の指摘件数
- 修正済み / スキップ / 変更修正 の内訳
- 修正したファイル一覧
- コミットするか
AskUserQuestionで確認 - コミットする場合は CLAUDE.md の規約に従う
ルール
- 質問には必ず
AskUserQuestionを使い選択式で提示する。 テキストだけで質問しない - 自由入力が必要な場合は
AskUserQuestionのallowFreeText: trueを使う - 指摘は重要度順（高→低）に並べる
- 同じファイルの指摘はまとめて連続で提示する
- 既存ファイルの修正は Edit で行う。新規ファイルを作成しない
- 改訂履歴の日付は実行日を使用する
- TaskCreate/TaskUpdate で進捗を管理する