create-adr-spike（创建 ADR 峰值）

Create ADR Spike

Standardized workflow for creating Architecture Decision Records (ADRs) and conducting research spikes for technical decisions.

When to Use This Skill

Explicit Triggers:

• "Create an ADR for [decision]"
• "Architecture decision for [problem]"
• "Research spike on [topic]"
• "Evaluate options for [choice]"
• "Document technical decision about [subject]"
• "Should we use X or Y?"

Implicit Triggers:

• Comparing multiple technical alternatives
• Making architectural choices that affect system design
• Evaluating libraries, frameworks, or patterns
• Deciding on refactoring approaches
• Documenting important technical trade-offs

Debugging/Analysis Triggers:

• "What decisions led to this architecture?"
• "Why did we choose [technology/pattern]?"
• "Search existing ADRs for [topic]"

When NOT to Use:

• Simple code refactoring (no architectural impact)
• Bug fixes without design implications
• Minor configuration changes
• Routine maintenance tasks

Table of Contents

Core Sections

• Quick Start - What this skill does and when to use it
• Workflow - Complete 5-phase ADR creation process

- Phase 1: Research (Discovery) - Gather context and search existing knowledge - Phase 2: Analysis (Evaluation) - Evaluate alternatives systematically - Phase 3: Decision (Recommendation) - Make clear, justified recommendation - Phase 4: Documentation (Formalization) - Create permanent ADR record - Phase 5: Memory Storage (Persistence) - Store decision in memory graph

• Quality Checklist - Verification before marking spike complete
• Anti-Patterns to Avoid - Common mistakes and correct approaches

Project Integration

• Project-Specific Conventions - ADR directory structure and naming
• Examples - Complete walkthroughs and use cases
• Output Format - How to present completed ADR spike results
• Success Criteria - When an ADR spike is complete

Supporting Resources

• reference.md - Technical documentation, ADR template deep-dive, and comprehensive examples
• Scripts - Utility scripts for ADR number finding and validation
• Templates - ADR and migration templates for structured decision records

Additional Information

• Requirements - Skills, tools, project setup, and knowledge needed
• Troubleshooting - Common issues and solutions
• References - Related documentation and guides

Templates

This skill includes comprehensive ADR and migration templates:

• templates/adr-template.md - Complete ADR structure with:

- Status and metadata frontmatter - Context, decision, and consequences sections - Implementation strategy and validation plan - Migration path with before/after examples - Alternatives considered and trade-off analysis - Related decisions and references

• templates/migration-template.md - Detailed migration/refactor plan with:

- Current state and desired state analysis - Phased migration path with detailed steps - Risk analysis and mitigation strategies - Comprehensive rollback procedures - Testing strategy and monitoring plan - Communication and training plans

Usage: Reference these templates when creating ADRs from spikes or planning complex migrations/refactors.

Quick Start

Invoke this skill when you need to:

• Document an architectural decision
• Research technical alternatives
• Evaluate competing solutions
• Create a formal decision record

Example invocation:

"Create an ADR for choosing between PostgreSQL and Neo4j for our graph storage"

Workflow

Phase 1: Research (Discovery)

Objective: Gather all relevant context before making a recommendation.

1. Identify the Decision:

- What problem are we solving? - What constraints exist (performance, cost, expertise)? - What are the success criteria?

1. Search Existing Knowledge: # Search existing ADRs for related decisions find docs/adr -name "*.md" -type f -exec grep -l "keyword" {} \; # Search project memory for patterns mcp__memory__search_memories(query="related topic")
2. Research External Resources (if needed):

- Use mcp__context7__resolve-library-id to find library documentation - Use mcp__context7__get-library-docs to get detailed technical info - Use WebSearch for recent discussions, benchmarks, or comparisons - Use WebFetch to extract specific documentation pages

1. Document Findings:

- Create ADR directory and start drafting ADR.md: docs/adr/not_started/{number}-{kebab-case-title}/ └── ADR.md # Draft: add research findings to "Context" and "Research" sections - DO NOT create separate RESEARCH.md, ANALYSIS.md, or EXECUTIVE_SUMMARY.md files - DO NOT put research in .claude/artifacts/ - All research goes directly into ADR.md sections

