HanLHo. - Fractional Architect & Software Product Engineer - adr

Grounded decision records from AI conversations

2025-09-02T00:00:00+00:00

If you've read some of my posts before or worked with me, you know I like using Architectural Decision Records (ADRs) for lots of reasons</a>. To me the most important one is documenting the why of a decision.

If you've worked with AI models before, you've probably asked them for options when brainstorming solution ideas when you're not sure about direction. In this situation, I've found it quite easy, maybe even more logical, to document the decision in a decision record with help from the AI model you have been working with. After all, you got feedback from it anyway.

This post briefly explains how I use Claude Code to write decision records (not necessarily architectural ones) when it's helped me make a decision. My goal isn't to dive into an elaborate investigation into the pros and cons of this approach, but I will touch upon a few points. The process is not specific to Claude Code but can be adapted to other AI models or tools as well.

Here's the process I've been following:

1. Ask for the decision record during the conversation

After going back and forth on options and reaching a decision, I ask something like:

Given your feedback, I think Option 2 is the way I want to implement. Principally I do not want to complicate things with 2 tools at the moment. Before implementing, summarise this into an ADR in the 'adr/' directory as a way of confirming our mutual understanding. So, write an ADR first, then ask me to confirm the ADR. Once I do, continue implementing. </code></pre> The phrasing is a bit sloppy, as this is what I actually wrote in my recent changes, but that's OK, Claude Code can work with this. 2. Review and edit the generated draft What it comes up with initially is actually pretty good. A lot will depend on the conversation you had with it and the input you gave it, of course. But the decision record mostly contains what was discussed and decided quite well. The text will be structured like an ADR even without me having to explain what an ADR is. It even picked up the decision record's next number too. Usually content editing is needed, but having a complete draft to start with makes a big difference instead of starting from a blank page. So after the draft is written, I edit it mostly on content only. 3. Use as implementation foundation When done, the decision is basically documented and it can serve as the basis of our next step. To make the continuation based on the decision record only, at this point you could clear or restart the Claude Code session to start fresh. This last step is meant to ground the decision record in reality. When you include the decision record as basis for implementation, it becomes living documentation that creates a feedback loop. During implementation you may encounter issues not anticipated during the decision making process. These can then be documented in the decision record, creating a continuous improvement cycle. I often use my home projects as playgrounds to experiment with new ideas, technologies, and methodologies I want to try out because they're new to me or because I want to confirm they're still useful. This is why most of my home projects serve two purposes: build the thing and apply what I think are best practices. In this particular project, I felt the need to create decision records. They aren't necessarily architecture related decisions but more decisions I'd like to document to remember why I went this way. I mainly make use of the markdown format of ADRs to document my decisions. Generally speaking, this is mostly an experiment at the moment. I'm trying this out in the setting of personal projects, but I think it may lower the bar for writing decision records in general. Not everyone wants to go to great lengths to record decisions, even if they see the value. Personally, I think it doesn't need to take a lot of time to document a decision, yet I often end up spending much more time on it than I anticipated or hoped for when I started writing one.

Here</a> is a decision record example for those interested. It is written by an LLM mostly. I know this may be controversial, but it is also useful. I do not think this is 'AI slop', if you review it and it all makes sense, I don't see much need for a complete rewrite. Having a documented decision is worth more than not documenting because it was written by AI. I haven't tried this in a team or organisational setting, but I'm curious to see how it works out and how people would feel about it. In any case, whoever created the decision record with help of an AI is always responsible for the decision and its recording.

Also, "working with an LLM replaces thinking" is an often heard argument. I agree and it's a reason for concern for me too, the impact on my own thinking. But an LLM also comes up with good ideas. It is easy and tempting to simply accept what's there. Maybe not all decisions require deep thinking though, and we just want to note down why we're doing the thing we're doing this way.

