spec-critique

仕様レビューのスキル

概要

仕様書の正確性、完全性、実現可能性を批判的にレビューします。実装を始める前に問題を見つけるため、拡張思考を使用します。

基本原則： 拡張思考（深い分析）を使用します。実装を始める前に問題を見つけます。

使用するタイミング

必ず使用する場合：

• 仕様書の作成が完了した後
• 実装計画を始める前
• 仕様に外部連携が含まれる場合
• 複数のコンポーネントを含む複雑な機能の場合

例外：

• 単純な変更に関する簡単な仕様
• 別のエージェントがすでにレビューした仕様

絶対原則

NO IMPLEMENTATION WITHOUT SPEC CRITIQUE FOR COMPLEX TASKS

外部連携や複数サービスにまたがる変更などの複雑なタスクでは、必ず仕様レビューを行います。

必要な入力

レビューの前に、以下を用意してください。

1. spec.md - レビュー対象の仕様書
2. 要件ドキュメント - ユーザーの元の要件
3. プロジェクトのコンテキスト - 技術スタック、パターン

ワークフロー

フェーズ 1：すべてのコンテキストを読み込む

# Read the spec
cat .claude/context/specs/[task-name]-spec.md

# Read original requirements
cat .claude/context/requirements/[task-name].md

# Read project context
cat .claude/context/tech-stack.md

以下を把握します。

• 仕様書に記載されている内容
• ユーザーが当初依頼した内容
• コードベースに存在するパターン

フェーズ 2：深い分析（拡張思考を使用）

重要： このフェーズでは拡張思考を使用します。以下について深く考えます。

技術的な正確性

仕様書を要件およびコードベースと照合します。

• パッケージ名：仕様書で正しいパッケージ名が使われていますか？
• インポート文：インポートは API のパターンと一致していますか？
• API 呼び出し：関数のシグネチャはドキュメントと一致していますか？
• 設定：環境変数や設定オプションは正しいですか？

よくある仕様書の誤りを確認します。

• パッケージ名が誤っている（例：「react-query」と「@tanstack/react-query」）
• 古い API パターンを使っている（例：非推奨の関数を使用している）
• 関数のシグネチャが正しくない（例：パラメーターの順序が誤っている）
• 必須の設定が不足している（例：環境変数の不足）

不一致があれば指摘します。

完全性

要件と照合します。

• すべての要件を網羅しているか？ - 各要件に実装の詳細が記載されている必要があります
• すべての受け入れ基準をテストできるか？ - 各基準を検証できる必要があります
• エッジケースに対応しているか？ - エラー条件、空の状態、タイムアウトなど
• 連携ポイントが明確か？ - コンポーネント同士の接続方法

不足があれば指摘します。

一貫性

仕様書内で確認します。

• パッケージ名に一貫性があるか - 同じ名前が全体を通して使われている
• ファイルパスに一貫性があるか - パスに矛盾がない
• パターンに一貫性があるか - 全体を通して同じスタイルである
• 用語に一貫性があるか - 同じ概念に同じ用語が使われている

不整合があれば指摘します。

実現可能性

実行可能性を確認します。

• 依存関係を利用できるか？ - すべてのパッケージが存在し、保守されている
• インフラは現実的か？ - セットアップが動作する
• 実装順序は論理的か？ - 依存されるものを先に実装する
• スコープは適切か？ - 過剰設計でも、仕様不足でもない

懸念事項があれば指摘します。

要件との整合性

要件と相互参照します。

• 検証済みの情報を使用しているか？ - 仕様書には調査済みの事実を使用する必要があります
• 未検証の主張に印が付いているか？ - 仮定があれば明確に示されている
• 注意点に対処しているか？ - 既知の問題に対応している
• 推奨事項に従っているか？ - 要件での提案が反映されている

相違点があれば指摘します。

フェーズ 3：問題を一覧化する

見つかった問題をすべて一覧にします。

## Issues Found

### 1. [SEVERITY: HIGH] Package name incorrect

- **Spec says**: "[incorrect]"
- **Should be**: "[correct]"
- **Location**: Line 45, Requirements section

### 2. [SEVERITY: MEDIUM] Missing edge case

- **Requirement**: "Handle connection failures"
- **Spec**: No error handling specified
- **Location**: Implementation Notes section

### 3. [SEVERITY: LOW] Inconsistent terminology

- **Issue**: Uses both "memory" and "episode" for same concept
- **Location**: Throughout document

フェーズ 4：問題を修正する

見つかった問題ごとに、仕様書を直接修正します。

修正ごとに：

1. 仕様書を変更する
2. 変更が反映されたことを確認する
3. 変更内容を記録する

フェーズ 5：レビュー報告書を作成する

# Spec Critique Report

**Spec**: [spec-name]
**Date**: [timestamp]

## Summary

| Category               | Status    | Issues  |
| ---------------------- | --------- | ------- |
| Technical Accuracy     | PASS/FAIL | [count] |
| Completeness           | PASS/FAIL | [count] |
| Consistency            | PASS/FAIL | [count] |
| Feasibility            | PASS/FAIL | [count] |
| Requirements Alignment | PASS/FAIL | [count] |