Phase 2: Analysis (Evaluation)

Objective: Evaluate alternatives systematically.

1. Identify Options (minimum 2-3):

- List all viable alternatives - Include "do nothing" if applicable - Consider hybrid approaches

1. Evaluate Each Option: For each alternative, document:

- Pros: Benefits and strengths - Cons: Drawbacks and weaknesses - Performance: Speed, scalability, resource usage - Maintainability: Code complexity, debugging, testability - Cost: Development time, operational cost, learning curve - Team Fit: Expertise required, training needed - Risks: What could go wrong? - Trade-offs: What are we giving up?

1. Create Comparison Matrix: Criteria Option A Option B Option C Performance High Medium Low Maintainability Medium High Low Cost Low High Medium Team Fit High Medium Low

Phase 3: Decision (Recommendation)

Objective: Make a clear, justified recommendation.

1. Recommend Preferred Option:

- State choice clearly - Provide 2-3 sentence rationale - Reference evaluation criteria

1. Document Justification:

- Why this option over others? - What criteria weighted most heavily? - What assumptions are we making? - What constraints influenced the decision?

1. Identify Consequences:

- Positive: What improves? - Negative: What gets harder? - Risks: What could fail? - Mitigations: How to reduce risks?

Phase 4: Documentation (Formalization)

Objective: Create permanent ADR record.

1. Determine ADR Number: # Find highest existing ADR number across all status directories find docs/adr -name "[0-9]*.md" | \ sed 's/.*\/\([0-9]*\)-.*/\1/' | \ sort -n | tail -1
2. Choose ADR Directory: Default: Use not_started/ for new decisions unless implementation begins immediately.

- docs/adr/not_started/ - Decision made, implementation not started - docs/adr/in_progress/ - Implementation currently underway - docs/adr/implemented/ - Fully implemented and verified

1. Create ADR from Template:

- Copy template: templates/adr-template.md or templates/migration-template.md - Fill all required sections (no placeholders) - Use next sequential number (e.g., ADR-028) - Use kebab-case for filename: 028-descriptive-title.md

1. Complete Required Sections:

- Status: Proposed | Accepted | In Progress | Completed - Date: Current date (YYYY-MM-DD) - Context: Problem statement, current state, motivation - Decision: Chosen approach, scope, pattern - Consequences: Positive, negative, migration strategy - Alternatives Considered: At least 2-3 options with pros/cons - References: Links to research, docs, discussions

1. Add Implementation Tracking (if applicable):

- Files affected - Completion criteria - Testing strategy - Code marker guidelines

Phase 5: Memory Storage (Persistence)

Objective: Store decision in memory graph for future retrieval.

1. Create Memory Entity: mcp__memory__create_entities(entities=[{"name": f"ADR-{number}: {title}", "type": "ArchitectureDecision", "observations": [f"Status: {status}", f"Decision: {chosen_option}", f"Rationale: {key_reason}", f"Date: {date}", f"Location: docs/adr/{status_dir}/{number}-{kebab-case-title}/"]}])
2. Create Relations to Existing Entities:

- Link to affected components - Link to related ADRs (supersedes, relates-to) - Link to architectural patterns

1. Verify Document Structure:

- Maximum 2 files per ADR - see "Document Structure Rule" section - For not_started/: Only ADR.md - For in_progress/: ADR.md + IMPLEMENTATION_PLAN.md - NO separate RESEARCH.md, ANALYSIS.md, EXECUTIVE_SUMMARY.md, or IMPLEMENTATION_NOTES.md - NO documents in .claude/artifacts/

Quality Checklist

Before marking the spike complete, verify:

• Minimum 2-3 alternatives evaluated
• Clear recommendation with justification
• Consequences documented (positive AND negative)
• ADR created in correct directory with proper numbering
• All required sections completed (no placeholder text)
• Memory entity created with proper observations and relations
• Max 2 files: ADR.md only (not_started) or ADR.md + IMPLEMENTATION_PLAN.md (in_progress)
• No extra files: No RESEARCH.md, ANALYSIS.md, EXECUTIVE_SUMMARY.md, IMPLEMENTATION_NOTES.md
• No single-option analysis (red flag: only one option presented)
• Trade-offs documented (no "silver bullet" claims)
• Risks identified with mitigation strategies

