create-adr

rayk's avatarfrom rayk

Create Architecture Decision Records (ADRs) following LCA conventions.INVOKE THIS SKILL when user:- Asks to "document a decision" or "record a decision"- Mentions "ADR", "decision record", or "architectural decision"- Wants to capture trade-offs or options considered- Needs to supersede or update an existing decision- Asks about decision history or rationaleTrigger keywords: ADR, decision record, architectural decision, trade-offs, options, rationale

⭐2stars🔀0forks📁View on GitHub🕐Updated Dec 29, 2025

When & Why to Use This Skill

This Claude skill automates the creation of Architecture Decision Records (ADRs) following LCA conventions. It helps engineering teams capture the 'why' behind critical technical choices by documenting context, drivers, trade-offs, and alternatives, ensuring a clear and searchable historical record of architectural evolution for improved long-term maintainability.

Use Cases

  • Case 1: Documenting the rationale for choosing a specific technology stack or database to ensure future developers understand the constraints and drivers.
  • Case 2: Recording complex trade-offs during system migration or refactoring to justify why certain architectural paths were taken over others.
  • Case 3: Managing the lifecycle of technical decisions by creating new records that supersede or update existing ones while maintaining a complete audit trail.
  • Case 4: Standardizing documentation across a distributed engineering team using a consistent template for decision outcomes and consequences.
namecreate-adr
description|
Trigger keywordsADR, decision record, architectural decision, trade-offs, options, rationale
Guide creation of Architecture Decision Records that capture the "why" behind architectural choices. ADRs are append-only documents that preserve decision history, enabling future maintainers to understand context and trade-offs. 1. **Identify decision scope**: What architectural choice needs documentation? 2. **Gather context**: Why is this decision being made now? What drivers exist? 3. **Document options**: What alternatives were considered? 4. **Analyze trade-offs**: Explicit positive, negative, neutral consequences 5. **Record decision**: Write ADR with proper numbering and status 6. **Link to architecture docs**: Reference from relevant ARCHITECTURE.md ``` adr-NNN-{slug}.md

Examples: adr-001-use-protocol-buffers.md adr-002-adopt-event-sourcing.md adr-003-schema-org-boundaries.md


Numbers are sequential and never reused. Superseded ADRs keep their number.
</naming_convention>

<template>
```markdown
# ADR-NNN: {Title}

**Status**: Proposed | Accepted | Deprecated | Superseded by ADR-XXX
**Date**: YYYY-MM-DD
**Deciders**: [list of people involved]
**Technical Story**: [ticket/issue reference if applicable]

## Context and Problem Statement

[Describe the context and problem. What forces are at play? Why is this decision needed now?]

## Decision Drivers

* [Driver 1: e.g., Performance requirements]
* [Driver 2: e.g., Team expertise]
* [Driver 3: e.g., Maintenance burden]

## Considered Options

1. [Option 1]
2. [Option 2]
3. [Option 3]

## Decision Outcome

**Chosen option**: "[Option N]" because [justification].

### Consequences

**Positive:**
* [Benefit 1]
* [Benefit 2]

**Negative:**
* [Drawback 1]
* [Drawback 2]

**Neutral:**
* [Side effect that is neither good nor bad]

## Pros and Cons of Options

### Option 1: [Name]

* Good, because [argument]
* Good, because [argument]
* Bad, because [argument]

### Option 2: [Name]

* Good, because [argument]
* Bad, because [argument]
* Bad, because [argument]

### Option 3: [Name]

[etc.]

## Links

* [Link to related ADRs]
* [Link to architecture documentation]
* [Link to external references]
| Status | Meaning | Action | |--------|---------|--------| | Proposed | Under discussion | Gather feedback, refine options | | Accepted | Decision made | Implement, update architecture docs | | Deprecated | No longer relevant | Document why, keep for history | | Superseded | Replaced by newer ADR | Link to superseding ADR | ADRs are **never deleted or modified** after acceptance. They are historical records.

To change a decision:

  1. Create new ADR with next number
  2. Reference original: "Supersedes ADR-NNN"
  3. Update original status: "Superseded by ADR-XXX"

This preserves the decision trail and reasoning evolution.

- Start at 001 - Always 3 digits with leading zeros - Sequential, never skip numbers - Superseded ADRs keep their original number When gathering context, consider these common architectural drivers:

Technical:

  • Performance requirements (latency, throughput)
  • Scalability needs (horizontal, vertical)
  • Reliability requirements (uptime, fault tolerance)
  • Security constraints (compliance, data protection)

Organizational:

  • Team expertise and capacity
  • Time-to-market pressure
  • Budget constraints
  • Existing technology investments

