/adr
Create Architecture Decision Records (ADRs) to document important architectural choices and design decisions in your project.
Quick Start
/agileflow:adr NUMBER=0001 TITLE="Use PostgreSQL for persistence" CONTEXT="Need reliable database" DECISION="PostgreSQL chosen" CONSEQUENCES="Better reliability, steeper learning curve"Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
NUMBER | Yes | - | 4-digit ADR number (e.g., 0001, 0042) |
TITLE | Yes | - | Short title of the architectural decision |
CONTEXT | Yes | - | Why this decision was needed |
DECISION | Yes | - | What was chosen and why |
CONSEQUENCES | Yes | - | Trade-offs, positive and negative impacts |
LINKS | No | - | Optional links to related documentation |
Examples
Basic ADR: Database Selection
/agileflow:adr NUMBER=0001 TITLE="Use PostgreSQL for persistence" CONTEXT="We need a reliable database with ACID guarantees for user data and transactions" DECISION="PostgreSQL chosen over MongoDB for its strong consistency guarantees and mature ecosystem" CONSEQUENCES="Better data integrity and reliability. Team needs PostgreSQL training. Slightly higher operational complexity than NoSQL alternatives"This creates a new file at docs/03-decisions/adr-0001-use-postgresql-for-persistence.md with the full ADR structure.
ADR with Related Links
/agileflow:adr NUMBER=0002 TITLE="Adopt TypeScript for all new code" CONTEXT="Type safety issues in JavaScript codebase causing bugs in production" DECISION="Migrate to TypeScript with strict type checking enabled" CONSEQUENCES="Fewer type-related bugs. Initial slower development. Better IDE support and refactoring. Requires team training" LINKS="- Related Story: US-0042\n- Related ADR: ADR-0001"Output
When you run the command, you'll see:
- Preview: Shows the generated ADR content in full
- Confirmation: Asks YES/NO to approve the ADR
- File Creation: Creates the ADR file in
docs/03-decisions/directory - Filename Format:
adr-<NUMBER>-<slug>.md(automatically generated from title)
The generated ADR includes:
---
number: 0001
title: Use PostgreSQL for persistence
date: 2025-12-24
status: accepted
tags: [database, architecture]
---
# ADR-0001: Use PostgreSQL for persistence
## Context
We need a reliable database...
## Decision
We will use PostgreSQL...
## Consequences
- Better data integrity...
- Team needs training...Best Practices
ADR Numbering
- Number sequentially (0001, 0002, 0003, ...)
- Don't skip numbers or reuse them
- Use leading zeros for consistency
Writing Good ADRs
- Context first: Explain the problem or constraint before the decision
- Be specific: "Use PostgreSQL 15+ with async replication" not "Use a database"
- Document trade-offs: List both positive and negative consequences
- Keep concise: Aim for 1-2 pages maximum
- Reference related work: Link to epics, stories, or other ADRs
Context Section Tips
- What problem or constraint triggered this decision?
- What are the business drivers?
- What technical constraints exist?
- What have we tried before?
Decision Section Tips
- State clearly what was chosen
- Explain briefly why this option won
- Mention alternatives that were considered
- Include version numbers or specific details
Consequences Section Tips
- List positive impacts first
- Then list trade-offs and risks
- Be honest about downsides
- Suggest mitigation strategies
Related Commands
/story-new- Create user stories related to architectural decisions/epic-new- Create epics for larger architectural efforts/context- Generate comprehensive project context including ADRs