Document Structure Rule (CRITICAL)

Minimal documents. No redundancy. Human-readable.

Document Count by Status

✅ CORRECT Structure

For not_started/ (decision made, not yet implementing):

docs/adr/not_started/005-subprocess-daemon-architecture/
└── ADR.md    # Contains: Executive Summary, Research, Analysis, Decision, Alternatives

For in_progress/ (actively implementing):

docs/adr/in_progress/005-subprocess-daemon-architecture/
├── ADR.md                  # The decision (research + analysis + decision)
└── IMPLEMENTATION_PLAN.md  # How to build it (phases + tasks + notes)

❌ WRONG Structure (Too Many Documents)

docs/adr/in_progress/005-.../
├── ADR.md
├── RESEARCH.md              # ❌ WRONG: Put in ADR.md
├── ANALYSIS.md              # ❌ WRONG: Put in ADR.md
├── EXECUTIVE_SUMMARY.md     # ❌ WRONG: Put in ADR.md
├── IMPLEMENTATION_PLAN.md
└── IMPLEMENTATION_NOTES.md  # ❌ WRONG: Put in IMPLEMENTATION_PLAN.md

The Rule

• ADR.md = Research + Analysis + Executive Summary + Decision + Alternatives
• IMPLEMENTATION_PLAN.md = Phases + Tasks + Developer Notes (only when in_progress/)
• That's it. 1-2 files maximum.

Anti-Patterns to Avoid

1. Single Option Presented:

- ❌ BAD: "We should use PostgreSQL" (no alternatives) - ✅ GOOD: "PostgreSQL vs Neo4j vs Hybrid approach" (multiple options)

1. Missing Trade-off Analysis:

- ❌ BAD: "Option A is better in every way" - ✅ GOOD: "Option A is faster but harder to maintain"

1. No Consequence Documentation:

- ❌ BAD: Decision without discussing impact - ✅ GOOD: Positive/negative consequences documented

1. Skipping Memory Storage:

- ❌ BAD: ADR created but not in memory graph - ✅ GOOD: ADR entity created with relations

1. Placeholder Text in ADR:

- ❌ BAD: "[TODO: Add alternatives]" - ✅ GOOD: All sections fully completed

1. Wrong Directory:

- ❌ BAD: Implementation ADR in not_started/ - ✅ GOOD: ADR directory matches status

1. No External Research:

- ❌ BAD: Decision based only on opinion - ✅ GOOD: Research references documentation, benchmarks, community discussion

1. Ignoring Existing ADRs:

- ❌ BAD: Creating conflicting ADR without checking existing - ✅ GOOD: Search existing ADRs, note conflicts/supersessions

1. Splitting Documents Across Locations:

- ❌ BAD: ADR in docs/adr/, research in .claude/artifacts/ - ✅ GOOD: ALL documents in docs/adr/{status_dir}/{number}-{kebab-case-title}/

Project-Specific Conventions

ADR Directory Structure (This Project)

docs/adr/
├── implemented/    # Completed ADRs (11+ ADRs)
├── in_progress/    # Active implementation (4+ ADRs)
├── not_started/    # Proposed/accepted, not started (10+ ADRs)
├── TEMPLATE-refactor-migration.md
└── README.md

Numbering Convention

• Use 3-digit format: 001, 028, 127
• Find highest number across ALL status directories
• Use next sequential number
• Do not reuse numbers

Filename Convention

• Format: {number}-{kebab-case-title}.md
• Example: 028-indexing-orchestrator-extraction.md
• Keep titles concise (3-7 words)

Status Values

• Proposed: Initial draft, seeking approval
• Accepted: Approved, awaiting implementation
• In Progress: Currently implementing
• Completed: Fully implemented and verified
• Superseded: Replaced by newer ADR

Refactor Markers (for in-progress ADRs)

If ADR is in in_progress/, add file-level markers in affected code:

