バイブコーディング時代のADRベストプラクティス

この記事では、バイブコーディングを pair programming / mob programming 型のリアルタイム協業として扱います。つまり、1人が黙って設計し、あとで実装する開発ではなく、複数人とAIエージェントが会話しながら、設計・実装・テスト・レビューを同時に進める状況です。

この開発では、意思決定が速くなります。一方で、決定の理由も速く蒸発します。コードは「何を作ったか」は示せますが、何を却下したか、どの制約に縛られたか、どのトレードオフを受け入れたかまでは残してくれません。

そこで必要になるのが ADR、Architecture Decision Record です。ADR は、アーキテクチャ上重要な判断を、背景・選択肢・決定・結果とともに残す短い文書です。

結論は明快です。

• ADR はすべてを書く文書ではない
• 構造、品質特性、難逆性に効く判断だけを書く
• バイブコーディングでは、決定後の清書より 決定形成中のdraft が効く
• 既定は Nygard 型で軽く始める
• 横断影響、監査性、高リスク判断だけ MADR 相当へ拡張する
• accepted 後のADRは原則書き換えず、変更時は新ADRで supersede する

なぜ今ADRか

mob programming の代表的な説明では、チーム全員が同じものを、同じ時間に、同じ空間で、同じコンピュータ上で扱います。実装だけでなく、設計、テスト、デプロイ準備、顧客やステークホルダーとの作業も working meeting として進めます。分散 pair programming の研究でも、pair は同じ設計・アルゴリズム・コードについて継続的に会話することが前提です。

つまり、判断は設計書の前ではなく、会話の中で発生します。

AIエージェントを含むバイブコーディングでは、この傾向がさらに強まります。Claude Code、Codex、Cursor、Cline のようなエージェントは、実装案、修正案、テスト案を短時間で複数出します。人間はそれを見ながら、会話の中で選びます。

このとき、ADRがないと次の問題が起きます。

• 半年後に「なぜこの方式にしたのか」が分からない
• 却下した案が再提案され、同じ議論が蒸し返される
• 新メンバーが設計意図をコードから推測するしかない
• AIエージェントが過去の判断に反する実装を提案する
• チームをまたぐ判断がSlack、PR、Issue、議事録に散る

ADR は、この「理由の負債」を抑えるための最小限の制御面です。後で読むための重い設計書ではなく、同期協業で生まれた判断を、非同期共有、将来変更、オンボーディング、他チーム伝達へつなぐ薄いインターフェースだと考えると実務に乗せやすくなります。

関連するAIエージェント時代の文書設計は、次の記事も近いテーマです。

• AIエージェント向け指示書・メモリ設計の実務テンプレート
• ライブコーディングでHTML・Markdown・JSONを使い分けるベストプラクティス

ADRの定義

Google Cloud は、ADR を「利用可能な主要オプション、決定を推進する主な要件、設計上の決定事項を捉えるもの」と説明しています。AWS は、ソフトウェアアーキテクチャの重要な側面についてチームが選んだ内容、コンテキスト、結果を記録する文書と整理しています。Azure Well-Architected Framework は、ADRに含めるべき対象を、構造、主要品質特性、戻しにくい選択に限定するよう勧めています。

ここで重要なのは、ADR は「実装手順書」ではなく「判断の記録」だという点です。

コードは「現在の姿」を示します。ADR は「その姿になった理由」を示します。

歴史

設計判断を第一級の知識として扱う流れは、2004年の Philippe Kruchten による設計判断オントロジーに遡ります。そこでは、設計判断と相互依存関係を保存することが、進化と保守を支えると論じられました。

2005年には Jeff Tyree と Art Akerman が、Issue、Decision、Status、Assumptions、Constraints、Positions、Argument、Implications などを含む詳細な decision template を提示しました。これは説明責任や統治には強い一方、日常の開発には重くなりがちです。

2011年に Michael Nygard が、短いテキストファイルとしての軽量 ADR を提案しました。基本構成は、Title、Status、Context、Decision、Consequences です。現在の多くのADR運用はこの Nygard 型から始まっています。

2018年前後には MADR、Markdown Architectural Decision Records が広がりました。MADR は Markdown を前提にしながら、decision drivers、considered options、pros/cons、decision outcome、confirmation、metadata を明示できる構造化テンプレートです。MADR 公式では 4.0.0 を選択肢として扱うADRも公開されています。