I am also thinking it may be useful to add to the decision record to what extent an LLM was used to generate the content. Firstly it will get it out of the way when people are suspicious of AI being used and to what extent. I think this is comparable to time or other constraints one has when writing ADRs or decision records in general: this may be worthwhile to document too. Sometimes there is not enough time to think deeply about the decision or consider more options and you have to make a decision with quite some unknowns. In these cases I recommend documenting this in the decision record too.

Finally, there are quite some interesting things that can be done next. When working with Claude Code, if you would create decision records more often it makes sense to create a command to use as 'saved prompt'. I actually created an agent for this as well (to try out agents mostly, I admit).

I've written about ADRs before, if you want to read more about them:

Less Mentioned Benefits of Architecture Decision Records</a> </li>

Ground Your ADRs with a Verification Section</a> </li> </ul>
Thank you for reading, Hans

Ground Your ADRs with a Verification Section

2024-12-11T00:00:00+00:00

Making architectural decisions is one thing, but have you ever wondered how to make them more effective? Adding a Verification section to Architecture Decision Records (ADRs) can make the difference. This simple addition bridges the gap between theory and practice, making decisions actionable and measurable.
If you're new to ADRs, check out my post on their benefits</a> first.
Common ADR Challenges</h2>
Architecture Decision Records (ADRs) are a valuable tool for capturing architectural choices. However, they can suffer from the following weaknesses:

Decisions can be made, or become, detached from implementation </li>

Intent and success criteria remain vague or unmeasurable </li> </ol>
These challenges can lead to:

Architectural decisions that exist only on paper </li>

Difficulty in assessing whether decisions are being followed </li>

Missed opportunities for feedback and improvement </li> </ul>
Introducing Verification</h2>
Adding a 'Verification' section to ADRs helps ground these decisions in reality and improve their quality. This section details how decisions will be evaluated or implemented, creating a clear path from decision to implementation.
Writing an ADR is often only the beginning, not the end. Establishing feedback loops helps to crystallise our decisions in actual implementation.
Grounding Architectural Decisions in Reality</h3>
It is a good idea to state goals in measurable and verifiable ways, and this applies equally to architecture and engineering. This is similar to writing requirements in parallel with the tests for these requirements. Or how writing code can put an analysis to the test. Each of these practices grounds our work in reality and provides feedback on our intentions.
Architecture decisions benefit from a similar grounding. Just as business analysts and developers can collaborate through behavioural tests, architects and developers can collaborate through verification criteria. More broadly, regardless of roles, the architecture function benefits from verification criteria. This creates反馈 loops that improve quality.
Importantly, verification works in both directions. Architecture and implementation connect and as such developers engage with the architecture and in return the architect receives feedback on what is working and what is not. When decisions aren't being acted upon, it becomes visible, which is a sign to investigate why and adapt.
A key benefit of keeping verification in mind: ADRs become more actionable and effective.
Verification Approaches</h2>
You might think this adds substantial work to your process. Not necessarily so. Verification methods can range from simple to sophisticated. Different architectural decisions require different verification approaches. Or you may, to get started, decide to go for a very light-weight approach.
Choose an approach that matches your context and needs. Here are some options:

Ask questions: the simplest approach uses straightforward questions for self-assessment. </li>

Automated tests / fitness functions: integrate checks in your development pipeline, look for ways to assess architectural characteristics objectively. </li>

Define metrics: what can you measure to determine if decisions are effective? </li>

Architecture Hoisting: the most comprehensive and strict approach, as described by George Fairbanks: </li> </ol>

