Architecture Decision Records (ADRs) are one of those practices every developer knows they should follow, but few actually do consistently. I finally found a way to make it effortless, using an AI agent to scan my codebase and generate ADRs automatically.

What are ADRs and why should you use them?

An Architecture Decision Record is a short document that captures an important architectural decision along with its context and consequences. The concept was popularized by Michael Nygard and has become somewhat of a standard in well-architectured software.

ADRs help teams:

• Remember why decisions were made months or years later.
• Onboard new developers who can quickly understand the reasoning behind the architecture.
• Avoid repeating the same debates when someone questions an existing decision.
• Track evolution of the system over time.

The problem? Writing ADRs requires time and discipline. In the heat of development, documenting decisions is often overlooked. By the time you remember, the context is fuzzy and the motivation unclear.

AI-Assisted ADR Generation

While working on my latest Umbraco project, I realized I had made numerous architectural decisions that existed only in my head or scattered across configuration files. I decided to use Claude Code to help me document them systematically.

The approach was simple:

1. Set up an ADR system with template.md and an overivew.md.
2. Let the AI agent scan my existing codebase.
3. Generate ADRs from what it finds based on template.

The instruction was even simpler than it sounds, all I told Claude was:

I want to scan my code base for high-priority ADR using the template described in template.md. Each individual ADR record should be created in folder /ADR/records using the pattern described in overview.md. The overview.md should have a table with title and link to each ADR record.

The result was far more that these 3 records but I've excluded most of them in this blog post to avoid unnecassary bulk. 

The Overview

The overview.md file serves as an index, containing:

• A brief introduction to what ADRs are.
• Instructions for humans and agents to follow when creating new records.
• A table linking to all existing ADRs with their status and date.

This makes it easy to browse all decisions at a glance and navigate to specific records.

Continuous ADR generation

The real power comes from making ADR generation a continuous process, not just a one-time scan. I added an instruction to my agents.md configuration:

Always create an ADR when changes are made to the codebase that affect the overall architecture.

This means when I'm working with the agent on a feature that involves architectural decisions the agent suggests creating an ADR after the implementation. The decision is documented while the context is fresh, and the agent handles the formatting and file creation, such as this example:

Conclusion

ADRs don't have to be time-consuming. With AI ADR generation, you can maintain consistent ADR record generation for all your projects. AI agents are excellent at finding and articulating architectual decisions and with the right instructions, they can ensure new decisions are captured automatically.

Try scanning your own project. You might be surprised how many undocumented decisions are hiding in plain sight.