What is an Architecture Decision Record (ADR)?

ADR is a lightweight documentation practice proposed by Michael Nygard in 2011 that records design decisions with three elements — Context, Decision, and Consequences — as sequentially numbered Markdown files in a project repository.

Why did ADRs fall out of use despite being recommended by Thoughtworks?

Human teams couldn't keep up with documentation at sprint velocity. Entries were forgotten, content went stale, and ADRs were shelved as "ideal in theory, too heavy in practice."

How is the AI coding problem similar to what ADRs were designed to solve?

AI agents lose design context across sessions, just as human team members lost track of decision rationale across sprints. Both result in inconsistent approaches and duplicated effort.

Can AI solve the ADR maintenance problem?

Yes — if the AI agent itself creates and updates ADRs, the human bottleneck that caused ADRs to fail is eliminated. However, traditional Markdown-based storage still has searchability and token efficiency limitations.

What are the limitations of Markdown-based ADRs for AI coding?

Poor searchability across dozens of files, excessive token consumption when loading all files into the LLM context, and no guarantee that the AI agent will consistently read or update them.

人類には早すぎたマネジメント手法、ADR

ソフトウェア開発の歴史には、「正しかったのに普及しなかった」手法がいくつかあります。ADR（Architecture Decision Record）もその一つかもしれません。

アジャイルとともに生まれた記録手法

ADRは、2011年にMichael Nygardが発表したブログ記事で広く知られるようになった手法です。高速にスプリントを繰り返すアジャイル開発において、設計判断の「理由」がチーム内で共有されず失われていく——その課題に対する解として提案されました。

記録の方法はシンプルです。プロジェクトのdocs/adrディレクトリに、ADR-001.mdのようにMarkdownファイルを通し番号で追加していく。各ファイルには「背景」「決定事項」「結果」の3要素を記述します。軽量で、バージョン管理にも乗る。Thoughtworksが2018年のTechnology Radarで「Adopt」に分類したことで注目度が上がりましたが、実際の現場で定着したかというと、そうはなりませんでした。

理由はシンプルで、人間がドキュメントを更新し続けるのが難しかったからです。スプリントのスピードに人手の記録作業が追いつかない。記述を忘れ、内容が陳腐化し、やがて誰も参照しなくなる。ADRは「理想的だが運用が重い」手法として、多くのプロジェクトで静かに棚上げされました。