はじめに
仕様書を正本にした瞬間、最初に壊れたのはコードではなく、自分の勘でした。2025年9月に Kiro と Cursor で仕様駆動開発を試し、色彩学習アプリ Colorism の v1 を出したときは、「設計書があればブレない」と思っていました。半年後の v2 では、プロジェクト内のドキュメント一式を唯一の正本にし、決定や不具合にも番号を振って残すまで来ました。それでも、毎週のように「これは仕様が古いのか、自分の感覚が古いのか」で立ち止まりました。
この記事は、仕様駆動開発のやり方そのものを説明するものではありません。進め方は Kiro×Cursor の記事、プロジェクトの中身は Colorism v2 の開発記 に任せます。ここで書くのは、そのあいだで自分の中で起きたこと──判断の所在がどう動いたか、です。
先に用語：この記事で出てくる番号と略語
v2 では、チャットの記憶に頼らず、ドキュメントで文脈を引き継ぐために次のような付番を使いました。以降の「D番号」「IR番号」はこの意味です。
- docs（ドキュメント）を正本にする
チャットや口頭の合意は、ドキュメントに書かれるまで「まだ決まっていない」と扱う。実装も AI への指示も、この正本を読む。 - D番号（例: D1, D15）
意思決定の通し番号。決定ログ（decisions.md）に「何を決めたか・なぜ・何を捨てたか」を短い ADR 形式で残す。 - ADR（Architecture Decision Record）
アーキテクチャ上の決定を1件ずつ記録する書き方の型。長い設計書を全部読み直さなくても、「あのときなぜそうしたか」を番号で辿れる。 - IR番号（例: IR-005, IR-011）
Issue Resolution の通し番号。不具合や手戻りを時系列ログに残す付番。現象・原因・対策・再発防止を1件にまとめる。 - Phase / 出口条件
開発を段階に分け、次の段階へ進む前に「満たすべき条件」を先に書いておく。動いただけで次に進まないための柵。
番号そのものに魔法はありません。効いたのは、「同じ議論を繰り返さない」「別のチャットでも続きから話せる」ようにしたことです。
なぜドキュメントを正本にしようと思ったか
v1 の Colorism は、見た目はかなり賑やかでした。6色を選ぶとヒーロー画像が変わる体験、色相環、色彩心理のインタラクティブ UI。一方で触っていて「学習アプリとしては薄い」と感じる場面が続きました。コンテンツが UI の付属物になっていたり、データの定義と画面のハードコードが二重管理になっていたり。
Kiro で起こした要件・設計・実装計画は、Cursor に引き継いだあとも増え続けました。ただ、どのファイルが最新かは曖昧でした。チャットをまたいで「さっきの仕様どおりで」と言っても、エージェントが参照する文脈は毎回少しずつ違う。v2 を作り直すとき、最初に決めたのは「プロジェクト内のドキュメントだけを信じる」というルールでした。チャットログや口頭の合意は、ドキュメントに書かれるまで存在しない、と割り切った方が楽だと感じていました。
正本にしたのは、仕様駆動を厳密に守るためではなく、議論の再発を減らすためだった。
正本にした最初の1週間で起きたこと
基盤フェーズの出口条件を書いた直後、Cursor に実装を任せ始めました。最初は気持ちよかったです。決定ログに D1、D2…と ADR を足していく。実装計画書のチェックボックスが埋まっていく。ここまでは、昔の SI 案件で設計書を回していた感覚に近い。
違和感が出たのは、エージェントが「仕様に沿っています」と言いながら、自分の頭の中の Colorism 像とズレているときでした。例えば、ホーム画面に大型の色相環を常設する案。v1 でもやっていたので自然に思えたのですが、v2 の方針では「まず学ぶ（Learn first）」「説明の直後に見せる（Show, then tell）」と書いてあり、図解は各レッスンの中に閉じることにしていました。仕様書は正しい。古いのは自分の感覚の方だった。
この週で気づいたのは、ドキュメントを正本にすると「自分の勘を疑う」方向に引っ張られる、ということです。悪いことばかりではありません。v1 では「とりあえず動くからこのまま」で進んでいた部分を、仕様が止めてくれました。ただ、全部を仕様に委ねると、プロダクトの温度感が下がる瞬間もありました。
判断ログ（3件）
ここからは、実際にメモした判断の断片です。日付は開発ログ上のもので、時系列に並べています。最初の1件は v1（正本化の前）、あとの2件は v2 です。
2025-08-22（v1・正本化の前）─ AI エディタの利用枠が先に尽きてしまった
Kiro では、仕様どおりに UI の一貫性を取るのが難しく、課金体系上の Specs / Vibe という利用枠の消費も異常に速かった。仕様書は増えているのに、動く画面は増えない。ここは仕様の是非ではなく、当時のツールとフェーズの相性の問題だと判断し、Cursor に引き継いだ（v1 記事の「紆余曲折」）。引き継ぎ後もドキュメントは残したが、「どの節がまだ実装と一致していないか」を自分でマーキングし始めた。
2026-05-18（v2）─ 「レッスンに表を載せる」と書いてあったのに、画面では表にならなかった
レッスン原稿を Markdown の表形式で書き始めたら、記事を HTML に変換する処理側に表対応の設定が入っていないことに気づいた（のちに不具合ログ IR-014 として記録）。仕様は正しかった。実装が遅れていた。ここで「仕様が間違っている」とは言えず、「仕様の前提がまだコードに反映されていない」と決定ログに書き足した。教訓は、コンテンツの仕様を書く前に、表示パイプラインを1本だけ通しておくこと。
2026-05-28（v2）─ 「紫のヒーロー画像」は満たしていたが、城やバイクが出てきた（IR-005）
仕様も実装も「紫のヒーロー画像を出す」は満たしていた。外部の画像検索 API に渡す英語キーワードが「Royal Purple」だったため、城やバイクの写真が返ってきた。キーワードの選び方は仕様に書いていなかった。ここはドキュメントを上書きし、検索語を単純な Purple に変え、キャッシュの残り方とページのランダム性も直した。正本を守るとは、間違った正本を直すことも含む、とそのとき初めて腹落ちした。
実装の進め方で変わったこと
v1 では「実装して」と投げることが多かったです。v2 では、投げる前に「どのドキュメントのどの節を読んで、完了したらどの節を更新するか」まで書くようにしました。手戻りは減った印象です。代わりに、人間側の作業は「差分のレビュー」から「ドキュメントとコードの矛盾検知」に寄りました。
不具合は、不具合ログに IR-001 から順に残します。たとえば開発中に、画面の状態管理の書き方が原因で再レンダーが無限に回り、開発用のビルドツールが暴走してマシンが重くなった件（IR-011 / IR-012）──局所は直るのに全体が崩れるパターンは v1 と同型でした。違うのは、「React のフック層なのか、ビルドツールなのか、コンテンツ変換なのか」と層ごとに分解して書いたこと。次のチャットでは「IR-011 を見て」と言えるので、長い経緯の貼り付けが要らなくなります。
| v1 の頃 | ドキュメント正本化のあと |
|---|---|
| チャットの文脈が正本になりがち | プロジェクト内のドキュメントと決定ログが正本 |
| 「動いたから次へ」 | Phase の出口条件を満たすまで次へ進まない |
| 同じ議論の繰り返し | D番号で一度決めたら戻らない |
| エージェントの自己レビュー | 別タスクの検証（軽い自動テストやチェック用スクリプト） |
| 口頭の「こういう感じ」 | 機能対応表に「なぜ捨てたか」列を足す |
自分の判断が変わったこと
大きく言うと、役割が「決める人」から「矛盾を見つける人」に寄りました。仕様駆動をやっていると、自分は設計者のように感じがちです。実際には、設計はドキュメントに書かれていて、自分はそのドキュメントと実装・コンテンツのあいだを行き来する編集者に近い。
たとえば v2 で、バッジやポイントのようなゲーミフィケーションを見送った判断があります。機能対応表に理由を書きました。AI には「バッジを付けましょう」と提案されがちです。方針の「まず学ぶ」と照らすと、学習の深さを優先する方がプロダクトの芯に合う。こういうのは、仕様書が代わりに決めてくれるというより、仕様書を根拠に「やらない」と言いやすくなる、に近いです。
個人的には、エージェントにコードを書かせる前にドキュメントを1段落更新するクセが、いちばん効いたと感じています。見た目や振る舞いがそろう鍵は、生成物そのものより、正本ドキュメントと Phase の境界にある──というのは v2 を通して強く思いました（Colorism v2 の開発記でも同じことを書いていますが、ここでは判断の話として切り出しています）。
それでも自分でしか決められなかったこと
仕様駆動にすると、全部が文書化できる錯覚に陥ります。v2 でも、次のようなものは最後まで人間の判断でした。
- レッスンの説明が「足りない」と感じるかどうか（自動の品質スコアは補助にしかならない）
- ヒーロー画像が「その色らしい」と感じるか（API は紫を返しても、城の写真は却下）
- v1 ユーザーのブックマークを救うか、機能ごとに潔く捨てるか（古い URL を新しい画面へ転送する範囲と、テストの線引き）
- AI の出力が「だいたい合っている」ときに、どこまでレビューを省略するか
ここを仕様書に書こうとすると、かえって嘘になる。「良い UX」や「十分な説明」は、プロジェクトの途中で基準が上がります。ドキュメントはそのとき更新すればいいのですが、更新するかどうかのトリガーは、結局、自分の違和感です。
2025年9月の Kiro×Cursor 記事で書いた「よく分かる気がします。一貫性や品質を確保するうえで AI に任せきりは難しい」という所感は、v2 でも変わりませんでした。変わったのは、任せきりにしないための仕組み──正本ドキュメント、D番号（決定）、IR番号（不具合）、Phase の出口条件──が手元に揃ったことです。レビュー時間の肩代わりではなく、レビューすべき場所を絞る道具、くらいの位置づけです。
これから試すこと
いま考えているのは、ドキュメントの更新を「実装のあと」だけでなく「違和感を感じた瞬間」にも起票する運用です。不具合ログはこれまで不具合用に使ってきましたが、仕様と感覚のギャップも同じログに載せると、あとから読み返したときの脈絡がつながりそうです。
読んでいる方で、仕様駆動を試している方に一つだけ聞きたいです。あなたのプロジェクトで、最後に「仕様書ではなく自分の勘で上書きした」のは、どんな場面でしたか。逆に、勘を抑えて仕様に従ってよかった場面があれば、それも教えてほしいです（X で @amayan_t に返信いただけると助かります）。
関連する記事
- KiroとCursorを活用した仕様駆動開発 — 進め方・ツールの遠回り
- Colorism v2 開発記 — 矛盾が起きた実例の詳細
- 学習ハブ（/learn/） — AI駆動開発シリーズの読む順
- Colorism v2 アプリ — 本番で触れる完成物
言葉とコードの揃え方をもう一段掘りたい方には、成瀬允宣『ドメイン駆動設計入門』（翔泳社）の第15章「ドメイン駆動設計のとびらを開こう」内にある15.3 ユビキタス言語の節が参考になります（Amazon の商品ページだけでは目次が読み取りにくいので、出版社の紹介ページの目次も併せて見ると分かりやすいです）。仕様の書き方の型としては、GitHub の spec-kit を眺めるのも手です。どちらも正解を教えてくれるというより、自分のプロジェクトで試したあとに読むと腑に落ちるタイプだと思います。
※ 執筆支援に AI を使用しています。事実確認・コード検証・構成の最終判断は著者が行っています。
この記事で使ったサービス
- ドメイン駆動設計入門（成瀬允宣・翔泳社） — 第15章に「ユビキタス言語」の節あり
- Cursor — AI コードエディタ（本記事の実践環境）
※ 一部リンクはアフィリエイトを含みます。