spec-philosophy

name	spec-philosophy
description	仕様駆動開発の方法論とワークフロー。使用場面: - 新機能やプロジェクトの開始（「新機能」「実装」「構築」） - ユーザーリクエストが曖昧または不明確（「何か追加して」「改善して」） - 仕様ファーストの開発を強制（「仕様を書いて」「仕様書を作成」） - 「とにかく作って」と言われたり計画をスキップしたい場合 - 要件、受け入れ基準、スコープの議論 Trigger phrases: specification, PRD, requirements document, scope definition, feature planning
allowed-tools	Read, Write, Glob, AskUserQuestion
model	sonnet
user-invocable	true
context	fork
agent	general-purpose

仕様駆動開発（SDD）

SDD は、実装開始前に明示的な仕様を要求する規律あるソフトウェア開発アプローチ。

基本原則

1. 仕様なしにコードなし

ルール: 承認された仕様なしに実装コードを書かない。

• スコープクリープを防止
• 事前の思考を強制
• 監査証跡を作成
• 正確な見積もりを可能にする

2. コードフリーの仕様（NEW）

ルール: 仕様は「何を」構築するかを記述し、「どのように」コーディングするかは書かない。

仕様に含めるべきもの:

• ユーザーストーリー（INVEST 原則: Independent, Negotiable, Valuable, Estimatable, Small, Testable）
• 受け入れ基準（Gherkin 形式: Given-When-Then）
• 非機能要件（測定可能な目標: 「p95 で < 200ms」、「速い」ではない）
• エッジケースとエラーシナリオ
• スコープ外（明示的な除外項目）
• 成功指標（検証可能な完了基準）

仕様に含めてはいけないもの:

• 実装コードやコードスニペット
• 疑似コードやアルゴリズムの詳細
• 関数シグネチャやクラス定義
• 特定のツール/ライブラリバージョン（「現在の安定版」を使うか省略）
• ステップバイステップの実装手順

コード参照:

• 既存パターンへの file:line ポインタを使用: 「src/services/auth.ts:23 のパターンに従う」
• 何を参照するかを記述し、コード自体は書かない: 「utils/errors.ts のエラーハンドリングパターンを使用」
• NEVER: 仕様書にコードをコピーしない

AI エージェントにとっての重要性:

• 仕様は「何を」定義する契約であり、「どのように」のチュートリアルではない
• AI エージェントは規範的な指示よりゴール指向の仕様でパフォーマンスが向上する
• 仕様内のコードは混乱を生む: それは要件なのか単なる例なのか？
• 仕様を技術非依存で再利用可能に保つ

3. 曖昧さ許容度ゼロ

ルール: 要件が曖昧な場合、推測しない。質問する。

• 推測は手戻りの原因
• 明確化はバグよりコストが低い
• ユーザーは（助けがあれば）何を求めているか知っている

4. 契約としての仕様

ルール: 仕様は実装の真実の情報源。

仕様が定義するもの:

• 何を構築するか（機能要件）
• どの程度の品質で構築するか（非機能要件）
• いつ完了とするか（受け入れ基準）
• 何を構築しないか（スコープ外）

開発フェーズ

フェーズ	名前	アクション	出力
1	曖昧さ	曖昧なリクエストを受領	意図の理解
2	明確化	interview スキルを使用	要件サマリー
3	定義	docs/specs/ に仕様作成	承認済み仕様
4	実行	仕様に従って実装	動作するコード
5	検証	仕様に対してバリデーション	テスト合格

Plan→Review→Implement コマンドとの関係

上記の 5 フェーズモデルは論理的な抽象化。plan→review→implement コマンドはこれを運用ワークフローに展開:

論理フェーズ	コマンド / フェーズ	詳細
1. 曖昧さ	/spec-plan: ディスカバリー	初期要件収集
2. 明確化	/spec-plan: 探索 + 明確化質問	コードベース分析とユーザーインタビュー
3. 定義	/spec-plan: 仕様ドラフト + アーキテクチャ設計	セルフレビュー付きの仕様と設計
4. レビュー	/spec-review: インタラクティブフィードバック	ユーザー主導のプランレビューと改善
5. 実行	/spec-implement: 実装	TDD 駆動の開発

クイックリファレンス

仕様ファイルの場所

docs/specs/
├── SPEC-TEMPLATE.md      # 新規仕様のテンプレート
└── feature-*.md          # 機能仕様

エージェント統合

エージェント	SDD での役割
product-manager	仕様を作成
system-architect	システムレベル設計（ADR、スキーマ）
code-architect	機能実装のブループリント
*-specialist	仕様を実装
qa-engineer	仕様を検証
security-auditor	セキュリティ NFR を監査

追加リソース

詳細情報:

• 完全な仕様テンプレート: references/spec-template.md を参照
• ワークフロー例: examples/workflow-example.md を参照
• プロジェクトテンプレート: docs/specs/SPEC-TEMPLATE.md を参照

構造と柔軟性のバランス

SDD は構造を提供するが、厳格な遵守は効果的な問題解決を妨げることがある。

ゴール指向のアプローチ

Claude Code Best Practices より:

"Claude often performs better with high level instructions rather than step-by-step prescriptive guidance."

SDD への適用:

• フェーズは「何を」達成するかを定義し、正確な「方法」は定義しない
• タスクの複雑さに応じてアプローチを適応
• 本当に不要な場合はフェーズをスキップ（例: タイポ修正）

フル SDD を適用する場合

シナリオ	フル Plan→Implement	簡略化
新機能	はい
複雑な変更	はい
アーキテクチャ判断	はい
バグ修正		はい /debug
タイポ/設定変更		はい /quick-impl
明確でスコープが限定されたタスク		はい /quick-impl

柔軟性条項

SDD ワークフローはフレームワークであり、チェックリストではない。

逸脱が必要な状況を特定した場合:

1. すべての L1 ルールが尊重されていることを確認（コードなしの理解、セキュリティスキップなし）
2. 標準的なアプローチが適さない理由を説明
3. 適応したアプローチで進行

L1 ルール（絶対にスキップしない）:

• 実装前に要件を理解
• セキュリティに関わるコードのセキュリティレビュー
• スコープ変更の承認

L2/L3（必要に応じて適応）:

• 探索エージェントの数
• 仕様書のフォーマット
• シンプルなタスクのフェーズ順序

ルール（L1 - ハード）

• NEVER: 要件を理解せずに実装しない
• ALWAYS: 推測する前に明確化する
• NEVER: 承認なしにスコープを追加しない
• ALWAYS: 重要な逸脱を文書化する
• NEVER: 仕様書にコードスニペット、疑似コード、実装詳細を含めない
• ALWAYS: 仕様書にコードをコピーする代わりに file:line 参照を使用する

デフォルト（L2 - ソフト）

• 1日以上の工数がかかる機能には正式な仕様を作成
• 新機能には /spec-plan を使用（明らかに小さなタスクには /quick-impl を使用可能）
• 受け入れ基準はテスト可能であるべき

ガイドライン（L3）

• consider: 複雑なロジックには TDD を検討
• recommend: 独立した場合はエージェントの並列実行を推奨
• consider: アーキテクチャ判断を ADR に文書化