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 — The Management Technique That Was Too Ahead of Its Time

Software development history has its share of practices that were "right, but never caught on." ADR (Architecture Decision Record) may well be one of them.

A Documentation Practice Born Alongside Agile

ADRs became widely known through a 2011 blog post by Michael Nygard. In agile development — where teams iterate rapidly through sprints — the reasoning behind design decisions was being lost. ADRs were proposed as a lightweight solution.

The approach is straightforward: add Markdown files like ADR-001.md sequentially in a docs/adr directory. Each file captures three elements: Context, Decision, and Consequences. Lightweight, version-controllable, and easy to start. Thoughtworks classified ADRs as "Adopt" in their 2018 Technology Radar, giving them a brief moment in the spotlight. But in practice, they rarely stuck.

The reason was simple: humans couldn't keep up with the documentation. Sprint velocity outpaced manual record-keeping. Entries were forgotten, content went stale, and eventually no one referenced them. ADRs were quietly shelved as "ideal in theory, too heavy in practice."

A Familiar Problem in AI Coding

Here's where it gets interesting: the problems AI coding faces today are strikingly similar to what ADRs were designed to solve.

AI agents lose context across sessions. They start a new session unaware of design decisions made in the last one, writing code with a completely different approach. The same problem human teams had — "the rationale behind decisions isn't being shared" — is now playing out in human-AI collaboration.

And here's the twist: the very reason ADRs failed — "humans can't keep writing documentation" — can now be resolved by AI. If the AI agent itself records and updates design decisions, the human bottleneck disappears.

But Markdown Alone Isn't Enough

AI authoring ADRs addresses the maintenance problem. However, the traditional Markdown file approach has its own limitations.

As dozens of files accumulate under docs/adr, finding the right ADR at the right moment becomes difficult. Loading all files into the context window inflates token consumption and can degrade LLM reasoning quality. ADRs were "ahead of their time" for humans — and now there's an opportunity to redesign them in an AI-native way.

In the next article, we'll introduce how sqlew approaches this challenge.

ADRを再定義するsqlew：AIネイティブな設計記憶のかたち

Markdownベースの従来のADRには検索性やトークン効率の課題がありました。sqlewはRDBMSとClaude CodeのHooksを活用し、ADRをAIネイティブな形で再設計します。プランモードでの自動サジェストと強制記録の仕組みを...