When I ask AI to implement a feature, I do not just describe what I want — I share the decisions that shaped the system. This changes everything about how AI interacts with your architecture.
Most architects write Architecture Decision Records (ADRs) for documentation and governance. But ADRs serve another critical purpose: they provide AI with the "why" behind your architecture, preventing it from re-litigating issues your team already decided. Without decision context, AI operates in a vacuum, proposing changes that ignore past reasoning and violate established principles.
This guide shows you how to transform ADRs from documentation overhead into an AI governance mechanism. You will learn the ADR format that AI respects, when to include decision context in prompts, and how to position AI as a decision proposer rather than an autonomous decision-maker.
The Problem: AI Without Decision Memory
Six months into a document processing project, we had decided on phase-based directory organization after extensive discussion. The structure provided quality gates between preparation, editing, and deployment phases. Status visibility was clear. Archive-readiness was built in.
Then I asked AI to implement a new feature.
AI suggested a "simpler" flat directory structure. The suggestion was technically valid but ignored every reason we chose phase-based organization. I spent time explaining our constraints. AI accepted them and implemented correctly.
Two weeks later, different prompt, same suggestion. I re-explained the reasoning. AI complied again.
This happened three times before I realized the pattern. I was wasting significant time re-litigating a decided issue because AI had no memory of past decisions. The decision existed in my head, not in a format AI could consume.
Architecture Decision Records: The Format That Works
The solution lies in Architecture Decision Records — but not ADRs as passive documentation. ADRs as active decision context that you share with AI.
The ADR Structure
An ADR captures three essential elements:
Context: What situation required a decision? What constraints existed? Why was a decision needed?
Decision: What was decided? Be specific about the choice made.
Consequences: What trade-offs were accepted? What benefits gained? What new constraints introduced?
This structure works because it captures reasoning, not just outcomes. Future readers — including AI — understand not just what was decided but why.
Here is the template I use:
# ADR-001: Phase-Based Document Processing Organization
**Status**: Accepted
**Date**: 2024-03-15
**Deciders**: Architecture Team
## Context
Document processing workflow requires clear status visibility and quality gates. Previous flat structure made it difficult to identify processing stage and caused deployment issues when incomplete documents were archived.
## Decision
Implement phase-based directory organization:
- `/preparation/` - Documents being prepared for processing
- `/editing/` - Documents in active editing phase
- `/deployment/` - Documents ready for final deployment
- `/archive/` - Completed documents
## Consequences
### Positive
- Clear status visibility at filesystem level
- Natural quality gates between phases
- Archive-ready structure prevents incomplete deployments
### Negative
- Slightly more complex file management
- Requires phase transition logic
### Neutral
- File paths become longer but more descriptive
The power is in the "why" — the context and consequences. AI respects documented reasoning more than arbitrary rules.
Sharing Decision Context with AI
After creating that ADR, I tested whether providing decision context would prevent re-litigation. I asked AI to implement a feature that might trigger the same "simplification" suggestion.
But this time, I included the ADR in my prompt context:
"Implementation must respect existing architectural decisions. See ADR-001 for directory organization rationale."
AI implemented the feature within the phase-based structure. No suggestion to simplify or restructure. When I asked why it used phase-based organization, AI referenced the ADR: "Based on ADR-001, phase-based organization provides quality gates between preparation, editing, and deployment."
The ADR provided context that prevented re-litigation. Decisions with rationale proved more powerful than rules without explanation.
When to Include ADRs in Context
Not every AI interaction needs decision context. Use this guide:
| Situation | Include ADRs? | Rationale |
|---|---|---|
| Feature touches decided pattern | Yes | Prevents re-litigation |
| New feature in decided area | Yes | Ensures consistency |
| Greenfield implementation | Maybe | Only if precedent exists |
| Asking for suggestions | Depends | May want fresh perspective |
| Refactoring request | Yes | Respect constraints |
The key insight: AI operates on provided context. Without decision context, AI suggests changes that ignore past reasoning. With ADRs in context, AI implements within decided constraints.
ADRs as Case Law for Architecture
Think of ADRs like case law for architecture. Each ADR establishes precedent that future decisions should respect. Just as lawyers cite past cases to argue current positions, architects cite past ADRs to justify current approaches.
Case law prevents re-litigating settled issues. Each new case builds on precedent rather than starting from first principles. ADRs create the same efficiency — new features build on decided patterns rather than reconsidering everything.
The analogy breaks down in one important way: legal precedent is binding, but ADRs can be superseded when context changes. Architecture should not be bound by outdated decisions. But until context changes, precedent should guide implementation.
When AI Proposes Better Decisions
Testing the boundary between AI as implementer and AI as proposer, I was working on event handling patterns when AI suggested an approach that genuinely seemed better than our current pattern. Not re-litigation — a new idea with merit.
But accepting it would change our established architecture without documentation.
I told AI: "If you believe this approach is better than our current pattern, write an ADR proposing the change. Include Context (current state and limitation), Decision (proposed change), and Consequences (trade-offs)."
AI produced a well-structured ADR proposing the change. We reviewed it with the team. The proposal had merit but overlooked a constraint. We refined the ADR together and accepted a modified version. The decision was documented for future reference.
This established an important principle: AI can be a decision proposer, not just an implementer. But proposals must follow ADR format for proper review. Decision authority remains with humans. The process ensures changes are intentional, not accidental.
ADRs as Meeting Minutes for Decisions
ADRs are like meeting minutes for architectural decisions. Without minutes, attendees remember different things. Without ADRs, team members remember different decisions. Documentation creates shared truth.
But here is the critical insight: "We discussed this" is not a decision. Decisions need recording to be real. AI was not in the meeting — it needs the minutes (ADRs) to understand what was decided.
The analogy has limits. Meeting minutes record discussion. ADRs record decisions. Not all discussions become decisions, and not all decisions need the full discussion recorded. Focus on decisions that shape implementation.
Implementation: Your ADR-AI Integration
Start with your next architectural decision. Before implementation begins, document it as an ADR using the Context-Decision-Consequences structure.
When AI assists with implementation in that area, include the relevant ADR in your prompt context. State explicitly that implementation must respect documented decisions.
Observe the difference. AI will implement within decided constraints rather than proposing alternatives. Re-litigation drops to near zero for documented decisions.
For our document processing system, we now have nearly 30 architectural decisions documented and available for AI context. The pattern works across any domain — the ADR format is framework-agnostic, and the integration pattern works with any AI provider.
Beyond Documentation: ADRs as Governance
This transforms how you think about ADRs. They are not just documentation for future developers. They are governance mechanisms for AI-assisted development.
Decision documentation benefits any team, not just AI-assisted ones. But AI amplifies the value because it operates on explicit context rather than implicit understanding. What humans might infer from architecture patterns, AI needs stated explicitly.
The result: architecturally consistent AI outputs that respect your established patterns and constraints. No more re-litigation. No more explaining the same decisions repeatedly. AI becomes an implementer within your architectural framework rather than a source of architectural drift.
Conclusion
When you share decisions with AI, you transform it from a feature generator into an architectural partner. ADRs provide the decision context that prevents re-litigation and ensures consistent outputs.
The three key concepts work together: Architecture Decision Record Format captures reasoning alongside decisions. Decision Context in Prompts prevents AI from ignoring past decisions. AI as Decision Proposer allows AI to suggest changes while maintaining human decision authority.
Start with your next architectural decision. Document it as an ADR. Include it in your AI context. Watch how decision context changes the quality and consistency of AI outputs.
What decision would you document first as an ADR? Share your experience with ADRs and AI in the comments.
Resources
Watch the video for the complete framework and real examples of ADRs preventing AI re-litigation: https://www.youtube.com/watch?v=JrxXqAxImpA
How has AI challenged your established architectural decisions?