📜

SDD疲れの処方箋 ── AI時代の設計判断はADR 1枚で残す

に公開
AI
アーキテクチャ
ADR
開発効率化
Claude
tech

この記事について

対象読者: AIコーディングを日常的に使っていて、SDD（仕様駆動開発）ツールを触ったものの「毎回このボリュームのドキュメントは重すぎる」と感じている方。あるいは「設計判断の記録」を軽く始めたいけれど、何をどう残せばいいか迷っている方。

ADRとは: Architecture Decision Record の略で、「1つの設計判断 = 1つのMarkdownファイル」として時系列で残す軽量な台帳のこと。10年以上の歴史がある業界標準のプラクティスです（詳細は後述）。

この記事を読むと: ADRが「書いた後にどう生きるか」を具体的に理解し、SDD・Planモード・ADRをプロジェクトの規模や性質で使い分けられるようになります。特にAIコーディング時代にADRが持つ新しい価値について、手元で動かせる運用レベルまで踏み込んで解説します。

前回の記事「Claude Codeタスク管理・Agent Teams時代にSDDツールは必要か」の続編として読めます。

tl;dr ── SDDより軽く、AIに読まれる判断記録

要は: SDDは多くの場面で過剰。唯一残る「設計判断の永続化」だけを軽く切り出したのがADRで、AIが即座に読んで一貫性を保ってくれる時代だからこそ相対価値が上がっている。

  • SDDは多くの場面で過剰で、唯一残る「設計判断の永続化」だけを軽く切り出したのがADR。10年以上の歴史がある業界標準のプラクティスで、1つの判断を1つのMarkdownに残すだけのシンプルなもの。
  • AI時代の新しい価値: 紙のADRは人間に読まれずに終わりがちだったが、AIは全部読んで即座に答える。過去の判断との一貫性が低コストで保てる。
  • ADRは「なぜ」専用。「今どうなっているか」はコード + テスト + AI読解で足りる時代。だからこそ「なぜ」の相対価値が上がった。
  • 実務のレイヤー分け: README（入口の地図）/ ADR（なぜ）/ コード + テスト（今）。SDD・Planモード・ADRは扱う粒度が違うので併用OK。
  • 導入は公開スキルを1ファイル置くだけ。自然言語で「ADRに残そう」「なぜXにしたっけ」と言えば自動で発火する。

以降、各論点を掘り下げます。

なぜ今ADRか？ ── SDDの守備範囲が侵食されつつある

前回の記事でも触れたとおり、Claude Code標準機能（Planモード、タスク管理、Agent Teams、サブエージェントの永続メモリ）の進化で、SDDツールが担っていた仕事の多くが標準機能に吸収されつつあります。

SDDが担っていた 今は…
計画の立案とレビューサーフェス Planモードの plan.md
セッションをまたいだ進捗管理 タスク管理システム（v2.1.16〜）
並列実行・コンテキスト分離 Agent Teams
AIが学んだパターンの蓄積 サブエージェントの永続メモリ

一方で、SDDが提供していた価値のうち、まだ標準機能に吸収されていない領域が1つだけ残ります。それが「設計判断を構造化して永続的に残す」ことです。

ただ、この目的のためだけにSDDツール一式（requirements → design → tasks の複数ファイル運用）を回すのは、たいていのケースで過剰です。

  • バグ修正や小さなリファクタに毎回SDD全体のフローを回すのは現実的ではない
  • AIが生成したドキュメント群を読み直すコストが、判断を参照するメリットを食い潰す
  • Martin FowlerもSDDの「硬直性＋非決定性」に警鐘を鳴らしている

ここで浮かび上がってくるのが、「設計判断」というピースだけを切り出して軽く残すという選択肢です。それがADRです。

ADRとは

ADR（Architecture Decision Record）は、「1つの設計判断 = 1つのMarkdownファイル」として時系列で残す台帳です。

2011年にMichael Nygard氏が"Documenting Architecture Decisions"で提唱したのが起源で、その後10年以上かけて業界に浸透してきました。

MADR-lite形式

本記事では軽量版の MADR-lite（最低限のMarkdown ADR）を前提にします。

# ADR-0007: 認証方式にOIDCを採用する

**Date**: 2026-04-17
**Status**: accepted
**Deciders**: @kosk, @teammate

## Context

なぜこの判断が必要だったか（背景、制約、課題）

## Decision

採用した案と理由

## Alternatives Considered

### Alternative 1: OIDC
- **Pros**: ...
- **Cons**: ...
- **Why not**: (このオプションを却下した場合) ...

