Spec-Driven Development

構造化された計画を通じて品質、保守性、および成功する納品を確保する、体系的なソフトウェア機能開発の包括的な方法論です。

このスキルを使用する場合

理想的なシナリオ:

• 複数のコンポーネント、統合、またはユーザー操作を含む複雑な機能
• 再作業コストが大きい高リスク プロジェクト
• 共通認識が必要なチーム協力
• 明確な構造により出力品質が向上する AI アシスト開発
• 将来の保守者のための知識保存

あまり適さない場合:

• 明白な解決策を持つ簡単なバグ修正
• 迅速な反復を目的とした実験的プロトタイプ
• 即座の対応が必要な時間に追われているホットフィックス
• あいまいさが最小限で確立されたパターン

3 フェーズ ワークフロー

フェーズ 1: 要件ガイザリング

目的: 曖昧な機能アイデアを明確でテスト可能な要件に変換する

プロセス:

1. 価値と目的を表現するユーザーストーリーを取得する
2. EARS フォーマット (Easy Approach to Requirements Syntax) を使用して受け入れ基準を定義する
3. エッジケースと制約を特定する
4. 完全性と実行可能性を検証する

EARS フォーマット パターン:

WHEN [event] THEN [system] SHALL [response]
IF [precondition] THEN [system] SHALL [response]
WHEN [event] AND [condition] THEN [system] SHALL [response]

例:

**ユーザーストーリー:** 新しいユーザーとして、個人用機能にアクセスできるように、アカウントを作成したいです。

**受け入れ基準:**
1. ユーザーが有効なメールアドレスとパスワードを入力した場合、システムは新しいアカウントを作成するものとします
2. ユーザーが既存のメールアドレスを入力した場合、システムは「メールアドレスは既に登録されています」というエラーを表示するものとします
3. ユーザーが 8 文字未満のパスワードを入力した場合、システムは「パスワードが短すぎます」というエラーを表示するものとします
4. アカウント作成が成功した場合、システムは確認メールを送信するものとします

フェーズ 2: 設計ドキュメント

目的: 実装のための包括的な技術計画を作成する

プロセス:

1. 技術的なアプローチと制約を調査する
2. システム アーキテクチャとコンポーネント間の相互作用を定義する
3. データ モデルとインターフェイスを指定する
4. エラー処理とテスト戦略を計画する

設計ドキュメント構造:

## 概要
[アプローチの高レベルの要約]

## アーキテクチャ
[システム コンポーネントとその関係]

## コンポーネントとインターフェイス
[詳細なコンポーネント記述]

## データモデル
[データ構造と検証ルール]

## エラーハンドリング
[エラーシナリオと応答戦略]

## テスト戦略
[異なるレイヤーのテスト アプローチ]

決定ドキュメント:

### 決定: [タイトル]
**コンテキスト:** [決定が必要な状況]
**検討されたオプション:**
1. [オプション 1] - メリット: [利点] / デメリット: [欠点]
2. [オプション 2] - メリット: [利点] / デメリット: [欠点]
**決定:** [選択されたオプション]
**根拠:** [この選択が行われた理由]

フェーズ 3: タスク計画

目的: 設計を実行可能で段階的な実装手順に分解する

プロセス:

1. 設計要素を特定のコーディング タスクに変換する
2. 段階的な進捗を可能にするようにタスクを順序付けする
3. 明確な目標と完了基準を定義する
4. 要件への追跡可能性のための参照を追加する

タスク構造:

- [ ] 1. [エピック/メインコンポーネント]
- [ ] 1.1 [具体的な実装タスク]
  - [実装の詳細]
  - [作成するファイル/コンポーネント]
  - _要件: [要件参照]_

タスク順序付け戦略:

• ファンデーション優先: 依存するコンポーネントの前にコア インターフェイス
• フィーチャー スライス: 早期検証のためのエンドツーエンド垂直スライス
• リスク優先: 不確実な領域を早期に取り組む
• ハイブリッド: プロジェクトのニーズに基づいてアプローチを組み合わせる

品質チェックリスト

要件チェックリスト

• すべてのユーザーロールが特定され対処されている
• 通常、エッジ、およびエラー ケースがカバーされている
• 要件はテスト可能で測定可能である
• 競合する要件がない
• EARS フォーマットが一貫して使用されている

設計チェックリスト

• すべての要件が設計で対処されている
• コンポーネントの責任が明確に定義されている
• コンポーネント間のインターフェイスが指定されている
• エラー処理が予想される障害に対応している
• セキュリティの考慮が対処されている

タスク チェックリスト

• すべての設計コンポーネントに実装タスクがある
• タスクが依存関係を尊重する順序で実行される
• 各タスクがテスト可能なコードを生成する
• 要件参照が含まれている
• スコープが適切である (各 2～4 時間)

AI ワークフローとの統合

Claude Code / AI アシスタント向け:

1. コンテキストから開始: プロジェクト背景、制約、および目標を提供する
2. フェーズごとに作業: 設計前に要件を完了し、タスク前に設計を完了する
3. 反復: 単一リクエストではなく会話を通じて出力を改善する
4. 検証: AI にチェックリストに対して出力をレビューするよう求める
5. 追跡: 要件、設計、およびタスク間のリンクを維持する

仕様の開始時のプロンプト例:

[プロジェクト コンテキスト] に取り組んでいます。[機能説明] を追加する必要があります。

コンテキスト:
- テクノロジー: [スタック]
- ユーザー: [対象ユーザー]
- 制約: [主要な制限事項]

ユーザー ストーリーと受け入れ基準から始めて、EARS フォーマットを使用して要件を開発するのを支援してください。

避けるべき一般的な落とし穴

1. フェーズをスキップする: 各フェーズは前のフェーズの上に構築されます。ショートカットは問題を作成します
2. 曖昧な要件: 「システムは高速である必要があります」対具体的で測定可能な基準
3. 要件での実装詳細: 実装方法ではなく、実装内容に焦点を当てます
4. 設計の過度な複雑化: 仮説的な将来の要件ではなく、現在の要件を解決する
5. モノリシック タスク: 2～4 時間単位に細分化する
6. エラー ケースの欠落: 問題が発生したときに何が起こるかを常に考慮してください

次のステップ

仕様の完成後:

1. タスク シーケンスに従って実装を開始する
2. タスク完了をマークして進捗を追跡する
3. 実装が隙を明らかにした場合は仕様を更新する
4. 完了した作業を要件に対して検証する
5. 将来の仕様のための学習を文書化する