"Architecture hoisting is a stricter kind of architecture-focused design. When following an architecture hoisting approach, developers design the architecture with the intent of guaranteeing a goal or property of the system. Guarantees are difficult to come by in any kind of software design, but architecture hoisting strives to guarantee a goal or property through architecture choices. The idea is that once a goal or property has been hoisted into the architecture, developers should not need to write additional code to achieve it." </blockquote>
Let's see some examples.
Simple</h3>
Suppose the recorded decision is to put all code in a mono-repo. Then the verification step could be as simple as:
## Verification Is your service in our mono-repo <include name>? </code></pre> This looks too easy right? In some cases it simply can be. Especially if your ADRs apply to multiple teams, and verification is not handled centrally, your verification tends to be more questions or check-based than actual steering towards an implementation. Self-Assessment</h3> For another example, suppose your cross-team decision is to adopt Continuous Delivery: ## Verification - Is the CI pipeline automated? - Can you deploy to production without manual steps? - If not, what manual gates are in place? - Are feature flags used for in-progress work? - Are branches short-lived? </code></pre> Note the self-assessment tone. This style can be adopted when architecture is an enabling and supporting function. Automated</h3> An example requiring effort but providing more guarantees to compliance: Suppose we are all working in the previously mentioned mono-repo and discover that teams are not respecting service boundaries. We decide to establish naming conventions to be able to enforce no inappropriate, accidental dependencies are created. We could again simply ask a question in the Verification section if naming conventions are followed, but automating this checking is relatively easy, so we decide to automate this check. Here we make compliance with our ADR automatic by hoisting the decision in our way of working. The verification section in the initial ADR may then look like this: ## Verification A dependency checker will be written and integrated in our build tooling for each service. - Are all of your services' build tooling integrated with the dependency checker? </code></pre> **Roles and organizational structures can heavily influence the verification section. If you have, say, a Developer Experience Team they may likely work with the teams and makes sure this gets integrated in their CI-pipeline. Other times seniors in the teams may take this upon them. Ideally these responsibilities are made clear in the Verification section as well. More examples of self-assessment questions can be found at John Lewis' Software Engineering Principles Self-Assessment</a>. Implementing the Verification section</h2> Verification</code> is my recommended term because of this definition: [!quote] "VERIFY implies the establishing of correspondence of actual facts or details with those proposed or guessed at." (Merriam-Webster) </blockquote> However, depending on your environment a different name could be a pragmatic choice. Compliance</code> often resonates better in regulated environments. I have used 'Validation' before. While regularly validating or evaluating our decisions is good practice, here we are aiming to put a system in place to check if our decisions are implemented. Here is an example of a Verification</code> section you could include in your ADR template: ## Verification How will we ensure compliance with this decision? Consider: - Questions for self-assessment - Specific metrics - Verifications in the form of tests or fitness functions - Implementation guidance - Making it easy to adopt </code></pre> Based on this, a more extended example for a Continuous Delivery ADR: ## Verification Questions: - Is the CI pipeline automated? - Can you deploy to production without manual steps? - Are feature flags used for in-progress work? Metrics: - Deployment frequency (target: daily) - Lead time for changes (target: < 1 day) - Change failure rate (target: < 15%) Implementation: - Teams must implement automated deployment, Delivery Platform Team will assist - Regular metrics reporting (data can be collected manually) </code></pre> Considerations</h2> Won't adding this section complicate writing these ADRs? Well yes, there is another section to write and you need to think about how to make your ADRs more effective. Making them more effective and actionable is something you would want regardless, so the thinking part about this should not be skipped. Instead, incorporate verification thinking while writing the ADR: state decisions in measurable and verifiable ways. Now if you ask me, is it better to have a record of a decision without this section than not having one at all? Then my answer would be yes. Don't let perfection stop you from adopting or recording your decisions - use verification to improve them over time. Conclusion</h2> Architecture benefits from being grounded in implementation. Adding a Verification section to your ADRs creates feedback loops and improves their quality. The verification section serves as more than a checklist. It: Connects architecture with implementation </li> Provides a mechanism for feedback in both directions </li> Reveals when decisions aren't being acted upon </li> Makes ADRs more actionable and effective </li> </ul> This grounding helps prevent architectural decisions from remaining theoretical or becoming shelfware.
Less Mentioned Benefits of Architecture Decision Records 2024-11-27T00:00:00+00:00 Teams adopt Architecture Decision Records</a> (ADRs) to document decisions, avoid revisiting settled matters, onboard newcomers, adapt to changing circumstances, and sharpen their thinking. However, there are several other valuable benefits that often go unnoticed. A clear decision process</h4> The most basic of these: having a clear decision process beats having none at all. Objective evaluation</h4> ADRs provide a framework to evaluate design choices objectively. Instead of getting caught in personal debates, we focus on documenting and analysing technical trade-offs together. "Developers on the same project will often disagree about design options. The disagreements can often be resolved, or at least reduced from a boil to a simmer, by exposing the decision making process. If the disagreement is simply that one developer thinks option A is better, and another thinks option B is better, it is hard to choose. When the rationale for each is expressed using the template, it may be clear that A helps usability, while B helps testability. This does not immediately resolve the disagreement, since both usability and testability are desirable, but now the question is which quality is a higher priority for the project. It casts the problem as an engineering or requirements decision, not as a judgment about who is the better designer, and can help take egos out of the dispute." (George Fairbanks, Just Enough Software Architecture) </blockquote> Grounding in reality</h4> Through ADRs, engineering roles could become more invested in architectural decisions, while architect roles stay connected with practical implementation realities. This grounds architectural decisions in practical reality, bridging vision and practice. Preventing paralysis</h4> When teams can't trace why and by whom past decisions were made, decision paralysis could occur. ADRs overcome this by providing the documented context teams need to more confidently evolve their systems. Efficiency</h4> Capturing architectural decisions through ADRs requires minimal effort compared to the time and resources teams spend rediscovering or reconstructing the reasoning behind past choices. This investment in documentation prevents costly archaeological expeditions through old emails, meetings, and code. "The cost of recording knowledge is small compared to the cost of acquiring knowledge." (Software Development Pearls, Karl Wiegers) </blockquote> Further Reading</h4> If you like to learn more about ADRs, here are some of my favorite online resources: The GitHub adr organization</a> provides additional motivation, tooling, and pointers to public documentation. </li> Olaf Zimmermann's Architectural Decisions (ADs) and Software Architecture</a> offers insights into the practice. </li> </ul>

