adr-architecture

• [Purpose](#purpose)
• [When to Use This Skill](#when-to-use-this-skill)
• [What is an ADR?](#what-is-an-adr)
• [Workflow](#workflow)

- [1. Understand the Decision](#1--understand-the-decision)

- [2. Choose ADR Template](#2--choose-adr-template)

- [3. Document the Decision](#3--document-the-decision)

- [4. Validate Quality](#4--validate-quality)

- [5. Deliver and File](#5--deliver-and-file)

• [Common Patterns](#common-patterns)
• [Guardrails](#guardrails)
• [Quick Reference](#quick-reference)

Document significant architectural and technical decisions with full context, alternatives considered, trade-offs analyzed, and consequences understood. ADRs create a decision trail that helps teams understand "why" decisions were made, even years later.

• Recording architecture decisions (microservices, databases, frameworks)
• Documenting infrastructure choices (cloud providers, deployment strategies)
• Capturing technology selections (libraries, tools, platforms)
• Logging process decisions (branching strategy, deployment process)
• Establishing technical standards or conventions
• Migrating or sunsetting systems
• Making security or compliance choices
• Resolving technical debates with documented rationale
• Onboarding new team members who need decision history

Trigger phrases: "ADR", "architecture decision", "document this decision", "why did we choose", "decision record", "technical decision log"

An Architecture Decision Record is a document capturing a single significant decision. It includes:

• Context: What situation necessitates this decision?
• Decision: What are we choosing to do?
• Alternatives: What other options did we consider?
• Consequences: What are the trade-offs and implications?
• Status: Proposed, accepted, deprecated, superseded?

Quick Example:

```markdown

# ADR-042: Use PostgreSQL for Primary Database

Status: Accepted

Date: 2024-01-15

Deciders: Backend team, CTO

Need to select primary database for new microservices platform.

Requirements: ACID transactions, complex queries, 10k+ QPS at launch.

Use PostgreSQL 15+ as primary relational database.

• MySQL: Weaker JSON support, less robust constraint handling
• MongoDB: No ACID across documents, eventual consistency issues
• CockroachDB: Excellent but adds operational complexity we can't support yet

✓ Strong consistency and data integrity

✓ Excellent JSON support for semi-structured data

✓ Team has deep PostgreSQL experience

✗ Vertical scaling limits (will need read replicas at 50k+ QPS)

✗ More complex to shard than DynamoDB if we need it

```

Copy this checklist and track your progress:

```

ADR Progress:

• [ ] Step 1: Understand the decision
• [ ] Step 2: Choose ADR template
• [ ] Step 3: Document the decision
• [ ] Step 4: Validate quality
• [ ] Step 5: Deliver and file

```

Step 1: Understand the decision

Gather decision context: what decision needs to be made, why now, who decides, constraints (budget, timeline, skills, compliance), requirements (functional, non-functional, business), and scope (one service vs organization-wide). This ensures the ADR addresses the right problem.

Step 2: Choose ADR template

For technology selection (frameworks, libraries, databases) → Use resources/template.md. For complex architectural decisions with multiple interdependent choices → Study resources/methodology.md. To see examples → Review resources/examples/ (database-selection.md, microservices-migration.md, api-versioning.md).

Step 3: Document the decision

Create adr-{number}-{short-title}.md with: clear title, metadata (status, date, deciders), context (situation and requirements), decision (specific and actionable), alternatives considered (with pros/cons), consequences (trade-offs, risks, benefits), implementation notes if relevant, and links to related ADRs. See [Common Patterns](#common-patterns) for decision-type specific guidance.

Step 4: Validate quality

Self-check using resources/evaluators/rubric_adr_architecture.json. Verify: context explains WHY, decision is specific and actionable, 2-3+ alternatives documented with trade-offs, consequences include benefits AND drawbacks, technical details accurate, understandable to unfamiliar readers, honest about downsides. Minimum standard: Score ≥ 3.5 (aim for 4.5+ if controversial/high-impact).

Step 5: Deliver and file

Present the completed ADR file, highlight key trade-offs identified, suggest ADR numbering if not provided, recommend review process for high-stakes decisions, and note any follow-up decisions needed. Filing convention: Store ADRs in docs/adr/ or architecture/decisions/ directory with sequential numbering.

For technology selection:

• Focus on technical capabilities vs requirements
• Include performance benchmarks if available
• Document team expertise level
• Consider operational complexity

For architectural changes:

• Include migration strategy in consequences
• Document backward compatibility impact
• Consider team velocity impact during transition
• Note monitoring and rollback plans

For standards and conventions:

• Include examples of the standard in practice
• Document exceptions or escape hatches
• Consider enforcement mechanisms
• Note educational/onboarding implications

For deprecations:

• Set status to "Deprecated" or "Superseded"
• Link to superseding ADR
• Document sunset timeline
• Include migration guide

Do:

• Be honest about trade-offs (every choice has downsides)
• Write for future readers who lack current context
• Include specific technical details (versions, configurations)
• Acknowledge uncertainty and risks
• Keep ADRs immutable (status changes, but content doesn't)
• Write one ADR per decision (focused scope)

Don't:

• Make decisions sound better than they are
• Omit alternatives that were seriously considered
• Use jargon without explanation
• Write vague consequences ("might improve performance")
• Revisit/edit old ADRs (write new superseding ADR instead)
• Combine multiple independent decisions in one ADR

• Standard template: resources/template.md
• Complex decisions: resources/methodology.md
• Examples: resources/examples/database-selection.md, resources/examples/microservices-migration.md, resources/examples/api-versioning.md
• Quality rubric: resources/evaluators/rubric_adr_architecture.json

ADR Naming Convention: adr-{number}-{short-kebab-case-title}.md

• Example: adr-042-use-postgresql-for-primary-database.md