# =============================================================================
# TODO: "Section Name"
# REFACTOR: [ADR-XXX] Brief description
# WHY: One-line reason
# STARTED: YYYY-MM-DD
# STATUS: IN_PROGRESS
# PERMANENT_RECORD: docs/adr/in_progress/XXX-title.md
# ACTIVE_TRACKING: todo.md "Section Name"
# =============================================================================

See: Refactor Marker Guide

Integration with todo.md

For ADRs requiring implementation:

• Create section in ./todo.md tracking tasks
• Reference in ADR's "Active Tracking" section
• Update ADR's "Progress Log" as work proceeds

Examples

Python Examples

• validate_adr.py - Validate ADR completeness and format
• find_next_adr_number.sh - Find next ADR number in sequence

Complete Walkthroughs

See references/reference.md for detailed examples of:

• Simple architectural decision (library choice)
• Complex refactor/migration ADR
• Research spike with external investigation
• Superseding an existing ADR

Supporting Files

• references/reference.md: Detailed technical documentation, ADR template deep-dive, and comprehensive examples
• templates/adr-template.md: Complete ADR structure with all required sections
• templates/migration-template.md: Detailed migration/refactor planning template
• scripts/validate_adr.py: Validation script for ADR completeness
• scripts/find_next_adr_number.sh: Utility to find next ADR number

Requirements

Skills & Tools:

• Skill tool access: Read, Grep, Glob, Bash, Write
• MCP tools: mcp__memory__, mcp__context7__ (for research)
• Web tools: WebSearch, WebFetch (for external research)

Project Setup:

• docs/adr/ directory structure exists with status subdirectories (in projects using this skill)
• ADR templates available at templates/adr-template.md and templates/migration-template.md
• Memory system configured for entity storage

Knowledge:

• Understanding of Clean Architecture principles (for this project)
• Ability to evaluate technical trade-offs
• Familiarity with ADR format and structure

Troubleshooting

Issue: Can't find next ADR number

# Solution: Use helper script
./scripts/find_next_adr_number.sh

# Or manually:
find docs/adr -name "[0-9]*.md" | sed 's/.*\/\([0-9]*\)-.*/\1/' | sort -n | tail -1

Issue: Don't know which directory to use

• not_started/: Decision made, no implementation yet (default)
• in_progress/: Currently implementing
• implemented/: Fully complete and verified

Issue: Alternatives seem equivalent

• Good! Document that in the ADR
• Explain why you chose one over the other (team fit, learning curve, etc.)
• Consider hybrid approaches

Issue: Only one viable option

• ❌ RED FLAG - dig deeper
• Minimum 2-3 alternatives required
• Include "do nothing" as an option if applicable
• Consider different implementation approaches of the same technology

Issue: Research taking too long

• Set time box (1-2 hours for simple decisions, 4-8 hours for complex)
• Focus on key decision criteria
• Note what you didn't research in ADR limitations section
• Can always update ADR later with more research

Issue: Memory entity creation fails

• Verify memory system is configured and running
• Check entity name doesn't already exist
• Simplify observations if too complex
• Skip memory storage if blocked, but note in ADR

Success Criteria

An ADR spike is complete when:

1. ✅ Research conducted (existing ADRs, memory, external sources)
2. ✅ Alternatives evaluated (2-3+ options)
3. ✅ Recommendation made with justification
4. ✅ ADR created with all required sections
5. ✅ ADR placed in correct directory with proper numbering
6. ✅ Memory entity created with relations
7. ✅ Research artifacts saved and referenced
8. ✅ Quality checklist verified

Output Format

When completing an ADR spike, provide:

1. Executive Summary:

- Decision made - Key rationale (2-3 sentences) - Alternatives considered

1. ADR Location:

- Full path to created ADR - ADR number and title

1. Memory Entity:

- Entity name - Key observations stored

1. Next Steps (if applicable):

- Implementation tasks - todo.md section created - Refactor markers needed

References

• Refactor Marker Guide
• ADR Template
• Migration Template
• Reference Documentation - Detailed examples and walkthroughs

Skill Type: Project Skill (team workflow) Audience: @researcher, @planner, any agent making architectural decisions Last Updated: 2025-10-17