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化する4user-invocable: true5---67# spec-audit89仕様書を正（Single Source of Truth）として、実装漏れ・乖離を検知し GitHub Issue を作成する。1011## 前提条件1213- Claude Code 環境14- `gh` CLI（Issue 作成時）1516## 引数1718- **引数なし**: 対話でヒアリングしてから全体チェック19- **パス指定** (例: `/spec-audit docs/api-spec.md`): 特定ドキュメントに絞ってチェック2021## フェーズ1: ヒアリング2223引数でパスが指定されていない場合、プロジェクトルートを `Glob` で自動探索する：24- `docs/`, `spec/` 配下25- `README.md`, `ARCHITECTURE.md`, `CLAUDE.md`26- OpenAPI/Swagger 定義 (`*.yaml`, `*.json`)27- その他 `.md` ファイル2829検出したドキュメント一覧をユーザーに示し、チェック対象を確認する。3031**検知粒度は機能・エンドポイント単位**。セクション丸ごとではなく「DELETE /users/:id が未実装」のように具体的な単位で報告する。3233検知対象は以下のすべて：341. **仕様 vs 実装**: 仕様書に定義されているが未実装の機能352. **TODO/FIXME/HACK**: コード内の未完了マーカー363. **スキップテスト**: `skip`, `pending`, `xit`, `xdescribe` 等374. **APIスキーマ乖離**: OpenAPI/Swagger 定義 vs 実装ハンドラ3839## フェーズ2: ドキュメント探索40411. Q1 で決まった対象のドキュメントを読み取る422. 各ドキュメントから具体的な主張・仕様を抽出する：43 - エンドポイント定義、関数シグネチャ、CLI 引数44 - データモデル、テーブル定義45 - 機能一覧、振る舞いの記述46 - 設定項目、環境変数473. `TaskCreate` でチェック対象をタスク化する4849## フェーズ3: 実装との突き合わせ5051検知観点は `references/check-criteria.md` を参照。5253#### 3-1: 仕様 vs 実装54551. ドキュメント内の主張（関数名、パス、設定値、振る舞い等）を1つずつ抽出562. `Explore` エージェントや `Grep`/`Glob` で対応する実装を探す573. 一致・不一致・未実装を判定584. 不一致はドキュメント側の行と実装側のファイル:行を記録5960#### 3-2: TODO/FIXME/HACK61621. `Grep` で `TODO`, `FIXME`, `HACK`, `XXX`, `TEMP` を検索632. 各マーカーの内容・ファイル・行番号を記録643. 仕様書との関連があれば紐付ける6566#### 3-3: スキップテスト67681. `Grep` で以下を検索：69 - JS/TS: `it.skip`, `describe.skip`, `xit`, `xdescribe`, `test.skip`70 - Go: `t.Skip`71 - Python: `@pytest.mark.skip`, `@unittest.skip`, `self.skipTest`72 - Ruby: `skip`, `pending`73 - その他: プロジェクトの言語に応じて調整742. 各スキップの理由コメント・ファイル・行番号を記録7576#### 3-4: API スキーマ乖離77781. OpenAPI/Swagger 定義があれば読み取る792. 定義済みエンドポイントに対応するハンドラ・ルートを検索803. 未実装エンドポイントを記録8182## フェーズ4: レポート生成と出力先の確認83841. 検出結果を重大度別に集計する（重大度基準は `references/check-criteria.md`）852. `templates/report.md` の形式でレポートを生成863. `AskUserQuestion` で出力先をユーザーに確認する：87 - **GitHub Issue に作成**（推奨）88 - **ローカル MD ファイルに保存**: プロジェクトルートに `spec-audit-report.md` を生成89 - **コンソール出力**: レポートをそのまま会話に出力9091## フェーズ5: Issue 作成9293出力先で「GitHub Issue に作成」が選ばれた場合：94951. 全件の一覧（タイトル + 重大度）をまとめて表示する962. `AskUserQuestion` で Issue の作成方式を確認：97 - **まとめて1つの Issue**: 全検出結果をチェックリスト形式で1つの Issue にまとめる（推奨）98 - **個別 Issue**: 検出結果1件につき1 Issue を作成する993. 重複チェック: `gh issue list --state open --search "<要約>"` で既存 Issue を検索。重複あり → スキップ or 新規作成か確認1004. Issue 本文は `templates/issue.md` を参照1015. `gh issue create` で作成。ラベル: `spec-audit` + 重大度ラベル（`severity:critical`, `severity:high`, `severity:medium`, `severity:low`）1026. 作成した Issue の URL をユーザーに報告103104## ルール105106- 推測で乖離を報告しない。**実装コードを確認して裏付けを取る**107- 乖離にはドキュメント側と実装側の**両方の箇所**を示す108- コードを修正しない。成果物は Issue とレポートのみ109- Issue 作成前に**必ず承認を得る**110- `TaskCreate`/`TaskUpdate` で進捗を管理する111- 検出件数が多い場合は重大度 🔴🟠 を優先し、🟡🟢 は省略可とする
ousiass