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