Initial commit: Fresh start with current state
This commit is contained in:
Claude Code
234
.claude/commands/adr.md
Normal file
234
.claude/commands/adr.md
Normal file
@@ -0,0 +1,234 @@
|
||||
---
|
||||
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)
|
||||
Reference in New Issue
Block a user