2025年には GOV.UK の Architectural Decision Record Framework が公開され、公的機関の横断ガバナンスでも ADR が明示的に採用されました。2026年には Nygard、MADR、Tyree/Akerman、arc42、Y-statements を比較する arXiv 論文も出ており、Nygard は簡潔さと採用しやすさ、MADR は構造的な詳細と特定のアーキテクチャ要件の表現に強い、という整理が示されています。

テンプレートの選び方

ADRのテンプレート選定で失敗しやすいのは、最初から「完璧な形式」を決めようとすることです。実務では、判断の重さに応じて使い分けるほうが長続きします。

推奨は、lean を既定、rich を昇格です。

日常のバイブコーディングでは Nygard 型で十分です。横断影響が出る、セキュリティやSREの確認が必要、監査可能性が必要、将来の説明責任が重い、と分かった時点で MADR 相当へ昇格します。

何をADRにするか

ADRにするかどうかは、次の3条件で判断します。

具体例です。

ADRにするもの:

• モノリスを分割する境界
• REST ではなく GraphQL を採用する
• 認証方式をセッションからJWTに変える
• APIゲートウェイでレート制限する
• キュー基盤として Pub/Sub、SQS、Kafka のどれを選ぶか
• フロントエンド状態管理を特定方式に寄せる
• 監査ログの責務をアプリ層か基盤層に置く

ADRにしないもの:

• 変数名や関数名の変更
• 一時的な設定値変更
• 実装中に見つけた小さなリファクタ
• 単なるライブラリのpatch更新
• 仕様書そのもの
• 会議メモの全文

迷ったら、将来のメンバーがコードを見て「なぜこうしたのか」と聞きそうかで決めます。

バイブコーディングでの書き方

従来のADRは、設計会議の後にテックリードが清書する運用になりがちでした。バイブコーディングでは、それだと遅いです。判断はセッション中に次々と発生し、あとから思い出すほど理由が薄まります。

推奨フローは次です。

ポイントは、議論を止めずに残すことです。最初から完成文書にしようとすると書かれません。まずは、会話中に次の4行だけ残せば十分です。

# APIゲートウェイのレート制限はエッジ層で実施する

## Context
各サービスで個別にレート制限しており、ルール差異と監視のばらつきが出ている。

## Options
- 各サービスで実装する
- APIゲートウェイで実施する
- CDN / WAF 側でのみ実施する

## Open Questions
- 例外ルールをどこで管理するか
- ゲートウェイ障害時のフェイルオープン/フェイルクローズをどうするか

この段階では draft です。合意形成のための作業台として使います。

推奨テンプレート

以下は、Nygard 型をベースに、MADR の metadata、選択肢比較、confirmation を足した実務向けテンプレートです。バイブコーディング中に起票しやすく、あとで監査やレビューにもつなげやすい形にしています。

---
id: ADR-0042
status: proposed
date: 2026-05-11
decision-makers:
  - "@tech-lead"
  - "@backend-lead"
consulted:
  - "@security"
  - "@sre"
informed:
  - "@product"
related-issues:
  - ISSUE-128
related-prs:
  - PR-932
related-commits:
  - abc1234
session-log:
  - pair-session-2026-05-11-am
supersedes:
superseded-by:
---

# APIゲートウェイのレート制限はエッジ層で実施する

## Context
現在のレート制限は各アプリケーションで個別実装されており、
実装の重複、ルール差異、監視のばらつきが生じている。
モバイルAPIと管理画面APIの増加に伴い、横断的な制御点が必要になった。

## Decision Drivers
- DoS・濫用対策を統一したい
- サービスごとの実装差分を減らしたい
- 運用時に閾値変更を一元管理したい
- 将来的なマルチサービス構成に耐えたい

## Considered Options
- 各サービスでアプリケーションレベルに実装する
- APIゲートウェイ / エッジ層で一括実施する
- CDN / WAF 側でのみ実施する

## Decision
APIゲートウェイ / エッジ層でレート制限を一括実施する。
横断一貫性と運用変更容易性を最も高い水準で満たし、
サービス実装の重複も減らせるため。

## Consequences
- Good: 実装重複が減り、監視・変更点が集約される
- Good: 横断ポリシーを一箇所で管理できる
- Bad: ゲートウェイ障害時の影響範囲が広い
- Bad: 例外ルールは設計を丁寧にしないと複雑化しやすい

