I Taught My AI Agent How to Write Architecture Decision Records

Most teams don't write ADRs. The ones that do usually stop after a few months. Not because the practice is bad — it's that the activation energy is too high for the perceived reward. You're deep in implementation, you just made a decision about database strategy, and the last thing you want to do is context-switch into writing a structured document about the decision you already made.

So it doesn't get written. Six months later, a new engineer asks "why did we choose DynamoDB?" and nobody remembers the tradeoffs. The decision gets relitigated. Time gets burned. This cycle repeats across every team I've worked with.

I built a skill to fix this.

The Problem With ADRs Isn't the Format

Architecture Decision Records have been around for years. The MADR template is clean. The concept is sound. The problem is execution.

Most teams fail at ADRs for three reasons:

1. No quality gate on the front end. Teams write ADRs before the decision is actually ready — stakeholders haven't been identified, only one option has been considered, and the problem statement is vague.
2. No quality gate on the back end. ADRs get marked "accepted" without evidence that the decision will work, without stakeholder agreement, and without a plan to verify it later.
3. The writing itself is hard. Good ADRs require a specific discipline — balancing brevity with completeness, documenting tradeoffs honestly, avoiding the eleven anti-patterns that make ADRs useless.

Olaf Zimmermann at OST has spent years researching this. He developed frameworks for each of these failure modes: START criteria for readiness, ECADR criteria for completeness, and a catalog of anti-patterns for writing quality. The research is solid. But it lives across five academic blog posts that nobody reads during the heat of a sprint.

What I Built

I distilled Zimmermann's methodology into a reusable AI agent skill — a set of markdown-based knowledge modules that Claude Code, Codex, or any AI coding agent can load when you need ADR guidance. It's part of the Startup OS Skills collection.

The skill covers the full ADR lifecycle:

Readiness Assessment (START)

Before you write anything, the agent walks you through five criteria: Are stakeholders identified? Is this the Most Responsible Moment — not too early, not too late? Have you identified at least two genuine alternatives? Are the requirements and context documented? Is a template ready?

If any of these are missing, you're not ready to write an ADR. The agent tells you what's missing instead of letting you produce an incomplete record.

Creation (MADR Template + Writing Principles)

When you're ready, the agent provides the full MADR template with guidance for each section. It also encodes seven writing principles — things like "ground claims in requirements and experience, not vendor marketing" and "disclose confidence levels honestly."

Anti-Pattern Detection

This is where it gets interesting. Zimmermann catalogs eleven anti-patterns that make ADRs useless:

• Fairy Tale — only listing benefits, no tradeoffs
• Sales Pitch — marketing language instead of technical analysis
• Dummy Alternative — including obviously unworkable options to make the preferred choice look better
• Magic Tricks — weighted scoring matrices with subjective numbers creating false objectivity
• Mega-ADR — stuffing an entire architecture document into one record

There are six more. The agent checks for all of them when reviewing a draft.

Completeness Check (ECADR)

Before you mark an ADR as accepted, the agent evaluates five criteria: Evidence that the design works. Criteria applied to compare alternatives. Agreement from stakeholders. Documentation captured and shared. Realization and review plan scheduled.

Lifecycle Management

ADRs don't end at acceptance. The skill handles status tracking, superseding outdated decisions, linking related records, and defining review triggers.

Why This Matters for AI-Assisted Development

Here's the thing that made this worth building: AI agents are already making architectural decisions alongside us. They suggest technology choices, design API contracts, pick libraries, and propose system boundaries. But they do this without any structured decision-making framework.

When you pair an AI agent with the ADR skill, something shifts. Instead of just suggesting "use PostgreSQL for this," the agent walks through the decision systematically — identifying drivers, evaluating alternatives, documenting tradeoffs, and flagging when the decision isn't ready to be made yet.

It's the difference between an AI that gives you an answer and an AI that helps you think through a decision.

The Uncomfortable Part

I'll be honest about what this doesn't solve.

This skill makes it easy to produce well-structured ADRs. But it can't force your team to actually do it. The activation energy is lower — you can say /adr create and get walked through the process instead of staring at a blank template. But the discipline of stopping to document decisions before moving on to implementation? That's still a human problem.

What I've found is that the quality improvement is what sustains the habit. When ADRs are consistently useful — when a new team member can actually understand why you chose CockroachDB over PostgreSQL, including the tradeoffs you accepted — the practice becomes self-reinforcing. People write ADRs because the last one they read saved them from relitigating a six-month-old decision.

How to Use It

Install the skill:

npx skills add ncklrs/startup-os-skills

Then invoke it in your AI agent:

/adr create          # Walk through creating a new ADR
/adr review          # Evaluate an existing ADR
/adr check-ready     # Assess if a decision is ready to be recorded
/adr check-done      # Check if an ADR meets completeness criteria
/adr template        # Get a blank MADR template

The skill includes 8 rule files covering readiness, creation, anti-patterns, completion, validation, and lifecycle management. It's open source and works with Claude Code, Cursor, Windsurf, or any agent that supports the skills format.

What's Next

The ADR skill is the third engineering skill in the Startup OS collection, alongside logging best practices and Codex code review. The pattern I'm building toward is a set of engineering skills that encode institutional knowledge — the kind of expertise that usually lives in a senior engineer's head and gets lost when they leave.

Architecture decisions. Logging strategy. Code review standards. Security patterns. Each one is a skill that can be loaded into an AI agent, making the agent's output consistently better without requiring the human to remember every best practice.

The whole collection is at github.com/ncklrs/startup-os-skills. The ADR skill specifically draws from Olaf Zimmermann's research — if you want to go deeper, his blog posts on ADR readiness, creation, MADR templates, completeness, and significance testing are worth reading.