バイブコーディングとADR

概要

• バイブコーディング(vibe coding)は、AIエージェントに目標を伝えて実装を任せる開発スタイル
• 速い反面、「なぜその設計にしたか」という意思決定がAIとのやり取りの中に閉じてしまい、コードにもコミットにも残らない
• この欠落を埋めるのに ADR(Architecture Decision Record)が効く

バイブコーディングで失われるもの

• コードは「何をしたか」は残すが「なぜそうしたか・何を捨てたか」は残さない
• AIはセッションをまたぐと文脈を失い、前回と矛盾する判断をしやすい
  • 例: あるセッションでBを採用したのに、次のセッションでは事情を知らずAに戻してしまう
• 人間もレビューのたびに「なぜこうなっているのか」を問い直すことになる
• 決定の速度が上がるほど、未記録の決定が積み上がり、後から理由を復元できなくなる

なぜADRが効くのか

• 決定を「背景・決定・影響・状態」の1ファイルとして外部化し、人にもAIにも読める形で残す
• AIへ毎回読ませる素材になる(コンテキストの再注入)ので、過去の判断を踏襲させやすい
• 「やらない」判断や代替案の取捨も残せるため、同じ議論を蒸し返さずに済む
• 覆すときは新しいADRで上書きし、旧ADRの状態を Superseded にすることで履歴が追える

AIと組むときの運用

• docs/adr/NNNN-タイトル.md の連番で1決定1ファイルにする
• 対象は方針・トレードオフ・「やらない」判断など、後から「なぜ?」となるもの
  • 単なる実装詳細やバグ修正は対象外
• AIへの常設指示(AGENTS.md や CLAUDE.md 等)からADRの存在と運用を前提として参照させる
• セッション開始時やPR作成時に、関連するADRを読ませる/紐づける
• 大きな方針をドラフトで実行したら、要点をADRとして確定させ、ドラフトは経緯ログとして残す

最低限のテンプレート

# 0001. タイトル

> Status: Accepted

## Context
なぜこの決定が必要か、制約は何か

## Decision
何を選んだか

## Consequences
利点・欠点・トレードオフ、今後の前提

まとめ

• バイブコーディングは実装を速くするが、意思決定の記録は自動では残らない
• ADRは「なぜ」を外部化し、人とAIの双方が同じ前提で作業を継続するための最小コストの仕組みになる

参考

• Documenting Architecture Decisions - Michael Nygard
• Architecture decision record (adr.github.io)