## Pros and Cons of the Options

### 各サービスで実装する
- Good: サービスごとの柔軟性が高い
- Bad: 実装重複と逸脱が増える
- Bad: 監視・変更が分散する

### APIゲートウェイ / エッジ層で一括実施する
- Good: 横断一貫性が高い
- Good: 運用変更を集約できる
- Bad: 共通基盤への依存が強まる

### CDN / WAF 側でのみ実施する
- Good: 早い段階で遮断できる
- Bad: アプリケーション文脈を使った細粒度制御が難しい

## Confirmation
- アーキテクチャレビューで制御点の責務分離を確認する
- 負荷試験で閾値動作とフェイルオーバーを確認する
- 運用Runbookに閾値変更手順を追加する

## Revisit Triggers
- サービス数が2倍を超える
- ゲートウェイを分割する
- B2B APIの個別契約が増える

## Links
- ADR-0037: 認証方式
- ADR-0039: API分割方針
- PR-932

このテンプレートの肝は、decision-makers、consulted、informed を分けることです。全員を「承認者」にすると重くなります。相談した人、知らせる人、決める人を分けると、分散チームでも責任がぼやけません。

レビューと承認

GDS Way は、ADR の提案状態を GitHub の draft PR として扱う運用を紹介しています。GOV.UK のADR Framework も、判断のスコープに応じて適切な decision-making body へ review / approval する流れを示しています。

実務では、次の3パターンを使い分けると軽く回ります。

バイブコーディングでは、最初は Discussion で議論し、accepted になった本文だけ docs/adr/ に入れる運用も現実的です。ENECHANGE の事例では、GitHub Discussions が Markdown、コメント、ID、ラベル、議論の記録を持つ点が ADR と相性がよいとされています。

accepted後は書き換えない

AWS、Azure、GDS、Martin Fowler の整理はいずれも、受理済みADRの履歴を残すことを重視しています。accepted なADRを後からこっそり書き換えると、当時の判断が失われます。

運用ルールは次で十分です。

• proposed 中は更新してよい
• accepted 後は、誤字やリンク修正以外は原則変更しない
• 前提が変わったら、新しいADRを書く
• 古いADRは superseded by ADR-00xx とする
• 新しいADRには supersedes ADR-00yy を書く

これは面倒に見えますが、長期的には効きます。いつ、どの前提で、どの判断が有効だったのかを追えるからです。

バイブコーディングチームと従来チームの違い

バイブコーディングでは、ADRを書くこと自体がコラボレーションの一部です。清書担当があとで作文するより、その場で「この決定のタイトルは何か」「却下した案は何か」「何を確認したら完了か」を話すほうが、判断の品質も上がります。

実践ワークフロー

導入初期は、次の流れで十分です。

1. セッション中に、構造・品質特性・難逆性に影響する判断が出たら止める
2. ADR候補かどうかを30秒で判定する
3. scribe を1人決める
4. 文タイトル、Context、Options、Open Questions だけ書く
5. セッション後に Decision、Consequences、Confirmation を追記する
6. draft PR または Discussion に出す
7. consulted / informed を明示してレビュー依頼する
8. accepted になったら docs/adr/ に置く
9. 実装PR、Issue、コミットから ADR をリンクする
10. 前提が変わったら新ADRで supersede する

コミットメッセージはADRの代替ではありません。ただし、相互参照には使えます。

Implement edge rate limiting

ADR: ADR-0042
Refs: ISSUE-128

PR本文には、次のように入れます。

## Architecture Decision

Implements ADR-0042: APIゲートウェイのレート制限はエッジ層で実施する

## Confirmation

- [ ] 閾値動作の負荷試験を追加
- [ ] Runbook更新
- [ ] SREレビュー完了

この程度で、会話、判断、実装、確認が一本につながります。

運用コスト

ADRは無料ではありません。書く時間、読む時間、レビューする時間がかかります。だからこそ対象を絞ります。

実務上の目安は次です。

これは厳密な統計値ではなく、制度設計の初期見積りです。重要なのは、ADRの費用をゼロと見なさないことです。価値がある判断だけADR化します。

CIと検索性

ADRは「書いて終わり」だと腐ります。最低限、次の仕組みを入れます。