### Alternative 2: 独自のセッショントークン
- **Pros**: ...
- **Cons**: ...
- **Why not**: ...

## Consequences

### Positive
- ...

### Negative
- ...

### Risks
- ...

3つの大原則

原則 意味
Append-only 一度書いたADRは削除・書き換えしない
1判断 = 1ファイル NNNN-kebab-title.md (4桁ゼロパディング)
Supersedeで覆す 古い判断を覆すときは新ADRを作り、旧ADRのStatusを superseded by ADR-NNNN に書き換える

判断を「その時点のスナップショット」として残し、変更は差分として記録する ── このシンプルな原則が、ADRを長く機能させる仕組みです。

ADRは書いた後どう生きる？

ここがこの記事の中心です。ADRを書いても「書きっぱなし」になっては意味がありません。ADRが書いた後にどう機能するかを4つの観点で見ていきます。

1. 未来の自分・新メンバーへの「なぜ」の証言

gitログとコードを見れば「何を変えたか」は分かります。でも「なぜ他の選択肢を捨てたか」は残りません。

  • 「なぜDynamoDBじゃなくてPostgreSQLにしたんだっけ」
  • 「このパッケージ分割、最初からそうだったのか、後から直したのか」
  • 「認証をJWTに寄せたのは、何が決め手だった？」

3ヶ月後の自分、半年後に入った新メンバー、過去の議論を知らないレビュアー ── 彼らが同じ疑問を繰り返さずに済むように、判断の理由と代替案の却下理由を残すのがADRの本質です。

2. AIが即答できる判断台帳 ── これが2026年の新しい価値

ここがSDDやPlanモードと性質が違うポイントです。

Claude Codeのようなエージェントは、過去のチームの判断を知りません。既存のADRを意図的に参照させない限り、AIは毎回ゼロから「自分の知識で最善と思う設計」を提案してきます。結果として、半年前にチームで合意した判断が、AIの手でしれっと覆されることが起きます。

ここで効いてくるのがADRです。設計判断が構造化されたMarkdownとして docs/adr/ に置いてあれば、AIは全ADRを瞬時に横断して「過去の判断」を即答できるようになります。人間のレビュアーは過去のADRを毎回思い出せませんが、AIなら全部読めます。

ユーザー: 「認証周りの今の方針ってなんだっけ？」
  ↓
Claude: (ADRスキルが発火) docs/adr/ を検索 → ADR-0007（OIDC採用）を発見
  ↓
Claude: 「ADR-0007でOIDCが採用されています。
        独自セッショントークンは却下済みです。
        今回の変更はこの方針の延長で進めますか？
        それとも方針自体を覆すなら、supersedeで新ADRを作ります」

「聞けば必ず過去の判断が返ってくる」という状態になることで、設計の一貫性を保つコストが劇的に下がります。

さらに強めの運用として、CLAUDE.mdに「設計変更前にADRを確認すること」とルールを1行足せば、ユーザーが明示的に聞かなくても、Claudeが自発的に過去の判断を参照してから実装に入るようにもできます（後述）。

これは従来のADR運用にはなかった、AIコーディング時代に生まれた新しい価値です。紙のADRを書いて本棚に並べても誰も読まないことはよくありましたが、AIは読みます。

3. レビューの共通参照点

PRレビューで「なぜこの設計？」と聞かれたとき、毎回議論を再演するのは疲れます。

  • ❌ Before: PRコメントで毎回10往復の議論
  • ✅ After: 「ADR-0012を参照してください」で終了

設計判断がチームの共通アセットになることで、同じ議論を何度もやり直すコストが消えます。

4. Supersedeで判断履歴が残る

状況は変わります。当時ベストだった判断が今はベストでなくなることは普通にあります。

ADRのappend-only原則は、覆すことを禁じるものではなく、覆す過程を記録するものです。

ADR-0007: OIDCを採用する (2024-03-12, superseded by ADR-0023)
  ↓
ADR-0023: 認証をOIDCからMagic Linkに変更する (2026-04-17)
  - Supersedes: ADR-0007
  - Context: ユーザー層がモバイル中心に変わり、OIDCのUXが合わなくなった

「2024年時点の判断」と「2026年時点の判断」の両方が読めることに価値があります。「当時はこう考えたけど、状況が変わってこう変えた」が時系列で追えるため、将来また似た判断が必要になったときの強力な参考資料になります。

ADRが答えないこと ── 現仕様はどこに残す？

