create-adr
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
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.
| name | create-adr |
|---|---|
| description | | |
| Trigger keywords | ADR, decision record, architectural decision, trade-offs, options, rationale |
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:
- Create new ADR with next number
- Reference original: "Supersedes ADR-NNN"
- 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
- "What problem is this decision solving?"
- "What happens if we don't make this decision?"
- "What constraints are non-negotiable?"
- "Who will be affected by this decision?"
- "How long do we expect this decision to remain valid?"
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)
- 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
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?"
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
- Custom JSON schema with documentation
- Schema.org/Product with JSON-LD serialization
- 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
Links
- Relates to ARCHITECTURE.md#data-strategy
- Schema.org Product: https://schema.org/Product
</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
- 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