• docs/adr/README.md に一覧を置く
• ファイル名は 0042-edge-rate-limiting.md のように番号 + 短いslugにする
• front matter に status、date、tags、decision-makers を持たせる
• markdownlint をCIで回す
• accepted / superseded の整合性を棚卸しする
• 横断ADRは中央リポジトリにも索引を持つ

ECSA 2024 の実務研究では、ADRは documentation culture、knowledge transfer、何を記録すべきかの優先順位づけには効く一方、分散コンポーネントをまたぐ課題は残ると報告されています。また、どこに文書を置くかが有用性に大きく影響するとされています。

したがって、保管場所は一枚岩にしません。

「コードの近く」と「横断検索性」は両方必要です。

導入チェックリスト

最初の2週間は、次だけ決めれば始められます。

• ADRを書く判断基準を3つに絞る: 構造、品質特性、難逆性
• docs/adr/ を作る
• 0001-record-architecture-decisions.md を作る
• Nygard型テンプレートを既定にする
• MADR相当へ昇格する条件を決める
• proposed / accepted / superseded のstatusだけ使う
• draft PR または Discussion のどちらでレビューするか決める
• accepted後は書き換えず、supersedeするルールを明文化する
• PRテンプレートに Related ADR 欄を追加する
• 四半期棚卸しの担当を決める

AIエージェントを使うチームなら、AGENTS.md や CLAUDE.md に次のようなルールを入れておくと効果があります。

## ADR

- 構造、品質特性、難逆性に影響する判断を提案する場合は、ADR候補として明示する。
- accepted ADR に反する実装を行う前に、既存ADRを参照し、新しいADRでsupersedeが必要か確認する。
- ADRは `docs/adr/` に置く。
- 日常判断はNygard型、横断影響や監査性が必要な判断はMADR相当に拡張する。

限界

ADRは万能ではありません。

まず、悪いコラボレーションをADRだけで直すことはできません。pair/mob の研究では、疲労、役割交代の失敗、参加者の沈黙、支配的な参加者などが問題になります。ADRは判断を残す道具であり、心理的安全性やファシリテーションの代替ではありません。

次に、ADRは分散システムの依存関係を自動で解きません。共有コンポーネント、複数リポジトリ、複数チームをまたぐ判断には、検索、タグ、中央索引、所有者設計が必要です。

最後に、テンプレートを重くしすぎると書かれません。2026年のADRテンプレート比較論文でも、Nygardは簡潔で客観的な文書化に向き、MADRは構造的詳細や特定のアーキテクチャ要件の表現に向くとされています。どちらか一方を全件に強制するより、判断の重さで切り替えるほうが現実的です。

まとめ

バイブコーディング時代のADRは、設計書ではなく、同期協業で発生した判断の外部記憶です。

最小ルールはこれで十分です。

• ADRは、構造・品質特性・難逆性に効く判断だけに使う
• セッション中に draft を起こす
• Nygard型で軽く始める
• 横断影響や監査性が必要ならMADRへ昇格する
• accepted 後は書き換えず、supersede する
• コード、PR、Issue、会話ログ、コミットを相互リンクする

会話が速いチームほど、理由は速く失われます。ADRは、その速度を落とすための文書ではありません。速い判断を、将来のチームが再利用できる知識に変えるための、いちばん軽い仕組みです。

参考リンク

• Michael Nygard: Documenting Architecture Decisions
• Architectural Decision Records GitHub organization
• MADR: Markdown Architectural Decision Records
• MADR: ADR Template
• AWS Prescriptive Guidance: ADR process
• AWS Prescriptive Guidance: ADR best practices
• Google Cloud: Architecture decision records overview
• Microsoft Azure Well-Architected Framework: ADR
• The GDS Way: Documenting architecture decisions
• GOV.UK: Architectural Decision Record Framework
• Martin Fowler: Architecture Decision Record
• adr-tools
• arXiv: One Size Fits All? An Empirical Comparison of ADR Templates
• ECSA 2024: Introducing Architecture Decision Records in Practice
• Distributed Pair Programming: A Systematic Literature Review
• Knowledge transfer in pair programming: An in-depth analysis
• Agile Alliance: Mob Programming - A Whole Team Approach
• 一休.com Developers Blog: ADRを1年間書いてみた感想
• ZOZO TECH BLOG: ZOZOFITにおけるADRを利用した意思決定を残す文化作り
• ENECHANGE Developer Blog: ADRsとGitHub Discussionsを使ってみた話