目次
Spec Kit を入れてみて最初に戸惑ったのが、/specify を叩くと spec.md が、/plan で plan.md が、と次々にファイルが生えてくることでした。一個ずつ役割が違うらしいのは分かるのですが、では自分が手で書き足すとき何をどこに書けばいいのか、最初はまるで掴めませんでした。
仕様駆動開発(Spec-Driven Development)は、いきなりコードを書かずに「何を作るか」をドキュメントに固めてから AI コーディングエージェントに実装させる進め方です。Spec Kit と Kiro はどちらもこの考え方のツールで、用意する仕様書は大きく3種類に分かれます。中身がそれぞれ何のためにあるのかを、両ツールの実物に沿って整理します。
仕様書の種類は「何を / どう / 手順」の3層に分かれる
ツールによってファイル名は違いますが、仕様書の種類は本質的に同じ3層です。
| 層 | Kiro | Spec Kit | 書く中身 |
|---|---|---|---|
| 要求 | requirements.md |
spec.md |
何を作るか(WHAT / WHY) |
| 設計 | design.md |
plan.md |
どう作るか(HOW) |
| タスク | tasks.md |
tasks.md |
実装の手順を分解した作業リスト |
Kiro の Spec はこの3ファイルがそのまま並びます。Spec Kit は /specify(要求) → /plan(設計) → /tasks(タスク) → /implement(実装) という4段階のフローで、各コマンドが対応する Markdown を生成します。実装の手前までが仕様書で、最後の /implement だけがコードを書くフェーズ、という構造です。
順番が大事で、前の層の成果物が次の層の入力になります。要求が曖昧なまま設計に進むと設計が崩れ、設計が雑だとタスク分解が破綻します。だから1枚にまとめず、わざと3つに割って各層で立ち止まる作りになっています。
要求: 何を作るかをユーザー視点で書く
最初の1枚(Kiro の requirements.md / Spec Kit の spec.md)には、作るものを実装手段ではなくユーザーの視点で書きます。「どう実装するか」はここでは一切書きません。
Kiro の requirements.md はユーザーストーリーと受け入れ基準で構成され、受け入れ基準を EARS 形式で書くのが特徴です。EARS(Easy Approach to Requirements Syntax)は、自然な英語に近い決まった語順で要求を書く記法で、公式には5つのパターンがあります。
WHEN ユーザーがタスクカードを別の列にドラッグしたとき、
THE システム SHALL タスクのステータスを移動先の列に合わせて更新する
EARS のパターンを公式定義から引くと、それぞれのテンプレートはこうなっています[1]。
When
<trigger>, the<system name>shall<system response>
（イベント駆動: When 'mute' is selected, the laptop shall suppress all audio output.）
While
<precondition(s)>, the<system name>shall<system response>
（状態駆動: While there is no card in the ATM, the ATM shall display 'insert card to begin'.）
If
<trigger>, then the<system name>shall<system response>
（望ましくない動作: If an invalid credit card number is entered, then the website shall display 'please re-enter credit card details'.）
トリガーの有無や状態の前提を語順で明示するので、「どういう条件のとき何が起きるべきか」が曖昧にならないのが狙いです。日本語に直すなら、上の requirements.md のように「〜したとき、システムは〜する」のテンプレに当てはめて書くと、受け入れ基準として後でそのままテストの観点に落とせます。
Spec Kit の spec.md も同じ層ですが、もう一つ特徴的なのが [NEEDS CLARIFICATION] マーカーです。プロンプトで指定されなかった点を勝手に埋めず、不明な箇所にこのマーカーを残す方針になっています。
## ユーザーストーリー
- ユーザーとして、ログイン後にダッシュボードで未読通知を確認したい
## 受け入れ基準
- 未読通知が1件以上あるとき、バッジに件数を表示する
- 通知の保持期間は [NEEDS CLARIFICATION: 何日保持するか未定]
ここで AI に「だいたい30日くらいで」と推測で埋めさせないのがミソで、曖昧な要求を曖昧なまま下流に流さない歯止めになっています。自分は要求を書くとき、迷った箇所を無理に決め切らず、このマーカー相当のメモをまず残して、後で人に確認する運用にしています。決め切れないことを決め切れないと書けるのは、仕様書の弱点ではなく強みです。
設計: どう作るかを技術に翻訳する
要求が固まったら、次の1枚(Kiro の design.md / Spec Kit の plan.md)でそれを技術アーキテクチャに翻訳します。要求の「何を」を受けて「どう」に落とす層です。
Kiro の design.md には技術アーキテクチャ、コンポーネント設計、データモデル、シーケンス図、エラーハンドリング戦略を書きます。要求にあった受け入れ基準を、どのコンポーネントがどう満たすかをここで具体化していきます。
## アーキテクチャ
- 通知の取得は NotificationService に集約する
- 未読件数はクライアント側でキャッシュし、SSE で差分更新する
## データモデル
- Notification { id, userId, body, isRead, createdAt }
## エラーハンドリング
- SSE 切断時はポーリングにフォールバックする
Spec Kit の plan.md も技術翻訳の層ですが、こちらは設計の「正しさ」を担保する仕掛けが組み込まれています。データモデルや API 契約を別ファイル(data-model.md、contracts/、research.md)に切り出して plan.md から参照する構成になっており、さらに constitution.md という別の文書で定めたプロジェクト原則に沿っているかをチェックするゲートを通します。
constitution.md は3層とは別枠の、プロジェクト横断の不変ルールを書く文書です。Spec Kit のドキュメントには例として次のような条項が挙がっています。
Article I: Library-First Principle（機能は常に独立したライブラリから始まる）
Article III: Test-First Imperative（テストを実装より先に書く）
毎回の設計でこの憲法に照らして、過剰な複雑さを持ち込んでいないかを点検します。設計が個々のエンジニアの気分で揺れないように、上位のルールを固定しておく発想です。
タスク: 実装の手順を分解する
最後の tasks.md は両ツールで名前も役割も共通で、設計を実装可能な作業単位のチェックリストに割ります。
Kiro の tasks.md は、終了条件が明確で追跡できる離散的なタスクの並びです。Kiro はこのタスクリストの依存関係を解析して、独立したタスクを並行実行する機能を持っています。
Spec Kit の tasks.md も plan.md や data-model.md、contracts/ を入力にタスクを派生させ、互いに独立して並行実行できるタスクに [P] マークを付けます。
- [ ] T001 [P] Notification モデルを定義する
- [ ] T002 [P] NotificationService の取得APIを実装する
- [ ] T003 T002 完了後、未読バッジのコンポーネントを実装する
[P] が付いた T001 と T002 は依存がないので同時に着手でき、T003 は T002 を待つ、という読み方です。ここまで分解しておくと、AI エージェントに渡すコンテキストが「次に何をやるか」の単位で揃うので、一気に実装させても破綻しにくくなります。
3層に割る意味
3種類を並べてみると、要求(何を) → 設計(どう) → タスク(手順)と、抽象から具体へ一段ずつ降りていく流れになっているのが分かります。1枚のドキュメントに全部書くと、結局この境目が溶けて「何を作るはずだったか」が実装の都合に侵食されます。層を分けて各層で立ち止まるからこそ、AI に丸投げしても要求からブレずに実装まで届く、というのが仕様駆動開発で仕様書を3つに割る理由でした。
自分はまだ Spec Kit を触り始めたばかりで、[NEEDS CLARIFICATION] を残す癖と EARS で受け入れ基準を書く癖の2つから入れています。この2つだけでも、要求の詰めの甘さが設計に流れ込む事故はだいぶ減りました。
参考
EARS の各パターンとテンプレート文は公式ガイド Easy Approach to Requirements Syntax (EARS) より。 ↩︎