235 lines
6.5 KiB
Markdown
235 lines
6.5 KiB
Markdown
---
|
|
description: Manage Architectural Decision Records (ADRs) - list, view, create, or update architectural decisions
|
|
allowed-tools: Read(*), mcp__serena__list_memories(*), mcp__serena__read_memory(*), mcp__serena__write_memory(*), Task(*)
|
|
argument-hint: [list|view|create|update] [adr-number-or-name]
|
|
---
|
|
|
|
# ADR Command
|
|
|
|
Manage Architectural Decision Records (ADRs) to document important architectural and technical decisions.
|
|
|
|
## What are ADRs?
|
|
|
|
Architectural Decision Records (ADRs) are documents that capture important architectural decisions along with their context and consequences. They help teams:
|
|
|
|
- Understand **why** decisions were made
|
|
- Maintain **consistency** across the codebase
|
|
- Onboard new team members faster
|
|
- Avoid repeating past mistakes
|
|
- Track the evolution of system architecture
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
# List all ADRs
|
|
/adr list
|
|
|
|
# View a specific ADR
|
|
/adr view adr-001
|
|
/adr view adr-003-authentication-strategy
|
|
|
|
# Create a new ADR
|
|
/adr create
|
|
|
|
# Update/supersede an existing ADR
|
|
/adr update adr-002
|
|
```
|
|
|
|
## Instructions
|
|
|
|
### When user runs: `/adr list`
|
|
|
|
1. Use Serena MCP `list_memories` to find all memories starting with "adr-"
|
|
2. Parse and display them in a formatted table:
|
|
|
|
```markdown
|
|
## Architectural Decision Records
|
|
|
|
| ADR # | Status | Title | Date |
|
|
|-------|--------|-------|------|
|
|
| 001 | Accepted | Microservices Architecture | 2024-10-15 |
|
|
| 002 | Accepted | PostgreSQL Database Choice | 2024-10-18 |
|
|
| 003 | Proposed | Event-Driven Communication | 2025-10-20 |
|
|
| 004 | Deprecated | MongoDB (superseded by ADR-002) | 2024-10-10 |
|
|
|
|
**Total ADRs**: 4
|
|
**Active**: 2 | **Proposed**: 1 | **Deprecated/Superseded**: 1
|
|
```
|
|
|
|
3. Provide summary statistics
|
|
4. Offer to view specific ADRs or create new ones
|
|
|
|
### When user runs: `/adr view [number-or-name]`
|
|
|
|
1. Use Serena MCP `read_memory` with the specified ADR name
|
|
2. Display the full ADR content
|
|
3. Highlight key sections:
|
|
- Decision outcome
|
|
- Related ADRs
|
|
- Status
|
|
4. Check for related ADRs and offer to view them
|
|
5. If ADR is deprecated/superseded, show which ADR replaced it
|
|
|
|
### When user runs: `/adr create`
|
|
|
|
1. **Check existing ADRs** to determine next number:
|
|
- Use `list_memories` to find all "adr-*"
|
|
- Find highest number and increment
|
|
- If no ADRs exist, start with 001
|
|
|
|
2. **Ask clarifying questions**:
|
|
- What architectural decision needs to be made?
|
|
- What problem does this solve?
|
|
- What are the constraints?
|
|
- What options have you considered?
|
|
|
|
3. **Invoke architect agent** with Task tool:
|
|
- Pass the user's requirements
|
|
- Agent will create structured ADR
|
|
- Agent will ask to save to Serena memory
|
|
|
|
4. **Confirm ADR creation**:
|
|
- Show ADR number assigned
|
|
- Confirm it's saved to Serena memory
|
|
- Suggest reviewing related ADRs
|
|
|
|
### When user runs: `/adr update [number]`
|
|
|
|
1. **Load existing ADR**:
|
|
- Use `read_memory` to load the specified ADR
|
|
- Display current content
|
|
|
|
2. **Determine update type**:
|
|
- Ask: "What type of update?"
|
|
- Supersede (replace with new decision)
|
|
- Deprecate (mark as no longer valid)
|
|
- Amend (update details without changing decision)
|
|
|
|
3. **For Supersede**:
|
|
- Create new ADR using `/adr create` process
|
|
- Mark old ADR as "Superseded by ADR-XXX"
|
|
- Update old ADR in memory
|
|
- Link new ADR to old one
|
|
|
|
4. **For Deprecate**:
|
|
- Update status to "Deprecated"
|
|
- Add deprecation reason and date
|
|
- Save updated ADR
|
|
|
|
5. **For Amend**:
|
|
- Invoke architect agent to help with amendments
|
|
- Maintain version history
|
|
- Save updated ADR
|
|
|
|
## ADR Format
|
|
|
|
All ADRs should follow this standard format (see architect agent for full template):
|
|
|
|
```markdown
|
|
# ADR-XXX: [Decision Title]
|
|
|
|
**Status**: [Proposed | Accepted | Deprecated | Superseded by ADR-XXX]
|
|
**Date**: [YYYY-MM-DD]
|
|
|
|
## Context and Problem Statement
|
|
[What problem requires a decision?]
|
|
|
|
## Decision Drivers
|
|
- [Key factors influencing the decision]
|
|
|
|
## Considered Options
|
|
### Option 1: [Name]
|
|
- Pros: [...]
|
|
- Cons: [...]
|
|
|
|
## Decision Outcome
|
|
**Chosen option**: [Option X] because [justification]
|
|
|
|
## Consequences
|
|
- Positive: [...]
|
|
- Negative: [...]
|
|
|
|
[Additional sections as needed]
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
### When to Create an ADR
|
|
|
|
Create an ADR when making decisions about:
|
|
- **Architecture**: System structure, component boundaries, communication patterns
|
|
- **Technology**: Language, framework, database, or major library choices
|
|
- **Security**: Authentication, authorization, encryption approaches
|
|
- **Infrastructure**: Deployment, hosting, scaling strategies
|
|
- **Standards**: Coding standards, testing approaches, monitoring strategies
|
|
|
|
### When NOT to Create an ADR
|
|
|
|
Don't create ADRs for:
|
|
- Trivial decisions that don't impact architecture
|
|
- Decisions easily reversible without significant cost
|
|
- Implementation details within a single component
|
|
- Personal preferences without architectural impact
|
|
|
|
### ADR Lifecycle
|
|
|
|
1. **Proposed**: Decision is being considered
|
|
2. **Accepted**: Decision is approved and should be followed
|
|
3. **Deprecated**: No longer recommended but may still exist in code
|
|
4. **Superseded**: Replaced by a newer ADR
|
|
|
|
### Integration with Other Agents
|
|
|
|
- **architect**: Creates and updates ADRs
|
|
- **code-reviewer**: Validates code aligns with ADRs
|
|
- **security-analyst**: Ensures security ADRs are followed
|
|
- **project-manager**: Loads ADRs to inform workflow planning
|
|
|
|
## Examples
|
|
|
|
### Example 1: Team wants to understand past decisions
|
|
|
|
```bash
|
|
User: /adr list
|
|
```
|
|
|
|
Agent lists all ADRs with status, allowing team to understand architectural history.
|
|
|
|
### Example 2: Reviewing specific decision
|
|
|
|
```bash
|
|
User: /adr view adr-003-authentication-strategy
|
|
```
|
|
|
|
Agent shows full ADR with rationale, alternatives, and consequences.
|
|
|
|
### Example 3: Making new architectural decision
|
|
|
|
```bash
|
|
User: /adr create
|
|
Agent: What architectural decision needs to be made?
|
|
User: We need to choose between REST and GraphQL for our API
|
|
Agent: [Asks clarifying questions, invokes architect agent]
|
|
Agent: Created ADR-005-api-architecture-graphql. Saved to Serena memory.
|
|
```
|
|
|
|
### Example 4: Superseding old decision
|
|
|
|
```bash
|
|
User: /adr update adr-002
|
|
Agent: [Shows current ADR-002: MongoDB choice]
|
|
Agent: What type of update? (supersede/deprecate/amend)
|
|
User: supersede - we're moving to PostgreSQL
|
|
Agent: [Creates ADR-006, marks ADR-002 as superseded]
|
|
```
|
|
|
|
## Notes
|
|
|
|
- ADRs are stored in Serena memory (`.serena/memories/`)
|
|
- ADRs persist across sessions
|
|
- All agents can read ADRs to inform their work
|
|
- Architect agent is responsible for creating properly formatted ADRs
|
|
- Use sequential numbering (001, 002, 003, etc.)
|
|
- Keep ADRs concise but comprehensive
|
|
- Update ADRs rather than deleting them (maintain history)
|