spec-audit
仕様書を正（Single Source of Truth）として、実装漏れ・乖離を検知し GitHub Issue を作成する。
前提条件
- Claude Code 環境
gh CLI（Issue 作成時）
引数
- 引数なし: 対話でヒアリングしてから全体チェック
- パス指定 (例:
/spec-audit docs/api-spec.md): 特定ドキュメントに絞ってチェック
フェーズ1: ヒアリング
引数でパスが指定されていない場合、プロジェクトルートを Glob で自動探索する：
docs/, spec/ 配下README.md, ARCHITECTURE.md, CLAUDE.md- OpenAPI/Swagger 定義 (
*.yaml, *.json)
- その他
.md ファイル
検出したドキュメント一覧をユーザーに示し、チェック対象を確認する。
検知粒度は機能・エンドポイント単位。セクション丸ごとではなく「DELETE /users/:id が未実装」のように具体的な単位で報告する。
検知対象は以下のすべて：
- 仕様 vs 実装: 仕様書に定義されているが未実装の機能
- TODO/FIXME/HACK: コード内の未完了マーカー
- スキップテスト:
skip, pending, xit, xdescribe 等
- APIスキーマ乖離: OpenAPI/Swagger 定義 vs 実装ハンドラ
フェーズ2: ドキュメント探索
- Q1 で決まった対象のドキュメントを読み取る
- 各ドキュメントから具体的な主張・仕様を抽出する：
- エンドポイント定義、関数シグネチャ、CLI 引数
- データモデル、テーブル定義
- 機能一覧、振る舞いの記述
- 設定項目、環境変数
TaskCreate でチェック対象をタスク化する
フェーズ3: 実装との突き合わせ
検知観点は references/check-criteria.md を参照。
3-1: 仕様 vs 実装
- ドキュメント内の主張（関数名、パス、設定値、振る舞い等）を1つずつ抽出
Explore エージェントや Grep/Glob で対応する実装を探す- 一致・不一致・未実装を判定
- 不一致はドキュメント側の行と実装側のファイル:行を記録
3-2: TODO/FIXME/HACK
Grep で TODO, FIXME, HACK, XXX, TEMP を検索- 各マーカーの内容・ファイル・行番号を記録
- 仕様書との関連があれば紐付ける
3-3: スキップテスト
Grep で以下を検索：
- JS/TS:
it.skip, describe.skip, xit, xdescribe, test.skip
- Go:
t.Skip
- Python:
@pytest.mark.skip, @unittest.skip, self.skipTest
- Ruby:
skip, pending
- その他: プロジェクトの言語に応じて調整
- 各スキップの理由コメント・ファイル・行番号を記録
3-4: API スキーマ乖離
- OpenAPI/Swagger 定義があれば読み取る
- 定義済みエンドポイントに対応するハンドラ・ルートを検索
- 未実装エンドポイントを記録
フェーズ4: レポート生成と出力先の確認
- 検出結果を重大度別に集計する（重大度基準は
references/check-criteria.md）
templates/report.md の形式でレポートを生成AskUserQuestion で出力先をユーザーに確認する：
- GitHub Issue に作成（推奨）
- ローカル MD ファイルに保存: プロジェクトルートに
spec-audit-report.md を生成
- コンソール出力: レポートをそのまま会話に出力
フェーズ5: Issue 作成
出力先で「GitHub Issue に作成」が選ばれた場合：
- 全件の一覧（タイトル + 重大度）をまとめて表示する
AskUserQuestion で Issue の作成方式を確認：
- まとめて1つの Issue: 全検出結果をチェックリスト形式で1つの Issue にまとめる（推奨）
- 個別 Issue: 検出結果1件につき1 Issue を作成する
- 重複チェック:
gh issue list --state open --search "<要約>" で既存 Issue を検索。重複あり → スキップ or 新規作成か確認
- Issue 本文は
templates/issue.md を参照
gh issue create で作成。ラベル: spec-audit + 重大度ラベル（severity:critical, severity:high, severity:medium, severity:low）- 作成した Issue の URL をユーザーに報告
ルール
- 推測で乖離を報告しない。実装コードを確認して裏付けを取る
- 乖離にはドキュメント側と実装側の両方の箇所を示す
- コードを修正しない。成果物は Issue とレポートのみ
- Issue 作成前に必ず承認を得る
TaskCreate/TaskUpdate で進捗を管理する- 検出件数が多い場合は重大度 🔴🟠 を優先し、🟡🟢 は省略可とする
1---2name: spec-audit3description: 仕様書と実装の乖離を全方位チェックし、未実装・TODO・スキップテスト等をIssue化する4---56# spec-audit78仕様書を正（Single Source of Truth）として、実装漏れ・乖離を検知し GitHub Issue を作成する。910## 前提条件1112- Claude Code 環境13- `gh` CLI（Issue 作成時）1415## 引数1617- **引数なし**: 対話でヒアリングしてから全体チェック18- **パス指定** (例: `/spec-audit docs/api-spec.md`): 特定ドキュメントに絞ってチェック1920## フェーズ1: ヒアリング2122引数でパスが指定されていない場合、プロジェクトルートを `Glob` で自動探索する：23- `docs/`, `spec/` 配下24- `README.md`, `ARCHITECTURE.md`, `CLAUDE.md`25- OpenAPI/Swagger 定義 (`*.yaml`, `*.json`)26- その他 `.md` ファイル2728検出したドキュメント一覧をユーザーに示し、チェック対象を確認する。2930**検知粒度は機能・エンドポイント単位**。セクション丸ごとではなく「DELETE /users/:id が未実装」のように具体的な単位で報告する。3132検知対象は以下のすべて：331. **仕様 vs 実装**: 仕様書に定義されているが未実装の機能342. **TODO/FIXME/HACK**: コード内の未完了マーカー353. **スキップテスト**: `skip`, `pending`, `xit`, `xdescribe` 等364. **APIスキーマ乖離**: OpenAPI/Swagger 定義 vs 実装ハンドラ3738## フェーズ2: ドキュメント探索39401. Q1 で決まった対象のドキュメントを読み取る412. 各ドキュメントから具体的な主張・仕様を抽出する：42 - エンドポイント定義、関数シグネチャ、CLI 引数43 - データモデル、テーブル定義44 - 機能一覧、振る舞いの記述45 - 設定項目、環境変数463. `TaskCreate` でチェック対象をタスク化する4748## フェーズ3: 実装との突き合わせ4950検知観点は `references/check-criteria.md` を参照。5152#### 3-1: 仕様 vs 実装53541. ドキュメント内の主張（関数名、パス、設定値、振る舞い等）を1つずつ抽出552. `Explore` エージェントや `Grep`/`Glob` で対応する実装を探す563. 一致・不一致・未実装を判定574. 不一致はドキュメント側の行と実装側のファイル:行を記録5859#### 3-2: TODO/FIXME/HACK60611. `Grep` で `TODO`, `FIXME`, `HACK`, `XXX`, `TEMP` を検索622. 各マーカーの内容・ファイル・行番号を記録633. 仕様書との関連があれば紐付ける6465#### 3-3: スキップテスト66671. `Grep` で以下を検索：68 - JS/TS: `it.skip`, `describe.skip`, `xit`, `xdescribe`, `test.skip`69 - Go: `t.Skip`70 - Python: `@pytest.mark.skip`, `@unittest.skip`, `self.skipTest`71 - Ruby: `skip`, `pending`72 - その他: プロジェクトの言語に応じて調整732. 各スキップの理由コメント・ファイル・行番号を記録7475#### 3-4: API スキーマ乖離76771. OpenAPI/Swagger 定義があれば読み取る782. 定義済みエンドポイントに対応するハンドラ・ルートを検索793. 未実装エンドポイントを記録8081## フェーズ4: レポート生成と出力先の確認82831. 検出結果を重大度別に集計する（重大度基準は `references/check-criteria.md`）842. `templates/report.md` の形式でレポートを生成853. `AskUserQuestion` で出力先をユーザーに確認する：86 - **GitHub Issue に作成**（推奨）87 - **ローカル MD ファイルに保存**: プロジェクトルートに `spec-audit-report.md` を生成88 - **コンソール出力**: レポートをそのまま会話に出力8990## フェーズ5: Issue 作成9192出力先で「GitHub Issue に作成」が選ばれた場合：93941. 全件の一覧（タイトル + 重大度）をまとめて表示する952. `AskUserQuestion` で Issue の作成方式を確認：96 - **まとめて1つの Issue**: 全検出結果をチェックリスト形式で1つの Issue にまとめる（推奨）97 - **個別 Issue**: 検出結果1件につき1 Issue を作成する983. 重複チェック: `gh issue list --state open --search "<要約>"` で既存 Issue を検索。重複あり → スキップ or 新規作成か確認994. Issue 本文は `templates/issue.md` を参照1005. `gh issue create` で作成。ラベル: `spec-audit` + 重大度ラベル（`severity:critical`, `severity:high`, `severity:medium`, `severity:low`）1016. 作成した Issue の URL をユーザーに報告102103## ルール104105- 推測で乖離を報告しない。**実装コードを確認して裏付けを取る**106- 乖離にはドキュメント側と実装側の**両方の箇所**を示す107- コードを修正しない。成果物は Issue とレポートのみ108- Issue 作成前に**必ず承認を得る**109- `TaskCreate`/`TaskUpdate` で進捗を管理する110- 検出件数が多い場合は重大度 🔴🟠 を優先し、🟡🟢 は省略可とする
ousiass