In an earlier article, Architecture Decisions: Why One Option Is No Option, I argued that having a single architectural option is not a sign of clarity but a failure of the decision process.
Good architectural decisions require multiple viable options, clear trade-offs, and evaluation within a specific context. Yet in practice, architects choose the first “reasonable” solution: time pressure, personal experience, and delivery constraints bias decisions toward familiar patterns. Alternatives are poorly documented, if at all, and ADRs often become justification documents rather than actual decision records.
The hardest part is frequently not evaluating options, but finding them in the first place.
This is the gap I wanted to explore.
Why an ADR assistant, not “just another AI tool”
I recently built and deployed an Architecture Decision Record (ADR) tool using a Retrieval-Augmented Generation (RAG) approach.
Its scope is intentionally narrow. It does not attempt to replace architects, automatically choose the “best” architecture, or generate final decisions without human judgment. Instead, it focuses on one responsibility: helping architects surface multiple, relevant architectural options grounded in known patterns.
The assistant takes contextual information, constraints, and a tentative technology stack, retrieves relevant architecture patterns, and uses an LLM to generate options, not answers. The output is structured so it can be directly used as the basis for an ADR.
This mirrors how experienced architects work: exploring alternatives, comparing trade-offs, and making decisions with context in mind.
Why I deliberately started with keyword-based RAG
From a technical standpoint, starting with keyword retrieval was a conscious architectural decision. It allowed me to understand how retrieval influences generation, debug why certain patterns appear or do not, and control scoring and weighting. Most importantly, it enabled me to build a working system without introducing the additional complexity of embeddings and vector databases.
The limitations are obvious. Keyword retrieval does not handle synonyms, implicit reasoning, or unexpected phrasing well. But those limitations are also useful signals. They clearly show where semantic retrieval would add value—if the tool itself proves valuable.
The uncomfortable question: Is this solving a real pain?
Here is the honest reflection.
Despite publishing the blog, sharing the live application, and targeting architects, I saw little actual use. That leads to several possible interpretations. Perhaps architects do not see enough value in an ADR assistant. Maybe the problem resonates, but the framing or timing is wrong. It could also be that architects prefer static guidance, such as blogs and templates, over interactive tools, or that trust barriers still exist around AI-assisted decision making.
Before investing time in semantic search, feedback loops, or advanced ranking, I want to validate the problem, not optimize the solution.
I would genuinely value your input
If you are an architect, I would be interested in your perspective.
Do you struggle to generate multiple architectural options?
Would a tool that helps surface alternatives be useful, or do you prefer relying on experience, discussion, and manual reasoning?
At what point does AI assistance feel helpful in your architecture decision process?
You can try the ADR assistant here: Try the ADR assistant
Or simply share your thoughts—positive or critical. Both are equally valuable right now.
What comes next (or not)
If there is clear interest, investing in semantic or hybrid retrieval, richer pattern modeling, and feedback-driven ranking makes sense. If there is not, that is also a valid outcome. It tells me where not to invest time and hopefully helps refine my understanding of how an AI ADR assistant can help.
Either way, this experiment has already served its purpose. It forced me to create a keyword-based RAG system, test assumptions, and confront reality, which, ironically, is precisely what good ADRs are supposed to do.