## Issues Found and Fixed

### High Severity

1. [Issue] - FIXED: [what was changed]

### Medium Severity

1. [Issue] - FIXED: [what was changed]

### Low Severity

1. [Issue] - FIXED: [what was changed]

## No Issues Found (if applicable)

Spec is well-written with no significant issues found.

## Confidence Level

[HIGH/MEDIUM/LOW]

## Recommendations

- [Any remaining concerns or suggestions]

フェーズ 6：修正を検証する

変更を加えた後：

# Verify spec is still valid markdown
head -50 .claude/context/specs/[task-name]-spec.md

# Check key sections exist
grep -E "^##? Overview" spec.md
grep -E "^##? Requirements" spec.md
grep -E "^##? Success Criteria" spec.md

重大度のガイドライン

高 - 実装の失敗につながる問題：

• パッケージ名の誤り
• API シグネチャの誤り
• 重要な要件の欠落
• 無効な設定

中 - 問題につながる可能性がある事項：

• エッジケースの不足
• エラー処理の不備
• 連携ポイントが不明確
• パターンの不整合

低 - 軽微な改善事項：

• 用語の不整合
• ドキュメントの不足
• スタイル上の問題
• 軽微な最適化

カテゴリーの定義

• 正確性：技術的な正しさ（パッケージ、API、設定）
• 完全性：要件とエッジケースの網羅性
• 一貫性：ドキュメント内の整合性
• 実現可能性：実用的に実装できるか
• 要件との整合性：元の要件との一致度

検証チェックリスト

仕様の批評を完了する前に：

• 拡張思考を用いてすべてのセクションを分析した
• 技術的な正確性を検証した
• 要件と照らし合わせて完全性を確認した
• 仕様全体の一貫性を検証した
• 実現可能性を評価した
• すべての問題を重大度別に記録した
• 重大度が高い問題と中程度の問題をすべて修正した
• 批評レポートを作成した
• 修正後も仕様が有効であることを確認した

拡張思考のプロンプト

分析時には、次の点を考えてください。

「この仕様を見て、要件と照らし合わせて深く分析する必要があります……

まず、すべてのパッケージ名を確認します。要件には [X] とありますが、仕様には [Y] とあります。これは不一致であり、修正が必要です。

次に、API のパターンを確認します。要件では初期化に [手順] が必要とされていますが、仕様には [異なる手順] が記載されています。これも問題です。

完全性については、要件に [X、Y、Z] が記載されています。仕様では X と Y に対応していますが、Z への対応はどこにも見当たりません。これは抜け漏れです。

一貫性については、'[用語1]' と '[用語2]' が同じ意味で使われています。どちらかに統一すべきでしょうか。

実現可能性については、セットアップは正しいようです。設定も一致しています。

全体として、この仕様を実装に進める前に修正が必要な問題が [N] 件見つかりました。」

よくある間違い

表面的なレビュー

なぜいけないのか： ざっと読むだけでは重大な問題を見落とします。

代わりに行うこと： 拡張思考を用いて、各セクションを深く分析します。

問題の報告だけで修正しない

なぜいけないのか： 問題を列挙するだけでは仕様は改善されません。

代わりに行うこと： 問題を直接修正し、仕様をより良いものにします。

他のスキルとの連携

このスキルは、次のスキルと相性が良いです。

• spec-writing：批評対象となる仕様を提供します
• complexity-assessment：批評が必要かどうかの判断に役立ちます
• debugging：仕様の批評でコードの問題が見つかった場合に使用します

絶対原則

1. たとえ軽微なものであっても、矛盾を含む仕様を決して承認しないでください
2. 隠れた前提を必ず明示してください。明示された要件と同じくらい重要です
3. 仕様レビューでスコープクリープを決して見過ごさないでください
4. 承認する前に、エッジケースとエラーシナリオを必ず検証してください
5. 実装方法を決して批評しないでください。仕様の完全性と一貫性のみに焦点を当てます

アンチパターン

アンチパターン	なぜ問題なのか	正しいアプローチ
矛盾のある仕様を承認する	後工程の実装で、矛盾が誤って解決される	承認前に、軽微なものも含めてすべての矛盾を指摘する
隠れた前提を見落とす	実装時に、前提が要件と食い違う	仕様が依拠するすべての前提を明示する
エッジケースのレビューを省略する	実装中にエラーシナリオが見つかり、対応が遅れる	仕様内のすべての境界条件とエラーパスを検証する
実装の詳細を批評する	仕様の品質から注意がそれる。仕様が定めるのは「何を」であり、「どのように」ではない	完全性、一貫性、テスト可能性に批評の焦点を当てる
曖昧な成功基準を受け入れる	成果物が完成したかどうかを検証できない	すべての要件に対し、測定可能でテスト可能な受け入れ基準を求める

メモリプロトコル

開始前： .claude/context/memory/learnings.md を読みます。

完了後：

• 新しいパターン -> .claude/context/memory/learnings.md
• 問題を発見した場合 -> .claude/context/memory/issues.md
• 決定した場合 -> .claude/context/memory/decisions.md

中断されたものとして扱ってください：メモリに記録されていなければ、実行されていません。