設計書をアホみたいに書きまくってから、ADR を拡張してみた

はじめに 

こんにちは、池本です！

自分は設計書体系を作ろうとして、プライベートのプロジェクトで試していたことがあります。そのとき得た知見の一部を、去年「技術選定の理由、即答できますか？AI との対話で作る設計ドキュメント」にまとめました。

今回はその前と後の話を書きます。設計書体系を作ろうとしていた話そのものと、その後で別のプライベートプロジェクトで試している ADR 拡張の話です。

SDD のドキュメントが読めなかった

2025 年の夏、Kiro でSDD（Spec-Driven Development）という考え方を知りました。AI にドキュメントを書かせて、それに基づいて開発するアプローチです。
Kiro: AIエージェントを活用した開発支援ツール。

Kiro が生成したドキュメントを読みました。1 機能に対して Markdown ファイルが大量に生成されます。読みづらい！ レビューする気になりません。

ただ、AI にドキュメントを書かせて開発するというアイデアそのものは、使えそうだと感じました。なので、自分でも AI に書かせてみることにしました。

設計書をアホみたいに書きまくった

題材は、自分のプライベートの個人プロジェクトです。2025 年 8 月から試しました。

このときに設計書の体系をいろいろ考えたり調べたりしました。個別の設計書を IPO モデル（前提 → 論理 → 結論）で 1 ファイル 1 判断で書くやり方、Why と What の分離、Kruchten の 4+1 ビュー、C4 モデル などです。IPO モデルについては 前回記事 でも書きました。

結果は Markdown ファイル 327 本、依存グラフは 307 ノード・757 エッジになりました。

依存関係はこうなりました（文字は読めなくていいです）。アホみたいにグチャグチャになっているのが伝わると思います。

たとえばフロントエンドという 1 つのトピックだけで、18 ファイル書いていました。

• Logical View にフロントエンド関連が 7 ファイル

  • 画面構造

  • ビジュアルデザイン

  • UI 技術アプローチ

  • UI コンポーネント責務

  • フロントエンドレンダリング方式

  • フロントエンド・バックエンド接続

  • API 契約
    

• Development View のフロントエンド技術選定 に 11 ファイル

  • 状態管理方針

  • パフォーマンス方針

  • アプリ構造評価

  • フレームワーク調査

  • メタフレームワーク調査

  • ビルドツール調査

  • CSS 調査

  • テスト調査

  • 基盤技術選択

  • グラフ可視化選択

  • HTTP API 選択

設計書を書こうとする中で、Kruchten の 4+1 ビューや C4 モデルなど、いろいろなフレームワークを調べる機会になりました。C4 モデルは今も使っています。ただ、前提を考えるのが面倒になって、この設計書体系自体は中断しています。

ADR を拡張してみた

その後、2019 年から動かしている別のプライベートプロジェクトで、ADR（Architecture Decision Record、設計判断の背景と決定を残すドキュメント）を拡張する仕組みを試しています。

そのプロジェクトでは元々 ADR は使っていませんでした。ただ、自分は ADR の、意思決定を残す考え方が良いと感じています。仕事で書くのにも慣れてきました。今回はその ADR をベースに拡張しています。

通常、ADR は immutable（一度決めたら変更しない、変えるときは新しい ADR を起こす）として運用されます。必ずしも immutable じゃなくてもいいんじゃないか、というのが今回の発想です。

具体的には、各 ADR に 3 つ付け足して 1 単位にしています。検出方法には、Neal Ford 他『進化的アーキテクチャ』で提唱された Fitness Function（適応度関数）の発想を当てています。

• 検出方法: ADR で決めたことに違反していないかを発見する手段

• 運用手順書（Runbook）: 違反を見つけたときの修正手順

• 現在の適用状況: ADR と実体の整合状況のトラッキング

検出方法には、リンタのほか、grep など簡易的なものも使っています。誤検出があっても AI がカバーしてくれます。

おわりに

この記事では、設計書をアホみたいに書きまくった話と、ADR を拡張してみた話を書きました。

ADRの拡張は、決めたことと、それを検証する仕組みと、直し方と、現状の記録を、1 つのドキュメントに同梱した形です。今のところうまく回っています。

うまく回っているのは、ADR が 1 判断にスコープを閉じているからだと思います。事前に完璧な体系を作ろうとすると前提が膨らんで続かなくなりますが、ADR は 1 判断単位で書くので、不完全を認めて事後に検出して直すという形と相性がよい。自分にはこちらのほうが続けやすい気がしています。

ちなみに、Martin Fowler のサイトで Birgitta Böckeler が Spec-anchored と呼んでいる発想と、思想として近いと考えています。

この方向は、もう少し追求していきたいと思います。