こんにちは、サーバーワークスで生成AIの活用推進を担当している針生です。
今回は GitHub が公開している Spec Kit の /specify コマンドで出力される仕様書の詳細とレビュー方法について解説したいと思います。
Spec Kit を使い始めたものの、「/specify コマンドで出力される spec.md ってどんなルールで生成されてるの？」「出力された仕様書はどうレビューすればいいの？」と気になっている方も多いのではないでしょうか。
Spec Kit についての情報は、サーバーワークスエンジニアブログの Spec Kit に関する関連情報も参考にしてください。
Spec Kit のワークフローをおさらい
まずは Spec Kit のワークフローを簡単におさらいしておきましょう。
ワークフローは5つのフェーズに分かれていて、それぞれに対応するコマンドがあります。
/constitution→ プロジェクトの原則を定義/specify→ 仕様書を作成/plan→ 技術的な実装計画を作成/tasks→ タスクに分解/implement→ 実装を実行
/specify コマンドの出力内容
/specify を実行すると、AI エージェントが spec.md ファイルを生成します。このファイルには「何を作るか」「なぜ作るか」が記述され、「どうやって作るか」は含まれません。
生成されるファイルの構造
.specify/
└─ specs/
└─ 001-feature-name/
├─ spec.md # メインの仕様書
└─ checklists/
└─ requirement.md
spec.md の主なセクション
| セクション | 内容 |
|---|---|
| User Scenarios & Testing | ユーザーシナリオ（Given/When/Then 形式の受け入れ基準） |
| Edge Cases | エッジケースや例外的な状況の定義 |
| Requirements | 機能要件（FR-001 形式で番号付け） |
| Key Entities | システムで扱うデータの概念的な構造 |
| Success Criteria | 測定可能な成功指標（SC-001 形式） |
| Assumptions | 前提条件 |
| Out of Scope | スコープ外の機能 |
それぞれのセクションを詳しく見ていきましょう。
User Scenarios & Testing（ユーザーシナリオ）
ユーザー視点でのシナリオを Given/When/Then 形式で記述します。
Given/When/Then 形式とは、BDD（Behavior-Driven Development：振る舞い駆動開発）で広く使われるシナリオ記述のフォーマットです。
- Given（前提条件）: テスト開始時のシステムやユーザーの状態
- When（操作）: ユーザーが行うアクション
- Then（期待結果）: アクションの結果として期待される状態や動作
「商品を販売するサイトを構築したい」というリクエストで、実際に生成された例を見てみましょう。
### User Story 1 - 商品を閲覧する (Priority: P1) 顧客がサイトを訪問し、販売されている商品を一覧で閲覧し、 興味のある商品の詳細情報を確認できる。 **Why this priority**: 商品を見ることができなければ購入も発生しない。 サイトの最も基本的な機能であり、これだけでも商品カタログとしての 価値を提供できる。 **Independent Test**: 商品一覧ページにアクセスし、商品の画像・名前・価格が 表示され、クリックして詳細ページで説明文を確認できることをテスト。 **Acceptance Scenarios**: 1. **Given** 顧客がサイトにアクセスした状態, **When** 商品一覧ページを開く, **Then** 登録されている商品が画像・名前・価格とともに一覧表示される 2. **Given** 商品一覧が表示されている状態, **When** 任意の商品をクリック, **Then** 商品詳細ページに遷移し、商品画像・名前・価格・説明文・在庫状況が 表示される 3. **Given** 商品が多数登録されている状態, **When** 商品一覧ページを開く, **Then** ページネーションにより適切な数ずつ商品が表示される
各ユーザーストーリーには以下の要素が含まれます。
- Priority（優先度）: P1/P2/P3/P4 などの優先度ラベル
- Why this priority: なぜその優先度なのかの説明
- Independent Test: 独立してテストできることの確認
- Acceptance Scenarios: Given/When/Then 形式の受け入れ基準
この形式で書くことで、受け入れ基準が明確になり、テストケースへの変換も容易になります。
Edge Cases（エッジケース）
例外的な状況や境界条件を定義します。
### Edge Cases - 在庫切れの商品を購入しようとした場合、どのように対応するか？ → カートに追加不可とし、商品詳細ページで「在庫切れ」と表示する - カートに商品を入れた後、別の顧客が同じ商品を購入して在庫がなくなった場合は？ → 購入手続き時に在庫を再確認し、不足があれば通知する - 購入手続き中にセッションが切れた場合は？ → カート情報は一定期間保持し、再度ログインまたはアクセス時に復元を試みる - 支払い処理が途中で失敗した場合は？ → エラーメッセージを表示し、再試行を促す。注文は確定しない
エッジケースを事前に洗い出すことで、実装漏れを防げます。
Functional Requirements（機能要件）
機能要件は FR-001 形式で番号付けされます。
### Functional Requirements - **FR-001**: システムは商品一覧ページで、商品の画像・名前・価格を 表示できなければならない - **FR-002**: システムは商品詳細ページで、商品の画像・名前・価格・説明文・ 在庫状況を表示できなければならない - **FR-003**: 顧客は商品をカートに追加できなければならない - **FR-004**: 顧客はカート内の商品の数量を変更できなければならない - **FR-005**: 顧客はカートから商品を削除できなければならない - **FR-006**: システムはカートの合計金額をリアルタイムで 計算・表示しなければならない
番号付けにより、後続の plan.md や tasks.md で要件をトレースしやすくなります。
Key Entities（主要エンティティ）
システムで扱うデータの概念的な構造を定義します。
### Key Entities - **商品（Product）**: 販売される品目。名前、説明、価格、画像、カテゴリ、 在庫数を持つ - **カテゴリ（Category）**: 商品の分類。名前と所属する商品のリストを持つ - **カート（Cart）**: 顧客の購入予定商品を一時的に保持する。 カート項目のリストを持つ - **カート項目（Cart Item）**: カート内の個別商品と数量の組み合わせ - **注文（Order）**: 確定した購入情報。配送先、支払い方法、注文商品、 合計金額、注文日時、ステータスを持つ - **顧客（Customer）**: 購入者。氏名、メールアドレス、配送先住所、電話番号を持つ
Success Criteria（成功指標）
測定可能で技術に依存しない成功指標を SC-001 形式で定義します。
### Measurable Outcomes - **SC-001**: 顧客が商品一覧から商品詳細ページに遷移するまで3秒以内に 完了できる - **SC-002**: 顧客がカートに商品を追加してから購入完了まで5分以内に 完了できる - **SC-003**: 初めて訪問した顧客の80%以上が、商品一覧から目的の商品を 30秒以内に見つけられる - **SC-004**: 注文確定後1分以内に確認メールが顧客に届く - **SC-005**: カートに追加した顧客のうち、60%以上が購入完了まで到達する （カート放棄率40%以下） - **SC-006**: 100件以上の商品が登録されていても、商品一覧ページの表示が 3秒以内に完了する
「スムーズに」「快適に」といった曖昧な表現ではなく、数値で測定できる形にすることがポイントです。
Assumptions（前提条件）
仕様の前提となる条件を明記します。
## Assumptions - 物理商品のみを扱う（配送が必要、デジタル商品は対象外） - ゲスト購入を許可する（会員登録なしで購入可能） - 支払い方法は一般的なオンライン決済手段を想定 - 日本国内向けサービスとして、日本語・日本円のみ対応 - 管理者向けの商品登録・注文管理機能は別途検討が必要 - SSL/TLSによる通信の暗号化は前提とする
Out of Scope（スコープ外）
今回の実装に含めない機能を明確にします。
## Out of Scope - サブスクリプション（定期購入）モデル - 複数販売者のマーケットプレイス機能 - アフィリエイトプログラム - クーポン・割引コード機能 - 多言語対応 - 複数通貨対応
スコープ外を明記することで、機能の肥大化を防ぎ、実装の焦点を明確にできます。
レビューのベストプラクティス
さて、ここからが本題です。生成された仕様書はどうレビューすればいいのでしょうか？
1. /clarify コマンドで曖昧な点を解消する
/specify の直後に /clarify を実行することを強くおすすめします！
このコマンドを実行すると、仕様の曖昧な部分が自動的に特定されて、構造化された質問が提示されます。
質問に回答すると、仕様書が自動的に更新されます。
2. 「テスターの視点」でレビューする
Spec Kit のテンプレートには「テスターのように考えろ」という指針があります。曖昧な要件は「テスト可能で曖昧でない」というチェック項目で不合格となるべき、という考え方ですね。
レビュー時には以下を自問してみてください。
- この要件は具体的なテストケースに変換できるか？
- 複数の解釈が可能な表現はないか？
- 数値や条件が明確に定義されているか？
「ユーザーがスムーズにログインできる」よりも「ユーザーが30秒以内にログインを完了できる」の方が、明確にテスト可能です。
3. 最初の出力を最終版として扱わない
これは重要なポイントです。
AI との対話を、仕様を明確化し質問する機会として活用しましょう。最初の出力をそのまま受け入れるのではなく、積極的に質問や修正を行うことで、より良い仕様書ができあがります。
仕様ファイルは Markdown なので、手動で編集することもできます。
4. 実装詳細の混入を防ぐ
仕様書（spec.md）には「What（何を）」と「Why（なぜ）」のみを含め、「How（どうやって）」は /plan フェーズまで持ち越します。
ただ、気をつけないと実装詳細が混入することがあります。たとえば、要素のサイズや色、特定のライブラリ名などが紛れ込んでいないか確認してください。
こうした分離を保つことで、技術的な選択が変わっても仕様書は安定したまま維持できます。
5. 仕様が不十分なまま次のフェーズに進まない
これは Spec Kit を使う上で最も重要な原則かもしれません。
悪い仕様は、悪い計画となり、悪いコードになります。
仕様に曖昧な点や不足があるまま /plan フェーズに進むと、その問題は増幅されて実装まで引き継がれます。手戻りのコストは後になるほど大きくなるため、仕様の段階で徹底的にレビューし、問題を解消しておくことが重要です。
推奨ワークフロー
最後に、推奨ワークフローをまとめておきます。
1. /specify を実行 ↓ spec.md が生成される ↓ 2. spec.md をレビュー ↓ 3. /clarify を実行 ↓ 4. 必要に応じてAIと対話しながら修正・追記 ↓ 5. /plan に進む
まとめ
- spec.md は「何を」「なぜ」に焦点を当て、「どうやって」は含まない
/clarifyコマンドで曖昧さを解消できる- 最初の出力を最終版として扱わず、積極的に対話する
- 仕様が不十分なまま次のフェーズに進まない（悪い仕様 → 悪い計画 → 悪いコード）
Spec Kit を使っていて感じているのは、AI に「よしなにやって」とお願いするのではなく、仕様という形で意図を明確に伝えることの大切さです。最初は面倒に感じるかもしれませんが、結果的に手戻りが減り、期待通りのものができあがる確率が格段に上がります。
ぜひ皆さんも試してみてください！
針生 泰有(執筆記事の一覧)
サーバーワークスで生成AIの活用推進を担当