Operational:

  • Maintenance burden
  • Monitoring and observability
  • Deployment complexity
  • Rollback capabilities

Strategic:

  • Vendor lock-in considerations
  • Future flexibility needs
  • Integration requirements
  • Standards compliance
Ask these questions to surface drivers:
  1. "What problem is this decision solving?"
  2. "What happens if we don't make this decision?"
  3. "What constraints are non-negotiable?"
  4. "Who will be affected by this decision?"
  5. "How long do we expect this decision to remain valid?"
LCA mandates explicit trade-offs—never assume decisions are purely positive.

Positive consequences: What improves? What becomes easier? Negative consequences: What gets harder? What new problems emerge? Neutral consequences: What changes without clear good/bad valence?

For each option, evaluate against:
Criterion Weight Option 1 Option 2 Option 3
Performance High ++ + -
Maintainability Medium + ++ +
Team familiarity Low - + ++
Migration effort Medium -- + +

Use: ++ (strong positive), + (positive), 0 (neutral), - (negative), -- (strong negative)

Surface hidden costs explicitly:
  • Learning curve: Time for team to become proficient
  • Migration path: Effort to move from current state
  • Operational overhead: Ongoing maintenance burden
  • Technical debt: Future refactoring this creates
  • Lock-in: Difficulty switching away later
Architecture decisions frequently needed in LCA systems:

Boundary Decisions:

  • "Where should the Conduit boundary be?"
  • "What Protocol Buffer version to use?"
  • "How to version the API?"

Composition Decisions:

  • "How to decompose this into Atoms?"
  • "What should the Composite orchestrate?"
  • "Where does this logic belong?"

Data Strategy Decisions:

  • "What Schema.org types at boundaries?"
  • "How to model this internally?"
  • "Where is the mapping layer?"

Performance Tunnel Decisions:

  • "Is this bottleneck proven by profiling?"
  • "What optimization approach?"
  • "How to encapsulate complexity?"
```markdown # ADR-005: Use Schema.org/Product at API Boundary

Status: Accepted Date: 2025-01-15 Deciders: Architecture team

Context and Problem Statement

Our product catalog API needs to be consumable by AI agents and third-party integrations. We need a data format that is self-describing and follows industry standards.

Decision Drivers

  • AI agents need to understand our data semantically
  • Third-party integrations should work without custom documentation
  • Internal models need to remain optimized for computation

Considered Options

  1. Custom JSON schema with documentation
  2. Schema.org/Product with JSON-LD serialization
  3. GraphQL with custom types

Decision Outcome

Chosen option: "Schema.org/Product with JSON-LD serialization" because it provides semantic interoperability for AI consumers while following established web standards.

Consequences

Positive:

  • AI agents can parse and understand our data without training
  • Follows LCA principle of Schema.org at boundaries
  • SEO benefits from structured data

Negative:

  • Schema.org types are verbose compared to internal models
  • Mapping layer adds complexity
  • Some product attributes don't map cleanly

Neutral:

  • Team needs to learn JSON-LD serialization
</example_adr>
</lca_specific_adrs>

<directory_structure>
<placement>
ADRs live in a dedicated directory at the architecture level they affect:

project/ ├── ARCHITECTURE.md ├── adr/ │ ├── adr-001-initial-architecture.md │ ├── adr-002-use-protocol-buffers.md │ └── adr-003-schema-org-boundaries.md └── services/ └── order-service/ ├── architecture.md └── adr/ └── adr-001-caching-strategy.md

</placement>

<index>
Maintain an index file for discoverability:

```markdown
# Architecture Decision Records

| ADR | Title | Status | Date |
|-----|-------|--------|------|
| [001](adr-001-initial-architecture.md) | Initial Architecture | Accepted | 2025-01-01 |
| [002](adr-002-use-protocol-buffers.md) | Use Protocol Buffers | Accepted | 2025-01-05 |
| [003](adr-003-schema-org-boundaries.md) | Schema.org at Boundaries | Accepted | 2025-01-15 |
Before marking ADR Accepted:
  • Clear problem statement (why now?)
  • Decision drivers listed with rationale
  • At least 2 options considered
  • Chosen option clearly stated with justification
  • Positive consequences documented
  • Negative consequences documented (mandatory—no free lunches)
  • Neutral consequences considered
  • Links to related architecture docs
  • Proper numbering (adr-NNN format)
  • Date and deciders recorded
An ADR is complete when:
  • A future reader can understand WHY the decision was made
  • Trade-offs are explicit, not hidden
  • Alternative options are documented for historical context
  • Links connect to relevant architecture documentation
  • Status accurately reflects decision state