仕様駆動開発：AIに任せる前に仕様を書く
仕様駆動開発とは、作るものを先に書き出し、AIにそれに沿って作らせることです。この記事は、3つの段階、マーティン・ファウラーの分析によるKiro、Spec Kit、Tesslというツール、役に立つ場面と立たない場面、今日使える軽い5項目の仕様ひな形を説明します。
AIでコードを書くプログラマーと、製品に関わる人のための記事です。技術用語には短い説明を付けます。
3つの段階、3つのツール、限界の説明は、マーティン・ファウラーの分析（直接読みました）に拠ります。「軽い5項目の仕様」と例は私の提案で、多くのプロジェクトでは検証していません。「返金機能」の例は、イメージしやすいように作ったものです。
先に要点#
- **仕様駆動開発（SDD）**とは、作るものを先に書き出し、AIにそれに沿って作らせることです。
- マーティン・ファウラーは3つの段階を挙げます：spec-first（先に書き、後で捨ててもよい）、spec-anchored（仕様を残して保守に使う）、spec-as-source（仕様だけを直し、コードは生成物）。
- 今の取り組みの多くは、spec-firstだけです。
- 実際の限界があります：小さな作業にも重い手順、レビューしにくい繰り返しの多いファイル、エージェントが仕様を無視することがある。
- 実際的なやり方：中規模と大規模の作業に軽い5項目の仕様を使い、小さな作業では省く。
むずかしい言葉をやさしく#
| 用語 | やさしい意味 |
|---|---|
| 仕様（スペック） | 機能の望ましい振る舞いを、普通の言葉で構造立てて書いたもの。 |
| コーディングエージェント | 答えるだけでなく、ファイルを読んで直し、コマンドを実行して作業するAI。 |
| 受け入れ基準 | 機能が完成とみなされるために、真でなければならないこと。多くは具体的な例で書く。 |
| メモリバンク | すべての作業に当てはまる文脈ファイル。規則やプロジェクトの説明など。 |
| ブラウンフィールド | しばらく動いているプロジェクト。新品のものとは対照的。 |
| 非決定的 | 同じ入力でも、毎回少し違う結果になること。 |
1. なぜ仕様なのか#
短い一文でAIに頼むと、空白を自分で埋める権利を渡すことになります。小さな仕事なら問題ありません。大きな仕事では、空白はすべて推測で、間違ったと分かるのは結果を読んだときだけです。
このブログ自身の例：利用者が「検索が動かない」と報告したとき、エージェントは論理を確認して正しいと分かりましたが、本当の問題は、結果が最初の画面の下にあって、何も変わらないように見えたことでした（実際のプロジェクトでAIエージェントと働いた3時間を参照）。「入力したら、スクロールなしで結果が見える」という仕様の1行があれば、早く気づけたかもしれません。「かもしれない」と言うのは、これが後知恵の推論で、試験の結果ではないからです。
仕様駆動開発の考えは、そうした行を、AIが作業する前の正式な手順にすることです。
2. 3つの段階#
マーティン・ファウラーによると：
| 段階 | 意味 | 作業後の仕様 |
|---|---|---|
| Spec-first | 先に仕様を書き、それで作業を導く | 捨ててもよい |
| Spec-anchored | 仕様を残し、機能の発展と保守に使う | 残して更新する |
| Spec-as-source | 仕様が主な成果物で、人は仕様だけを直し、コードは直さない | 源であり、コードは生成される |
彼は、今のSDDの取り組みの多くはspec-firstにとどまり、仕様を長く保つ計画は、あいまいなことが多いと述べています。
また、仕様をメモリバンクと区別します：メモリバンク（規則、製品とコードの説明）はすべての作業に当てはまり、仕様は、作っている、または変えている機能だけに当てはまります。だからAGENTS.mdのようなファイル（AI向けの手引きを参照）と仕様は、補い合います。
3. 3つのツール（ファウラーの記事による）#
ファウラーは3つのツールを検討しています。以下の説明は私の要約です。
| ツール | 手順 | ファウラーの注記 |
|---|---|---|
| Kiro | 要件、設計、タスク。「ステアリング」機能がメモリバンクの役割 | 軽めで、主にspec-first |
| Spec Kit（GitHub） | 原則、仕様、計画、タスク、そして実装。各段階でMarkdownファイルを作る | GitHubはspec-anchoredを目指すが、ファウラーは仕様ごとにブランチを作るのでspec-firstと見る |
| Tessl（非公開ベータ） | 明確にspec-anchoredを目指し、spec-as-sourceを試す。生成ファイルは編集不可と印が付く | ファウラーは、同じ仕様から非決定的な出力を見た |
これらのツールは新しく、速く変わるので、上の説明を最終版と思わないでください。
4. ファウラーの観察と批評#
私が最も読む価値があると思うのは、ファウラーが称賛だけをしていないことです。彼は次を指摘します：
- どんな大きさにも同じ手順。 Kiroは、小さなバグを4つのユーザーストーリーと16の受け入れ基準に変えました。Spec Kitは、既存のコードの中規模の機能には大げさで、AIで直接書くほうが速く、制御しやすかったでしょう。
- レビューの負担。 Spec Kitは、繰り返しが多く冗長なMarkdownファイルをたくさん生み、レビューが疲れます。彼はコードのレビューのほうがよいと言います。
- 偽りの制御感。 エージェントは、仕様の内容を無視することがあります。調査の段階で記録されていたのに、すでにあるクラスを作り直したり、共通の原則を過剰に適用したりします。
- 既存のコードは難しい。 3つのうち2つは、動いているプロジェクトに導入しにくく、評価しにくい。
- 機能と技術の境目は不明確です。
- 「スペック」が緩く使われています。 この言葉は、「詳しいプロンプト」の同義語になる危険があります。
- モデル駆動開発（MDD）の教訓。 MDDは業務アプリではうまくいきませんでした。ファウラーは、spec-as-sourceがMDDの硬直さと言語モデルの非決定性の両方を引き継ぐことを心配しています。
それでも彼は、spec-first的な考え方には価値があると見ています：エージェントに頼む前に仕様を丁寧に書くと、役立つことが多い。彼が疑うのは、重くてファイルの多い手順です。
5. 役立つ場面、立たない場面#
この表は、ファウラーの言葉と私自身の推論に基づきます。
| 場面 | 仕様 | なぜ |
|---|---|---|
| 小さなバグの修正 | 要らない | 仕様を書く手間が、作業よりずっと大きい |
| 既存コードの中規模の変更 | 軽く、または無し | 多くの文書のレビューが、AIで直接書くより高くつくかもしれない |
| 新しい中規模から大規模の機能 | 要る、軽く | AIが推測する空白が多いので、先に固める |
| リスクの高い変更（お金、権限、個人情報） | 要る、明確な受け入れ基準つき | 起きてはいけないことを書く必要がある |
| 大きくてあいまいな問題 | まだ、先に利用者を知る | 仕様は、問題の理解の代わりにならない |
| 小さな段階で制御したい作業 | 少なめ、一歩ずつ | 大きな仕様は、小さく繰り返す進め方に逆らうことがある |
6. 軽い5項目の仕様ひな形#
私の提案で、どのツールの標準でもありません。 短いファイル1つ、1ページ、コードのそばに。
- なぜ。 問題と利用者について1、2文。解決策ではなく。
- 望ましい振る舞い。 利用者が見て、することを、普通の文で。
- やらないこと。 意図的に範囲外としたもの。この項目が、AIの「余計なこと」を止めます。
- 受け入れられる例。 3〜6個の具体例：入力、期待する結果、変わったケース（空、非常に長い、型違い）も含めて。
- 未解決の問い。 まだ分からないこと。AIに推測させず、聞き返させる。
例（作り直したもの）：返金機能。
- なぜ： 注文をキャンセルする顧客が、サポートに電話せずにお金を取り戻したい。
- 振る舞い： 注文ページで、未配送の注文に「キャンセルして返金」ボタンがある。押すと、顧客に「返金中」の状態が見え、メールが届く。
- やらないこと： 一部返金、配送済みの注文、別の支払い方法への切り替え。
- 受け入れられる例： 未配送で20万、全額返金。配送済みの注文：ボタンは出ない。2回続けて押す：返金は1回だけ。決済ゲートウェイのエラー：メッセージが出て、注文の状態は変わらない。
- 未解決の問い： カードの期限が切れていたら、どこへ返金するか？ 100万を超えたら誰が承認するか？
真ん中の受け入れられる例は、まさにテストが従えるもので、レビューする人が照らし合わせるものです。AIが書いたコードのレビューのチェックリストにもつながります：項目1（依頼と一致）と項目9（テストは何を確かめるか）。
7. 今日使える4段階の手順#
- 軽い仕様を書く（10〜20分ほど）。AIにあいまいな部分を問い返させますが、決めるのはあなたです。
- 仕様から、AIに短い計画を作らせ、作業させる前に計画を読む。
- 小さな段階で進める。 1段階に小さな変更を1つ、動かして、受け入れられる例と照らし合わせる。
- 仕様を更新するか、捨てる。 機能が長く生きるなら、振る舞いが変わるときに仕様を更新する。そうでないなら、古くならないよう消す。
3と4は、ファウラーの懸念に合います：段階を小さく保ち、仕様も古くなりうると覚えておく。
8. バランスの取れた見方#
- 根拠の多くは、1人の分析です。 ファウラーは、いくつかの作業でツールを試したので、大きな調査ではありません。SDDの効果を測った独立した研究は、見ていません。
- ツールは速く変わります。 Kiro、Spec Kit、Tesslの説明は、あなたが読むころには変わっているかもしれません。二次的な情報源は、公開日や利用の数字も食い違うので、引用しません。
- 「スペック」は複数の意味を持ちます。 仕様を、長いプロンプトや設計書と混同しないでください。
- 仕様は、利用者の理解の代わりになりません。 何をするかを固める助けになりますが、何をする価値があるかを見つける助けにはなりません。
- 5項目のひな形は私の提案で、多くのチームでは検証していません。
9. 結論#
先に仕様を書くことは、それ自体のための新しい儀式ではありません。それは、AIが自分で埋めてしまう空白を固める方法です。けれど、ファウラーが念を押すように、小さな仕事に大槌を使わないでください：軽い仕様、いくつかの受け入れられる例、小さな段階で、たいてい足ります。
今日の小さな一歩：今週AIに作らせるつもりの機能を1つ選び、上の5項目を10分で書き、結果を、いつものやり方と比べてください。
参考資料#
よくある質問
- 仕様駆動開発とは何ですか
- 先に仕様、つまり機能の望ましい振る舞いを構造立てて記述し、AIのコーディングエージェントにそれに基づいて作らせることです。長いプロンプトの代わりに、仕様が人にもAIにも正しさの拠り所になります。この言葉の意味は、まだ揺れています。
- 仕様とAGENTS.mdはどう違いますか
- AGENTS.mdのような共通の文脈ファイルは、すべての作業のための記憶で、規約、コマンド、構成などです。仕様は、特定の1つの機能や変更だけに当てはまります。両者は補い合います。
- 仕様駆動開発が割に合わないのはいつですか
- マーティン・ファウラーの分析によると、バグ修正のような小さな作業、既存のコードで中規模の変更をするとき（生成された文書のレビューが、直接書くより高くつく場合）、または問題が大きくあいまいで、仕様より製品のスキルが要るときです。冗長な仕様は、レビューの負担も増やします。
- Spec KitやKiroのようなツールは要りますか
- 必須ではありません。核心は、AIに頼む前に、やること、やらないこと、受け入れられる例を書く習慣です。リポジトリの中の軽い仕様ファイルで始めるには十分で、ツールは手順とファイルを増やすだけです。