# Spec Review

> 仕様書をレビューして指摘を1件ずつ確認しながら修正する

- Skill: `ousiass/spec-review` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ousiass/spec-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ousiass/spec-review/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ousiass (https://skillmd.com/u/ousiass)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/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 で進捗を管理する