Grounding in reality</h4>
Through ADRs, engineering roles could become more invested in architectural decisions, while architect roles stay connected with practical implementation realities. This grounds architectural decisions in practical reality, bridging vision and practice.</p>

Preventing paralysis</h4>
When teams can't trace why and by whom past decisions were made, decision paralysis could occur. ADRs overcome this by providing the documented context teams need to more confidently evolve their systems.</p>

HanLHo. - Fractional Architect & Software Product Engineer - adr

Grounded decision records from AI conversations

Ground Your ADRs with a Verification Section

Less Mentioned Benefits of Architecture Decision Records

HanLHo. - Fractional Architect & Software Product Engineer - adr

Grounded decision records from AI conversations

Ground Your ADRs with a Verification Section

Common ADR Challenges</h2> Architecture Decision Records (ADRs) are a valuable tool for capturing architectural choices. However, they can suffer from the following weaknesses:</p> Decisions can be made, or become, detached from implementation</p> </li>

Less Mentioned Benefits of Architecture Decision Records

Objective evaluation</h4> ADRs provide a framework to evaluate design choices objectively. Instead of getting caught in personal debates, we focus on documenting and analysing technical trade-offs together.</p>

Grounding in reality</h4> Through ADRs, engineering roles could become more invested in architectural decisions, while architect roles stay connected with practical implementation realities. This grounds architectural decisions in practical reality, bridging vision and practice.</p>

Preventing paralysis</h4> When teams can't trace why and by whom past decisions were made, decision paralysis could occur. ADRs overcome this by providing the documented context teams need to more confidently evolve their systems.</p>

Further Reading</h4> If you like to learn more about ADRs, here are some of my favorite online resources:</p>

Grounding in reality</h4>
Through ADRs, engineering roles could become more invested in architectural decisions, while architect roles stay connected with practical implementation realities. This grounds architectural decisions in practical reality, bridging vision and practice.</p>

Preventing paralysis</h4>
When teams can't trace why and by whom past decisions were made, decision paralysis could occur. ADRs overcome this by providing the documented context teams need to more confidently evolve their systems.</p>