Most ADRs written with AI today are garbage. They look professional, use the right headings, and sound authoritative. But they share one fatal flaw: they suffer from the “Hallucination of Consensus.” When you ask a single LLM to write a technical decision record, it tries to please you by confirming your biases rather than challenging your architectural assumptions.
I’ve spent 11 years in strategy consulting and product marketing, and I’ve seen enough “perfect” decision memos fail in production to know one thing: an ADR that doesn’t clearly define the cost of its own failure is just a work of fiction.
If you want to use AI to actually help you make better architectural decisions, you need to stop treating it like a writer and start treating it like a team of analysts. Here is how to build an ADR workflow that catches trade-offs instead of glossing over them.
1. The Problem: The "Yes-Man" Model
The primary failure mode of a single-model ADR is confirmation bias. If you prompt an LLM with your preferred solution, it will dutifully expand on why that solution is great. It will ignore the latency trade-offs, the maintenance overhead, and the integration bottlenecks because it’s optimizing for structural coherence, not technical viability.
To avoid this, you need to force a confrontation between models.
2. Build Your Context Fabric
Before you draft a single word, you need a Context Fabric. This is your shared memory—a unified document repository that includes your current tech stack, recent performance logs, existing technical debt, and team capacity.
When you feed this into your AI orchestration layer, you’re providing the “Constraints” portion of your ADR. Without this, your model will hallucinate a "greenfield" architecture in a "brownfield" reality.
What could break this? If your Context Fabric is stale, your AI will recommend solutions that you deprecated six months ago. Always verify your context before you hit "generate."
3. Orchestration: The @mention Workflow
Stop using a single chat window for everything. Modern orchestration via @mention allows you to assign roles to specific models based on their strengths. Don’t use a general-purpose model for the entire ADR lifecycle. Use a specialized hierarchy:
- @Analyst (e.g., Claude 3.5 Sonnet): Used for logical reasoning and parsing complex trade-offs. @Validator (e.g., GPT-4o): Used for sanity checks and "What would break this?" stress testing. @Writer (e.g., Llama-3-70B): Used to synthesize the final documentation into clean, readable ADR format.
The Orchestration Table: Role Allocation
Role Task Primary Responsibility @Analyst Identifying Constraints Translating Context Fabric into technical requirements. @Devil’s Advocate Stress Testing Searching for hidden failure modes and trade-off gaps. @Writer Final Synthesis Formatting the final ADR template.4. Implementing "Modes" of Decision Making
You cannot use the same prompt for a trivial component replacement and context fabric ai memory a core infrastructure rewrite. You need to switch your "Decision Mode."
The "Defensive" Mode (High Risk)
When the decision is mission-critical, your orchestration must mandate a cross-model verification step.
@Analyst proposes Option A, B, and C. @Devil’s Advocate is tasked with "Why will Option A fail in 18 months?" @Synthesizer writes the ADR only after the @Devil’s Advocate signs off on the risk mitigation strategy.The "Velocity" Mode (Low Risk)
For routine configuration updates, keep it simple. Use @Writer to fill out a standard ADR template using your existing style guide. Skip the heavy cross-validation, but always include a "Known Risks" section populated by the AI.
5. Cross-Model Verification (Catching the Hallucination)
Hallucinations aren't just "lying." They ai for legal teams are statistical errors in predicting the next token. When a model predicts that "Microservices will definitely reduce latency," it is hallucinating a benefit based on training data that ignores your specific network overhead.
To catch this:
Always prompt your @Validator to output only potential points of failure. If the @Validator can’t find a downside, you aren’t looking hard enough, or the model is being too agreeable. Force it to be contrarian. Use a prompt like: "Review the following ADR. List the top 3 ways this architecture will break under 10x load, regardless of how well-structured the argument is."
6. Constructing the ADR: The "One Direction" Brief
An ADR is a decision record, not a suggestion box. If your ADR ends with "we could do X or Y, depending on the team's preference," you have failed. The final output of your orchestrated workflow must be a Decision Brief that leads to one recommended direction.
Your template should look like this:
- Status: (Draft/Proposed/Accepted/Deprecated) The Problem: (Context Fabric summary) The Decision: (The one recommended direction) The Trade-offs: (The critical section. AI often minimizes this; force it to list 3 negative externalities). The Failure Mode: (What would break this?)
The "What Would Break This?" Test
I ask this every time I review an AI-generated ADR. If the AI provides an answer like "poor implementation," reject it. That’s a lazy answer.
You want technical failure modes:
- "Database connection pooling limits during retry storms." "Increased binary size impacting cold-start times in Serverless functions." "Synchronization lag between the read-replica and the primary in multi-region deployments."
If your AI isn't giving you this level of granularity, it’s not helping you—it’s just formatting your ignorance. Use your @mention orchestration to drill down. Ask the @Analyst to look at the specific constraints, and ask the @Validator to simulate the failure points.
Final Thoughts: Don't Outsource Judgment
AI is a phenomenal mirror. It reflects your own biases back at you with remarkable eloquence. If you go into an ADR process wanting to choose a specific tech stack, the AI will build a case for it. If you use it to find the gaps in your thinking, it will keep you from making catastrophic decisions.
Use your Context Fabric, rotate your models via @mention, and never accept a document that doesn’t have a clearly defined "Failure Mode." Everything else is just noise.
Now, go re-read your last ADR. What would break it?