Architecture Decision Record creation and management
Creates and manages Architecture Decision Records (ADRs) to document technical decisions with proper context, alternatives, and consequences. Use when making significant architectural choices that need preservation for future reference.
/plugin marketplace add melodic-software/claude-code-plugins/plugin install documentation-standards@melodic-softwareThis skill is limited to using the following tools:
Use this skill when:
Create and manage Architecture Decision Records (ADRs) for documenting technical decisions.
Before creating ADRs:
docs-management skill for ADR patternsWhat is an ADR?
An Architecture Decision Record (ADR) captures:
- WHAT decision was made
- WHY it was made (context and drivers)
- WHAT alternatives were considered
- WHAT the consequences are
Benefits:
- Preserves decision context for future team members
- Prevents relitigating closed decisions
- Documents trade-offs explicitly
- Creates searchable decision history
# ADR-[NUMBER]: [TITLE]
## Status
[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]
## Context
[What is the issue that we're seeing that is motivating this decision or change?]
## Decision
[What is the change that we're proposing and/or doing?]
## Consequences
[What becomes easier or more difficult to do because of this change?]
# ADR-[NUMBER]: [SHORT TITLE]
## Status
[Proposed | Accepted | Deprecated | Superseded]
Date: [YYYY-MM-DD]
Deciders: [Names/Roles]
## Context and Problem Statement
[Describe the context and problem statement, e.g., in free form using two to
three sentences or in the form of an illustrative story. You may want to
articulate the problem in form of a question.]
## Decision Drivers
* [Driver 1: e.g., technical constraint]
* [Driver 2: e.g., business requirement]
* [Driver 3: e.g., team expertise]
## Considered Options
1. [Option 1]
2. [Option 2]
3. [Option 3]
## Decision Outcome
**Chosen option:** "[Option X]", because [justification, e.g., only option
that meets requirement / best trade-off / etc.].
### Consequences
**Good:**
* [Positive consequence 1]
* [Positive consequence 2]
**Bad:**
* [Negative consequence 1]
* [Negative consequence 2]
### Confirmation
[Describe how the implementation of/compliance with the ADR is confirmed.
E.g., by a review or an ArchUnit test.]
## Pros and Cons of Options
### [Option 1]
[Example description]
* Good, because [argument]
* Good, because [argument]
* Bad, because [argument]
* Bad, because [argument]
### [Option 2]
[Example description]
* Good, because [argument]
* Bad, because [argument]
### [Option 3]
[Example description]
* Good, because [argument]
* Bad, because [argument]
## More Information
[Links to related ADRs, external documentation, or discussion threads]
# ADR-[NUMBER]: [TITLE]
| Property | Value |
|----------|-------|
| **Status** | [Proposed \| Accepted \| Deprecated \| Superseded] |
| **Date** | [YYYY-MM-DD] |
| **Author** | [Name] |
| **Reviewers** | [Names] |
| **Approvers** | [Names] |
| **Epic/Story** | [Link] |
| **Supersedes** | [ADR-XXX] |
| **Superseded By** | [ADR-XXX] |
## Executive Summary
[One paragraph summary for stakeholders who don't read the full ADR]
## Context
### Background
[Detailed context explaining the situation]
### Problem Statement
[Clear statement of the problem to be solved]
### Constraints
| Constraint | Description |
|------------|-------------|
| [C-1] | [Description] |
| [C-2] | [Description] |
### Assumptions
| Assumption | Description |
|------------|-------------|
| [A-1] | [Description] |
| [A-2] | [Description] |
## Decision Drivers
1. **[Driver 1]**: [Explanation]
2. **[Driver 2]**: [Explanation]
3. **[Driver 3]**: [Explanation]
## Options Considered
### Option 1: [Name]
**Description:** [What this option entails]
**Pros:**
- [Pro 1]
- [Pro 2]
**Cons:**
- [Con 1]
- [Con 2]
**Estimated Effort:** [T-shirt size or hours]
**Risk Level:** [Low/Medium/High]
### Option 2: [Name]
[Same structure...]
### Option 3: [Name]
[Same structure...]
## Decision
**We will adopt Option [X]: [Name]**
### Rationale
[Detailed explanation of why this option was chosen]
### Trade-offs Accepted
| Trade-off | Mitigation |
|-----------|------------|
| [Trade-off 1] | [How we'll manage it] |
| [Trade-off 2] | [How we'll manage it] |
## Consequences
### Positive
- [Consequence 1]
- [Consequence 2]
### Negative
- [Consequence 1]
- [Consequence 2]
### Neutral
- [Consequence 1]
## Implementation
### Action Items
| Action | Owner | Due Date | Status |
|--------|-------|----------|--------|
| [Action 1] | [Name] | [Date] | [Status] |
| [Action 2] | [Name] | [Date] | [Status] |
### Validation Criteria
- [ ] [Criterion 1]
- [ ] [Criterion 2]
- [ ] [Criterion 3]
## Related Decisions
- [ADR-XXX: Related Decision 1]
- [ADR-YYY: Related Decision 2]
## References
- [Reference 1]
- [Reference 2]
ADR Status Flow:
┌──────────────┐
│ Proposed │
└──────┬───────┘
│
▼
┌──────────────┐ ┌──────────────┐
│ Accepted │────▶│ Deprecated │
└──────────────┘ └──────────────┘
│
▼
┌──────────────┐
│ Superseded │
│ by ADR-XXX │
└──────────────┘
ADR Numbering Patterns:
Sequential:
ADR-001, ADR-002, ADR-003, ...
Date-based:
ADR-2025-01-001, ADR-2025-01-002, ...
Category-prefixed:
ARCH-001 (architecture)
DATA-001 (data/database)
SEC-001 (security)
API-001 (API design)
# ADR-001: Use PostgreSQL as Primary Database
## Status
Accepted
Date: 2025-01-15
## Context and Problem Statement
We need to choose a primary database for the order management system.
The database must support complex queries, transactions, and scale to
millions of records.
## Decision Drivers
* Need ACID compliance for financial transactions
* Team has strong SQL expertise
* Must support JSON for flexible data
* Open source preferred for cost
## Considered Options
1. PostgreSQL
2. MySQL
3. MongoDB
4. SQL Server
## Decision Outcome
**Chosen option:** "PostgreSQL", because it provides the best combination
of ACID compliance, JSON support, and open-source licensing.
### Consequences
**Good:**
* Strong transaction support for financial data
* JSONB for flexible schema when needed
* Excellent query optimizer
* Large ecosystem and community
**Bad:**
* Requires careful tuning for high write loads
* Connection pooling essential (PgBouncer)
# ADR-002: Adopt Event-Driven Architecture for Order Processing
## Status
Accepted
Date: 2025-01-20
## Context and Problem Statement
The order processing system needs to coordinate multiple services
(inventory, payment, shipping) while maintaining loose coupling and
supporting eventual consistency.
## Decision Drivers
* Services must be independently deployable
* Need to handle partial failures gracefully
* Want to enable event sourcing in future
* Must support audit trail requirements
## Considered Options
1. Direct synchronous calls (REST)
2. Event-driven with message broker
3. Choreography with events
4. Orchestration with saga pattern
## Decision Outcome
**Chosen option:** "Event-driven with message broker (Kafka)", combined
with saga orchestration for complex workflows.
### Consequences
**Good:**
* Loose coupling between services
* Natural audit trail through event log
* Enables replay and debugging
* Supports eventual consistency model
**Bad:**
* Added complexity of message broker
* Eventually consistent (not immediate)
* Requires careful event schema design
* Team needs messaging expertise
# Architecture Decision Registry
| ADR | Title | Status | Date | Category |
|-----|-------|--------|------|----------|
| [ADR-001](./ADR-001.md) | Use PostgreSQL | Accepted | 2025-01-15 | Data |
| [ADR-002](./ADR-002.md) | Event-Driven Architecture | Accepted | 2025-01-20 | Architecture |
| [ADR-003](./ADR-003.md) | REST for External APIs | Accepted | 2025-01-22 | API |
| [ADR-004](./ADR-004.md) | gRPC for Internal Services | Accepted | 2025-01-22 | API |
## By Category
### Architecture
- [ADR-002: Event-Driven Architecture](./ADR-002.md)
### Data
- [ADR-001: Use PostgreSQL](./ADR-001.md)
### API
- [ADR-003: REST for External APIs](./ADR-003.md)
- [ADR-004: gRPC for Internal Services](./ADR-004.md)
| Anti-Pattern | Problem | Solution |
|---|---|---|
| No ADRs | Decisions forgotten | Start ADR practice |
| Stale ADRs | Reality diverged | Review and update status |
| Huge ADRs | Too much detail | Split into multiple ADRs |
| Vague ADRs | Not actionable | Be specific |
| Solo ADRs | No review | Require peer review |
When creating ADRs:
For detailed guidance:
Last Updated: 2025-12-26
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.