この記事はAIと壁打ちしながら人間が書きました。
流行りの仕様駆動開発、とっつきづらく感じませんか？
サービスデザイナーという肩書きで仕事している非エンジニアの僕には、正直ちょっと難しいと感じてました。
理解を深めるために個人で仕様駆動開発にトライしてみたのですが、最初にSpecKitやcc-sddなどの有名なフレームワークを調べてみて、気が重くなりました。
フレームワークの違いやメリデメがイマイチよくわからないし、
Git操作が前提になっている時点でちょっと腰が引けちゃうし、
Skillとか覚えることも多そうだし...（使いこなせたら便利そうなことだけはわかる）
違うでしょと。
僕は、仕様駆動開発は経験したいけど、別にフレームワークに詳しくなりたいわけではないんですよ。
そこで、 非エンジニアの自分向け・個人開発レベルの複雑さ向けに簡略化した仕様駆動開発 をやってみました。
この記事では、僕がやってみた方法をご紹介したいと思います。
僕と同じように尻込みしている方を勇気づけられたら嬉しいです。
なお、アプリ開発自体の話は別記事にまとめているので、気になる方は合わせて読んでいただけたら嬉しいです
気楽に始める、家庭料理のような仕様駆動開発
今回試したやり方を例えるなら 「家庭料理のような仕様駆動開発」 です。
AI駆動での開発プロセスを複雑さの1軸で比較してみます。
一番シンプルなのがバイブコーディング、一番複雑なのがSpecKitなどの既存フレームワーク、そして今回のやり方はその中間です。
これを料理に（強引に）置き換えて考えます。
既存フレームワークでの開発は、いわばレストランが出す料理です。 大火力のコンロや鉄製の大きい中華鍋、聞いたことのないスパイスを揃え、レシピにこだわり、様々な管理基準のもと作られた料理です。お金を取るに値する美味しさで、いつも同じ味になることが期待されます。
でも、料理初心者からすると大変すぎて「いきなりそこまでできないよ」っていうレベルです。
一方、バイブコーディングは、いわば一人で食べるズボラ飯です。 タッパーに具材を全部入れてレンチンするようなやつ。手軽ですが、再現性には欠けますし、複雑な料理は作れません。誰かに食べてもらうのもちょっと気が引けますね。
やりたいのはその中間にある家庭料理です。
フライパンと家庭用のコンロでOK。調味料は目分量。困ったらカレー粉で味付け。それでも家族に食べてもらえる程度のクオリティは狙いたい。
そのくらいの手軽さと品質のバランスを、仕様駆動開発で狙いました。
ドキュメント構成とその狙い
なるべくシンプルな構成にしながら、「仕様駆動開発の本質」が損なわれないようにするのを意識していました。
そこで考えたのが次の3点です
- セッションを跨いでもコンテキストを保てる
- 実装の前に、仕様でレビューできる
- 仕様書が参照すべき正しい情報となっており、開発の軸になる
逆に削ったのは、厳密なドキュメントのフォーマットやコマンド（スキル）です。
ただのMarkdownファイルとフォルダだけで代替しました。
具体的には、次の5つのドキュメント構成にしました。
- PLAN.md：要求や要望をラフに書き溜める
- SPEC.md：要求を元に、実装する仕様を記載する
- TODO.md：実装タスクの進捗を管理する
- KNOWLEDGE.md：調査結果やトラブルシュートをまとめる
- DISCUSSIONS.md：仕様などの検討経緯や結論背景を残す
各ドキュメントとも、実際には内容ごとに複数ファイルに分かれています。
各ドキュメントのご紹介
PLAN.md
思いついたことを言葉にして、AIとの壁打ちの起点にする。それだけの役割です。
僕の場合は、作りたいアプリの概要や想定ユーザー、機能案などをひたすら10分くらい音声入力させて、その内容をよしなに整理させてます。
整理の際「PRDとして整理して。その上で、不明点があったら質問してね」
と、AIに指示すると思考の盲点を突いてくれるのでおすすめです。
SPEC.md
PLAN.mdで考えた方針を、AIとの壁打ちを経て固めた仕様書です。
今回は機能単位でファイルを分け、features/ ui/ data/ api/ infra/ というサブフォルダに整理しました。また、README.mdに、仕様書1本あたりのテンプレートも置いています。
これは infra/ に入れたアーキテクチャの仕様サンプルです。
このアーキテクチャ構成や、features/ の仕様は割と抽象度が高く、ui/ data/ api/などはより細かく記載されています。この辺の書きっぷりのバランスはAIにお任せしています。
仕様書は、必ずしもPLAN.mdから一発生成したわけではありませんでした。
適宜バイブコーディングしてアプリを触りながら、フィードバックを繰り返して出来上がった実装を最終仕様に落とし込む場面もしばしば。
TODO.md
仕様を実装するためのtodoです。箇条書きレベルですが、やってる内容はプロダクトバックログに近いです。
仕様書をもとに「TODOを更新して！」とお願いするだけです。
CLAUDE.mdに「実装したら必ずtodoを更新してください」と書いておくことで、todoと実装とのズレを防ぎました。
KNOWLEDGE.md
実装方針を決めるために調べたことや、ハマったトラブルをその都度記録していく場所です。
例えば今回、Playwright MCPでテスト工程を自動化していたのですが、Playwirghtでのテスト結果と僕の手動でのテスト結果の整合が取れないシーンが発生しました。
その時の調査結果を残して、再発しないようにしています。
バグ修正や調査タスクをお願いしたら、必ず「ナレッジに足しといてね」と依頼するようにして進めました。
DISCUSSIONS.md
主にSPEC.mdを固める過程で生じる副産物です。
「どんな選択肢から何を決め手にして仕様を固めたのか」あるいは「AIの提案に対して人間（僕）がリジェクトしたものは何でその理由は」といった内容をメモしていきます。
AIが実装に着手する前に、仕様とセットで確認してもらうことでセッションを跨いでもコンテキストを追えるようにしています。
また、内容は割愛しますが、設計したサービス構成に対してセキュリティレビューを行った結果レポートなどもディスカッション（要は議事録）として保存しました。
AIと仕様を壁打ちした結果に対して、
「結論はSPEC.md」に、「背景はDISCUSSIONS.md」に記載して、かつ、相互にリンクを貼るよう指示するのがおすすめです
やってみた感想：自分のやりやすい形を育てる
商用開発やチーム開発ではSpecKitのような有名なフレームワークを採用するのが合理的な選択だと思います。安定品質や再現性が必要な場面において、これらフレームワークの磨き込まれた手厚さが価値になると感じます。
一方で、個人で仕様駆動開発を初めて試すという場面では、今回のようなシンプルな構成だとゼロから一歩ずつ学べる価値がある と感じました。
このシンプル構成で試す過程で「もっとこうした方が使いやすい」という気づきが生まれてきました。
その後で既存フレームワークの説明を改めて読んでみると、「僕がやろうとしていたことが形になっている...!!」と腑に落ちる感覚がありました。
順番として、まず自分の手でシンプルに触ってみて、理解が深まった状態で有名フレームワークに手を出す、というのは悪くないやり方だと思います。
また、フレームワークに手を出さなくても、自分なりにやりやすい形を徐々に見つけて、それを再現するスキルを組むのも良いと思います。
僕の場合はこんな感じにしてあります。
(本記事の説明に加えて、参考文献置き場やプロジェクト概要資料などを足しています。)
最後まで読んでいただきありがとうございました！
肩肘張らない家庭料理のようなスタイルで、気楽に仕様駆動開発デビューしていきましょう！