ここで正直に認めておくべきことがあります。ADRは「なぜ」は残すけれど、「今どうなっているか」には答えません。

「認証周りの現在の仕様が知りたい」「このAPIのレスポンス形式は今どうなってる？」と聞かれたとき、ADRを読んでも答えは出てきません。ADR-0007は「2024年時点でOIDCを採用した理由」を記録しているだけで、その後のパッチや拡張は反映されないからです。

そしてこれはSDDも同じ問題を抱えています。SDDの仕様書は「書いた時点のスナップショット」で、コードが先に進めば仕様書は腐ります。OpenSpecのデルタ仕様はこれに対抗する工夫ですが、それでも「仕様書さえあれば現状が分かる」という期待は現実にはほぼ幻想です。

AI時代の新しい答え ── 現仕様の一次情報はコード + テスト

ここで効いてくるのが、コードをAIに読ませれば現仕様が分かる時代になったことです。

  • 「このモジュール何してる？」→ AIに聞けば数秒で要約が返る
  • 「この関数の契約は？」→ テストを読めば分かる（テストなら腐っても落ちて気づける）
  • 「このデータフロー全体を説明して」→ AIがコードベース横断で説明できる

結果として：

  • 「今の仕様」を人間が文書化する価値 → 下がった
  • 「なぜそうしたか」を残す価値 → 上がった（コードから復元できない情報だから）

ADRの相対的な重要度が上がっているのはここが理由です。

でも「入口」だけは書いておく価値がある

とはいえ、完全にドキュメントをゼロにするのは現実的じゃない、という感覚も正しいと思います。特に次のような情報は、AIに聞くより先に目に入る場所（README等）にある方が圧倒的に速い：

  • このシステムが何を解決するためにあるか（目的・対象ユーザー）
  • 主要な構成要素と責務のざっくりした絵
  • どこから読み始めればいいか（エントリポイント）

新しく入った人が最初の30分で全体像を掴むための地図だけは、ドキュメントとして残す価値があります。

腐り度マトリクス ── 書く vs 書かない

「場合による」の判断軸は腐りやすさで切るのが現実的です。

情報の種類 腐り度 どこに置くか
関数シグネチャ、実装フローの詳細 ⚠️ すぐ腐る 書かない（コードを読む / AIに聞く）
詳細な挙動仕様 ⚠️ すぐ腐る テスト（腐ったら落ちて自動で気づける）
外部API契約 🟡 バージョンで変わる OpenAPI等のスキーマファイル（機械可読で検証可能）
主要コンポーネントの分割と責務 🟡 数年単位 README / アーキ概要図
システム全体の目的・対象ユーザー 🟢 めったに変わらない README冒頭
設計判断の理由 🟢 歴史なので腐らない ADR

原則はシンプルです：

  • 腐りやすいものは書かない（書くなら機械的に検証できる場所に書く = テスト、スキーマ）
  • 腐りにくいものだけ人間向けに書く（README、ADR）

現実的な3階層

結局、実務で落ち着くのはこのあたりだと思います：

README         → 目的・全体構造・入口の「地図」（腐りにくい粒度で薄く）
ADR            → 「なぜ」の台帳（append-only、腐らない）
コード + テスト → 「今どうなっているか」の一次情報（AIで読める）

この3階層なら、SDDツール一式を回さなくても「現状」「理由」「入口」が揃います。毎回 requirements / design / tasks を生成するコストは払わずに済む、というのが現時点での軽量な解です。

何を書く？何を書かない？

ADRの守備範囲（「なぜ」専用、現仕様には答えない）がわかったところで、その中でどの判断をADRに残すかの線引きを示します。「アーキの判断があるときだけ書く」が原則ですが、「アーキの判断」の定義は曖昧なので、実務的な基準で切ります。

書くべきもの

判断の性質 例
覆すのにコストがかかる DB選定、認証方式、通信プロトコル、マイクロサービス分割
複数の代替案を比較検討した 状態管理ライブラリ、ORM、デプロイ戦略
チームの暗黙知では伝わらない なぜこの命名規則？なぜこのエラーハンドリング方針？
公開仕様に影響する API設計、データモデル、URLスキーム

書かなくていいもの

  • 単発のバグ修正・単純リファクタ
  • 自明な技術選択（ReactでuseState使う、Goでgoroutineを使う等）
  • 可逆性が高い実装詳細（関数名、ファイル配置等）
  • ローカルな判断（1つのモジュール内で閉じる設計）

