AI for Architecture Decisions: ADRs with AI

Use AI to document, evaluate, and improve architecture decisions. How to write better ADRs with AI and avoid costly design mistakes early.

Mark Rachapoom

March 26, 2026·8 min read

AI for Architecture Decisions: ADRs with AI

Architecture decisions are the most consequential choices in software development. They set constraints that persist for years. The monolith vs. microservices decision made in year one shapes hiring, deployment, and feature velocity in year five. The choice of database in a startup's early days affects what kinds of queries are possible long after the startup has scaled.

Architecture Decision Records (ADRs) are the practice of documenting these decisions — what was decided, why, what alternatives were considered, and what the consequences are. Most teams know they should write ADRs. Most teams don't write them consistently.

AI helps with both the decision quality and the documentation consistency.

What ADRs Are (and Why They Matter)#

An Architecture Decision Record is a short document that captures:

Context: What situation prompted this decision?
Decision: What was decided?
Status: Proposed, accepted, deprecated, superseded?
Consequences: What are the positive and negative consequences of this decision?
Alternatives considered: What other options were evaluated and why weren't they chosen?

ADRs serve several functions:

Decision quality: Writing the ADR forces clearer thinking
Knowledge continuity: New team members can understand why things are the way they are
Evolution management: When circumstances change, ADRs help identify what needs to be reconsidered
Accountability: Decisions have owners and rationale, not just outcomes

The problem: writing ADRs takes time, and the time is always when you're busy with implementation.

AI-Assisted ADR Writing#

AI dramatically reduces the friction of writing ADRs without reducing the quality.

Input to AI:

The decision you're making (in natural language)
The context (what prompted this decision?)
Your current thinking on the approach

Output from AI:

A structured ADR draft
Alternatives you might not have considered
Consequences (positive and negative) you may have overlooked
Questions to sharpen the decision

Example ADR Session#

Developer input: "We need to decide how to handle database migrations for the DenchClaw workspace. We're currently running DuckDB locally with no formal migration system. As we add features, the schema needs to evolve. I'm thinking we should use a SQL migration file approach (numbered files, run sequentially)."

AI generates:

# ADR-007: Database Migration Strategy
 
Date: 2026-03-26
Status: Proposed
Deciders: Engineering Team
 
## Context
 
DenchClaw uses DuckDB as its primary database for workspace data. As the product 
evolves, the schema needs to change: new tables, new columns, modified indexes. 
Without a migration strategy, these changes require manual intervention or 
destructive schema recreation.
 
The migration system must work with:
- DuckDB's embedded nature (no separate server process)
- Local-first deployment model (each user's machine has a separate database)
- Upgrade paths for existing users when the schema changes
 
## Decision
 
Use sequential SQL migration files with a migrations tracking table.
 
Migration files are numbered (001_initial_schema.sql, 002_add_contacts.sql, etc.) 
and stored in the workspace repository. A `_migrations` table in DuckDB tracks 
which migrations have been applied. On startup, the system runs any pending 
migrations in order.
 
## Alternatives Considered
 
### Alternative 1: TypeScript migration files (e.g., Knex migrations)
Pros: Programmatic, can execute logic, rollback support
Cons: Requires running Node.js for migrations, DuckDB TypeScript client less mature
Rejected: Added complexity without meaningful benefit for our SQL-centric operations
 
### Alternative 2: Schema diff tools (automatic migration generation)
Pros: Don't need to write migration files manually
Cons: Doesn't handle data migrations, can generate unsafe migrations
Rejected: Too risky for production data without manual review
 
### Alternative 3: Recreate schema on every startup
Pros: Always starts clean
Cons: Destroys user data on each update
Rejected: Not viable for production deployment
 
## Consequences
 
### Positive
- Simple, understood pattern (used by Rails, Flyway, Liquibase)
- Human-readable migration history
- Full control over what each migration does
- No runtime dependencies beyond DuckDB
- Easy to test migrations in isolation
 
### Negative
- Manual migration file creation required for every schema change
- No automatic rollback (must write rollback migrations manually)
- Migration file numbering requires coordination in multi-developer teams
- No validation that migration files match actual schema state
 
## Notes
 
Open questions:
1. How do we handle migrations that fail partway through? (DuckDB doesn't support DDL transactions)
2. Should we include a dry-run mode for migrations?
3. How do we handle the case where a user has modified their schema manually?

This ADR took 5 minutes with AI assistance. Without AI, a thorough ADR like this would take 30-45 minutes and often doesn't get written at all.

AI for Evaluating Architecture Decisions#

Beyond writing the ADR, AI helps evaluate the decision itself.

Before committing, ask AI:

"What are the failure modes of this architecture?"
"At 10x current scale, does this architecture hold up?"
"What architectural patterns commonly solve this problem? Are there better approaches than what I'm considering?"
"What's the migration path if this turns out to be wrong in 18 months?"

For the migration decision above, AI might surface: "DuckDB doesn't support DDL in transactions, which means if a migration fails partway through, the database can be in an inconsistent state. You should add pre-migration validation and a way to detect and recover from partial migrations."

This is the kind of consequence that might not be discovered until it causes a production problem, caught early by a thorough decision review.

ADR Lifecycle Management with DenchClaw#

DenchClaw stores ADRs as entries in a decisions object, with document bodies containing the full ADR text.

-- ADR status dashboard
SELECT 
  d.title,
  d.status,
  d.created_at,
  d.last_reviewed_at,
  DATE_DIFF('month', d.created_at, CURRENT_DATE) as months_since_created,
  CASE 
    WHEN d.last_reviewed_at < CURRENT_DATE - INTERVAL '12 months' 
      AND d.status = 'accepted' THEN 'Review Overdue'
    ELSE 'Current'
  END as review_status
FROM v_decisions d
ORDER BY d.status, d.created_at DESC;

ADRs that are more than 12 months old and haven't been reviewed get flagged. Technology changes. Business needs evolve. An ADR that was correct in 2024 might be wrong guidance in 2026.

When to Write an ADR#

Not every decision needs an ADR. A good heuristic:

Write an ADR when:

The decision is hard to reverse
Multiple people need to understand why things are the way they are
There are real tradeoffs between alternatives
The decision affects how the system can evolve

Skip the ADR when:

The decision is easily reversible with minimal cost
It's a technical detail within one module (not a cross-cutting concern)
There's a clear obvious right answer with no meaningful tradeoffs

For DenchClaw, ADR-worthy decisions include: database choice, deployment architecture, API versioning strategy, authentication mechanism. Not ADR-worthy: which sorting algorithm to use in a utility function.

The ADR Review Practice#

Monthly ADR reviews are underrated. The 30-minute session where the team reads recent ADRs and asks "is this still the right decision?" is where systems evolve thoughtfully rather than by accident.

AI helps structure the review:

"This ADR was written when we had 10 users. We now have 10,000. What changes?"
"This decision assumed X. X has changed. What needs to be reconsidered?"
"We've been living with this decision for 12 months. What have we learned?"

Frequently Asked Questions#

Should ADRs be stored in the git repository or separately?#

In the repository, in a docs/architecture/decisions/ directory. This keeps the decisions versioned with the code they describe. When the code changes significantly, the relevant ADR should be updated or superseded in the same PR.

How detailed should an ADR be?#

Long enough to capture the essential reasoning, short enough to actually be written. The template above (500-800 words) is a good target. ADRs that are 3 pages long don't get written consistently. ADRs that are 3 paragraphs don't capture enough context.