Architect ADR Generator

An agent that creates well-structured Architectural Decision Records documenting important technical decisions with clear rationale, consequences, trade-offs, and alternatives considered.

When to Use This Agent

Choose ADR Generator when:

• Making significant technical architecture decisions that need documentation
• Evaluating multiple technical approaches and want structured comparison
• Onboarding team members who need to understand past architectural choices
• Preparing for architecture review meetings with documented proposals
• Building a searchable knowledge base of technical decisions

Consider alternatives when:

• Writing informal technical notes or meeting minutes (use a notes tool)
• Documenting API specifications (use OpenAPI/Swagger tooling)
• Creating user-facing documentation (use a documentation generator)

Quick Start

Copy
# .claude/agents/architect-adr-generator.yml
name: ADR Generator
model: claude-sonnet-4-20250514
tools:
  - Read
  - Write
  - Glob
  - Grep
prompt: |
  You are an architectural documentation expert. Generate
  comprehensive ADRs following the standard template with
  context, decision, consequences, and alternatives.
  Number ADRs sequentially and maintain cross-references.

Example invocation:

Copy
claude --agent architect-adr-generator "Create an ADR for choosing
  PostgreSQL over MongoDB for our user data storage, considering
  our relational query patterns and ACID requirements"

Core Concepts

ADR Template Structure

Copy
# ADR-{NUMBER}: {TITLE}

## Status
{Proposed | Accepted | Deprecated | Superseded by ADR-XXX}

## Date
{YYYY-MM-DD}

## Context
{Problem statement, forces at play, constraints}

## Decision
{The change proposed or agreed upon}

## Consequences

### Positive
- {Benefit 1}
- {Benefit 2}

### Negative
- {Trade-off 1}
- {Trade-off 2}

### Neutral
- {Side effect 1}

## Alternatives Considered

### Option A: {Name}
- Pros: {advantages}
- Cons: {disadvantages}
- Rejected because: {reason}

### Option B: {Name}
- Pros: {advantages}
- Cons: {disadvantages}
- Rejected because: {reason}

## References
- {Related ADRs, external docs, RFCs}

Decision Categories

Category	Scope	Examples
Infrastructure	Deployment, hosting, networking	Cloud provider, container orchestration
Data	Storage, caching, messaging	Database choice, queue system
Architecture	Patterns, boundaries, communication	Microservices vs monolith, API style
Security	Auth, encryption, compliance	OAuth provider, encryption standard
Frontend	Framework, state, rendering	React vs Vue, SSR vs SPA
Integration	Third-party, protocols, formats	Payment gateway, data format

ADR Lifecycle

Proposed → Accepted → [Active]
                    → Deprecated (no longer relevant)
                    → Superseded by ADR-XXX (replaced)

Configuration

Parameter	Description	Default
output_dir	Directory for ADR files	docs/adr/
numbering	Auto-increment ADR numbers	true
format	Output format (md, rst, asciidoc)	Markdown
template	Custom ADR template path	Built-in
require_alternatives	Mandate alternatives section	true
cross_reference	Auto-link related ADRs	true
status_tracking	Track lifecycle status changes	true

Best Practices

1. Write ADRs at decision time, not after. The most valuable part of an ADR is the context and alternatives you considered. These details fade from memory quickly. Write the proposed ADR before the decision meeting, then update the status and any modifications afterward.

2. Keep the context section focused on forces and constraints. Describe the specific technical constraints, business requirements, and team capabilities that shaped the decision. Avoid restating general architectural principles everyone already knows. Good context explains why this decision was non-obvious.

3. Document rejected alternatives with genuine pros. If an alternative had no merits, you wouldn't have considered it. Listing real advantages of rejected options shows thorough evaluation and helps future teams understand why circumstances might change enough to revisit the decision.

4. Use consistent file naming and numbering. Follow adr-NNNN-kebab-case-title.md naming. Sequential numbering creates a chronological record. When an ADR supersedes another, explicitly reference the old number so the chain of decisions remains traceable.

5. Link ADRs to implementation. Include references to the pull requests, tickets, or commits that implement the decision. This bidirectional linking helps developers understand not just what was decided but exactly how it was implemented, making future changes safer.

Common Issues

ADRs become stale and no longer reflect reality. Prevent this by treating ADRs as immutable records of decisions made at a point in time. When circumstances change, create a new ADR that supersedes the old one rather than editing it. The original context remains valuable for understanding the decision history. Include ADR review in your quarterly architecture review process.

Team doesn't write ADRs consistently. Lower the barrier by providing a CLI command or template that generates the boilerplate instantly. Integrate ADR creation into your pull request process for changes that touch architecture. Start with a lightweight template (context, decision, consequences) and expand only when needed. The best ADR is a short one that exists.

ADRs are too verbose or too terse. Aim for one to two pages. The context section should be two to three paragraphs explaining the specific problem. The decision section should be one clear paragraph. Consequences should be bullet points. If your ADR exceeds three pages, you're probably combining multiple decisions that should be separate records.