迷ったら「3ヶ月後の自分が理由を思い出せるか」で判断

これが一番実用的な基準です。

  • 3ヶ月後に「なんでこうしたっけ？」と悩みそう → 書く
  • 3ヶ月後に見ても自明 → 書かない

あるいは「もし新メンバーが同じ判断を覆そうとしたら、きちんと反論できるか」という基準でも良いでしょう。反論の材料（却下した代替案・却下理由）を書き残すのがADRです。

ADR vs SDD vs Planモード ── 粒度とタイミング

3者は競合するものではなく、扱う単位が違うものです。

Planモード SDD ADR
扱う単位 1セッション 1つの変更（feature単位） 1つの設計判断
ファイル構成 plan.md 1枚 requirements + design + tasks（複数ファイル） NNNN-title.md 1枚 × 判断数
タイミング 実装直前 実装前（承認ゲート式） 判断時（実装前後どちらでも）
寿命 セッション限り 変更完了まで（完了後はアーカイブ、以降更新されない） プロジェクトが生きている限り
覆し方 セッション中に上書き編集 変更進行中なら仕様書を更新 / アーカイブ後は新しい変更を立ち上げる 新ADRで supersede（旧ADRは残る）
主な読者 現在のClaude 実装担当（AI＋人） 未来の自分・新メンバー・AI
向く粒度 小〜中規模の実装 中〜大規模の機能追加 全粒度（判断単位） 
時間軸:
  Plan ━━━━━│                                  (セッション終了で消える)
  SDD  ━━━━━━━━━━│                             (実装完了でアーカイブ)
  ADR  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━▶ (プロジェクトと共に生きる)

つまり、Planモード/SDDは実装を前に進めるためのドキュメントで、ADRは実装後も残り続ける判断の台帳です。同じプロジェクトで3つを併用することに全く矛盾はありません。

AIコーディングとADRの運用

ADRをAIコーディングフローに組み込む具体的な方法を紹介します。ここではClaude Codeのスキル機能を使った運用を例に挙げます。

ADRスキル（公開スキル）

Claude Code用のADRスキルはいくつか公開されています。中でも affaan-m/everything-claude-code（約16万⭐）に収録されている architecture-decision-records スキルが、軽量なMADR形式に沿っていて扱いやすく、2026年4月時点で定番のひとつです。

導入

SKILL.md を ~/.claude/skills/architecture-decision-records/SKILL.md に配置するだけで使えます。

mkdir -p ~/.claude/skills/architecture-decision-records
curl -sL https://raw.githubusercontent.com/affaan-m/everything-claude-code/main/skills/architecture-decision-records/SKILL.md \
  -o ~/.claude/skills/architecture-decision-records/SKILL.md

動作

スラッシュコマンドを覚える必要はなく、会話の中で自然に触れた瞬間にスキルが発火します。

こう言うと… スキルが…
「このDB選定、ADRに残そう」「record this as an ADR」 新規ADRのドラフトを作り、承認後に docs/adr/NNNN-*.md を書き出してREADMEインデックスに追記
「なぜPostgreSQLにしたんだっけ？」「why did we choose X?」 docs/adr/ を検索して該当ADRのContext/Decisionを提示
2つの選択肢を比較して結論が出たとき 自動で「これADRに残しますか？」と提案
「ADR-0007をMagic Linkに覆したい」 Status行を superseded by ADR-NNNN に更新し、新ADRを作成

初回は docs/adr/ ディレクトリ・README（インデックス表）・template.md をユーザー確認のうえ自動セットアップしてくれます。

強めにしたければ CLAUDE.md で補う

上記のスキルは「聞かれたら答える / 決定モーメントを検出したら提案する」受け身型です。これだけでも実用上は十分なことが多いのですが、もし「設計変更の前に必ず既存ADRと整合するかを自動チェックしてほしい」というガードが欲しければ、CLAUDE.md に1行足すだけで実現できます：

## 設計変更時のルール
データ構造・認証方式・通信プロトコル・主要依存ライブラリの変更に入る前に、
`docs/adr/` を確認し、関連する既存ADRと矛盾しないか検証すること。矛盾する場合は
supersede を提案してから進む。

これで、ユーザーが「リファクタして」と頼んだときにも、Claudeが自発的に既存ADRをスキャンしてから実装に入るようになります。スキル本体を書き換えるよりCLAUDE.md側で制御する方が、プロジェクトごとに有無を切り替えやすく、ADRが増えたときのコンテキスト圧迫も避けられます。

書くタイミング

運用上のおすすめは：

  • 判断の議論中: Status = proposed で書き始める
  • PR merge時: Status = accepted に更新
  • 後から振り返って書く: 「あのとき書いておけばよかった」判断も遡って書いてOK

「決定と同時に書く」が理想ですが、書き忘れたものを後から書くのも十分価値があるというのが個人的な実感です。記憶が鮮明なうちなら、議論の直後でなくても問題ありません。

副産物としての「議論ログ」

実際に書いてみると気づくのですが、Alternatives Considered セクションが事実上の議論ログとして機能します。

「なぜこの案を選んだか」を書くには、必ず却下した案とその理由を整理する必要があります。このプロセスを通すと、チャットやPRコメントに散らばっていた議論が自然と構造化され、1つのMarkdownに収まります。

  • 「Aも検討したけどxxの理由で却下した」
  • 「Bは短期的には良かったがスケールしないと判断した」

こうした情報が**「残そう」と意識しなくても自然に書かれる**のは、ADRのフォーマットがもつ副産物的な効用です。

使い分けの指針

前回記事の4層整理をベースに、今回の議論を踏まえて6層に再構成します。主な変更は3点です：

  • SDD層を「仕様の永続化・検証」から「変更の仕様化」に改名: SDDの仕様書は変更完了でアーカイブされ、以降更新されない。「永続化」ではなく「変更進行中の実装プロセス」と捉え直した
  • 「設計判断の永続化」層を新設 ⭐: SDDからこぼれ落ちていた「長く残したい判断」の居場所を明示。ここがADRの担当
  • 「現仕様の一次情報」層を新設: AIでコードが読める時代の「今どうなっているか」の置き場。ドキュメントで管理する対象ではないと明示
層 担うもの 手段
計画・実行管理 何を・どう進めるか（セッション粒度） Planモード、タスク管理、Agent Teams
変更の仕様化 中〜大規模な機能追加の要件→設計→タスク分解 SDDツール（OpenSpec, cc-sdd, Spec Kit 等）
設計判断の永続化 ⭐ 判断単位の理由・代替案・履歴（append-only） ADR
現仕様の一次情報 ⭐ 今どうなっているか コード + テスト（+ AI読解）
知識の蓄積 AIが学んだパターンや知見 サブエージェントの永続メモリ
標準管理 AIがどう振る舞うべきか CLAUDE.md、Agent OS、カーソルルール

シチュエーション別の推奨

状況 推奨
1セッションで完結する実装変更 Planモードで十分
バグ修正・小さなリファクタ Planモードで十分（ADRもSDDも不要）
複数セッション・並列実行が必要 タスク管理 / Agent Teams
大規模な新機能追加で仕様書をまとめたい SDDツール（OpenSpec等）
設計判断の理由を長く残したい ADR
既存の設計判断を覆したい ADR supersede
AIに過去の判断を守らせたい ADR + プロアクティブチェック
人間のチームで仕様共有・レビュー SDDツール

併用パターン

実際の運用では併用が自然です：

新機能開発:
  SDDツールで要件・設計・タスクを定義
    ↓
  重要な設計判断だけADRに切り出して残す（SDDアーカイブ後も生きる）
    ↓
  実装はPlanモード + Agent Teamsで進める

バグ修正・軽微な変更:
  Planモードのみ（ADRもSDDも不要）

設計判断の変更:
  「関連するADRある？」 → スキルが既存ADRを検索・提示
    ↓
  覆す必要があれば「ADR-NNNNをsupersedeする新ADRを作って」
    ↓
  Planモードで実装に入る

まとめ

設計判断が本当に生きるのは、書いた瞬間ではなく書いた後に参照されたときです。ADRが書いた後に発揮する価値を振り返ると：

  1. 未来の自分・新メンバーへの「なぜ」の証言
  2. AIが即答できる判断台帳（← 2026年の新しい価値。紙のADRは読まれずに終わりがちだったが、AIは読む）
  3. レビューの共通参照点
  4. Supersedeによる判断履歴の時系列記録

どれも「書いた時点」ではなく「書いた後」に効いてくるものです。だからこそ重いSDD一式を毎回回す必要はなく、軽いMarkdown 1枚で十分に間に合います。

まずは docs/adr/ を作って、最近の設計判断を1つだけ書いてみるところから始めてみてください。2つ目を書くときには、すでに恩恵を感じているはずです。

参考リンク

ADR

Claude Code向けADRスキル

関連記事

SDDに関する分析記事

Discussion