372 lines
12 KiB
Markdown
372 lines
12 KiB
Markdown
# Architecture Decision Records (ADR) Guide
|
|
|
|
## Overview
|
|
|
|
Architecture Decision Records (ADRs) are a critical component of the BMad Method for documenting and tracking technical decisions throughout the project lifecycle. ADRs provide a structured approach to capturing the context, reasoning, and consequences of architectural choices, ensuring that institutional knowledge is preserved and decision-making processes remain transparent.
|
|
|
|
## What are ADRs?
|
|
|
|
An Architecture Decision Record is a document that captures a single architectural decision and its context. Each ADR describes:
|
|
|
|
- **The decision context** - What situation prompted this decision?
|
|
- **The decision itself** - What was decided?
|
|
- **The rationale** - Why was this decision made?
|
|
- **The consequences** - What are the implications of this decision?
|
|
|
|
ADRs are immutable once written - if a decision changes, a new ADR is created that supersedes the old one, maintaining a complete historical record of decision evolution.
|
|
|
|
## Why Use ADRs?
|
|
|
|
### Decision Transparency
|
|
|
|
- Clear documentation of why technical choices were made
|
|
- Visible reasoning process for future reference
|
|
- Shared understanding across team members
|
|
- Accountability for technical decisions
|
|
|
|
### Historical Context
|
|
|
|
- Understanding the environment and constraints when decisions were made
|
|
- Preventing re-litigation of previously resolved issues
|
|
- Learning from past decisions and their outcomes
|
|
- Maintaining continuity across team changes
|
|
|
|
### Change Management
|
|
|
|
- Structured approach to evolving architectural decisions
|
|
- Clear process for superseding previous decisions
|
|
- Impact assessment for proposed changes
|
|
- Migration planning and execution guidance
|
|
|
|
### Knowledge Transfer
|
|
|
|
- Preserving institutional knowledge beyond individual team members
|
|
- Onboarding new team members with complete context
|
|
- Understanding legacy decisions and their constraints
|
|
- Building organizational learning capabilities
|
|
|
|
## ADR Structure
|
|
|
|
BMad ADRs follow a standardized format that ensures consistency and completeness:
|
|
|
|
### Header Information
|
|
|
|
- **ADR Number**: Sequential identifier (ADR-001, ADR-002, etc.)
|
|
- **Title**: Descriptive title summarizing the decision
|
|
- **Date**: When the decision was made
|
|
- **Status**: Current status (Proposed, Accepted, Superseded, Deprecated)
|
|
- **Participants**: Who was involved in making the decision
|
|
|
|
### Core Content Sections
|
|
|
|
#### 1. Context and Problem Statement
|
|
|
|
- **Situation**: What circumstances led to this decision point?
|
|
- **Problem**: What specific problem needs to be solved?
|
|
- **Constraints**: What limitations or requirements must be considered?
|
|
- **Success Criteria**: How will we know if this decision was successful?
|
|
|
|
#### 2. Decision Drivers
|
|
|
|
- **Functional Requirements**: What capabilities must be delivered?
|
|
- **Quality Attributes**: Performance, security, maintainability, etc.
|
|
- **Technical Constraints**: Platform limitations, existing systems, etc.
|
|
- **Business Constraints**: Budget, timeline, skills, compliance, etc.
|
|
|
|
#### 3. Considered Options
|
|
|
|
For each option considered:
|
|
|
|
- **Description**: What would this approach involve?
|
|
- **Pros**: What are the advantages of this approach?
|
|
- **Cons**: What are the disadvantages or risks?
|
|
- **Trade-offs**: What would we gain/lose with this choice?
|
|
|
|
#### 4. Decision Outcome
|
|
|
|
- **Chosen Option**: Which approach was selected?
|
|
- **Justification**: Why was this option chosen over the alternatives?
|
|
- **Decision Makers**: Who made the final decision?
|
|
- **Decision Date**: When was the decision finalized?
|
|
|
|
#### 5. Consequences and Implications
|
|
|
|
- **Positive Consequences**: Expected benefits and improvements
|
|
- **Negative Consequences**: Accepted trade-offs and limitations
|
|
- **Neutral Consequences**: Other implications that are neither positive nor negative
|
|
- **Risks**: Potential issues that may arise from this decision
|
|
|
|
#### 6. Implementation Notes
|
|
|
|
- **Implementation Plan**: High-level approach to implementing the decision
|
|
- **Timeline**: Key milestones and deadlines
|
|
- **Dependencies**: What other work must be completed first?
|
|
- **Success Metrics**: How will implementation success be measured?
|
|
|
|
#### 7. Follow-up Actions
|
|
|
|
- **Next Steps**: Immediate actions required to implement the decision
|
|
- **Review Points**: When should this decision be re-evaluated?
|
|
- **Monitoring**: What should be watched to ensure the decision remains valid?
|
|
- **Migration**: If applicable, how to transition from previous approaches?
|
|
|
|
## Getting Started with ADRs
|
|
|
|
### Setting Up ADR Process
|
|
|
|
1. **Initialize ADR Structure**
|
|
|
|
```
|
|
Use the `*create-adr` command with any BMad agent
|
|
This creates the /docs/adr directory and first ADR template
|
|
```
|
|
|
|
2. **Establish ADR Governance**
|
|
|
|
```
|
|
Define who can create ADRs (typically Architect, senior developers)
|
|
Establish review and approval processes
|
|
Set guidelines for when ADRs are required
|
|
Create templates for common decision types
|
|
```
|
|
|
|
3. **Integrate with Workflows**
|
|
```
|
|
Include ADR creation in architecture tasks
|
|
Reference ADRs in development stories
|
|
Link ADRs to Memory Bank for context
|
|
Review ADRs during sprint retrospectives
|
|
```
|
|
|
|
### When to Create an ADR
|
|
|
|
**Always create an ADR for:**
|
|
|
|
- Technology stack decisions (frameworks, databases, services)
|
|
- Architecture pattern choices (microservices vs monolith, event-driven vs request-response)
|
|
- Infrastructure decisions (cloud providers, deployment strategies)
|
|
- Security architecture choices (authentication methods, data protection)
|
|
- Integration patterns and protocols
|
|
- Data architecture and storage strategies
|
|
|
|
**Consider creating an ADR for:**
|
|
|
|
- Significant library or tool selections
|
|
- Coding standards and conventions
|
|
- Testing strategies and approaches
|
|
- Deployment and release processes
|
|
- Monitoring and observability approaches
|
|
- Performance optimization strategies
|
|
|
|
**Don't create ADRs for:**
|
|
|
|
- Implementation details that don't affect architecture
|
|
- Temporary or experimental decisions
|
|
- Decisions that can be easily reversed
|
|
- Personal preferences without architectural impact
|
|
|
|
## Daily Usage Patterns
|
|
|
|
### Creating ADRs
|
|
|
|
1. **Identify Decision Point**
|
|
|
|
- Recognize when an architectural decision needs to be made
|
|
- Gather stakeholders and relevant information
|
|
- Define the scope and impact of the decision
|
|
|
|
2. **Research and Analysis**
|
|
|
|
- Investigate available options and approaches
|
|
- Analyze trade-offs and implications
|
|
- Consult with team members and experts
|
|
- Consider long-term consequences
|
|
|
|
3. **Draft ADR**
|
|
|
|
- Use `*create-adr` command to create new ADR
|
|
- Fill in all required sections thoroughly
|
|
- Include specific examples and evidence
|
|
- Reference related ADRs and documentation
|
|
|
|
4. **Review and Approval**
|
|
- Share with relevant stakeholders
|
|
- Incorporate feedback and revisions
|
|
- Obtain necessary approvals
|
|
- Finalize and mark as Accepted
|
|
|
|
### Referencing ADRs
|
|
|
|
- **In Code**: Include ADR references in significant architectural components
|
|
- **In Documentation**: Link to relevant ADRs from architecture documentation
|
|
- **In Stories**: Reference applicable ADRs in development stories
|
|
- **In Reviews**: Use ADRs to guide code and architecture reviews
|
|
|
|
### Maintaining ADRs
|
|
|
|
- **Regular Reviews**: Periodically review ADRs for continued relevance
|
|
- **Status Updates**: Update status when decisions are superseded or deprecated
|
|
- **Outcome Tracking**: Document actual consequences versus predicted outcomes
|
|
- **Lesson Capture**: Record lessons learned from ADR outcomes
|
|
|
|
## Best Practices
|
|
|
|
### Writing Quality ADRs
|
|
|
|
**Be Specific and Concrete**
|
|
|
|
- Use specific examples rather than abstract concepts
|
|
- Include quantitative criteria where possible
|
|
- Reference specific technologies, patterns, and approaches
|
|
- Provide concrete success and failure criteria
|
|
|
|
**Include Sufficient Context**
|
|
|
|
- Explain the business and technical environment
|
|
- Document constraints and assumptions
|
|
- Reference related decisions and dependencies
|
|
- Include timeline and urgency factors
|
|
|
|
**Consider Multiple Perspectives**
|
|
|
|
- Include different stakeholder viewpoints
|
|
- Consider short-term and long-term implications
|
|
- Address both technical and business concerns
|
|
- Acknowledge uncertainty and risks
|
|
|
|
**Maintain Objectivity**
|
|
|
|
- Present options fairly without bias
|
|
- Acknowledge weaknesses in chosen approaches
|
|
- Document dissenting opinions when relevant
|
|
- Separate facts from opinions clearly
|
|
|
|
### ADR Governance
|
|
|
|
**Establish Clear Ownership**
|
|
|
|
- Define who can create and approve ADRs
|
|
- Assign responsibility for ADR maintenance
|
|
- Create escalation paths for disputed decisions
|
|
- Establish review cycles and update processes
|
|
|
|
**Ensure Visibility**
|
|
|
|
- Make ADRs easily discoverable and accessible
|
|
- Include ADRs in onboarding processes
|
|
- Reference ADRs in relevant documentation
|
|
- Communicate significant ADRs to stakeholders
|
|
|
|
**Maintain Quality Standards**
|
|
|
|
- Establish templates and writing guidelines
|
|
- Require peer review before acceptance
|
|
- Validate that ADRs include all required sections
|
|
- Ensure decisions are actually implemented
|
|
|
|
## Advanced Usage
|
|
|
|
### ADR Relationships
|
|
|
|
**Superseding ADRs**
|
|
|
|
- Create new ADR that replaces previous decision
|
|
- Update old ADR status to "Superseded by ADR-XXX"
|
|
- Explain why previous decision no longer applies
|
|
- Document migration plan if applicable
|
|
|
|
**Related ADRs**
|
|
|
|
- Reference related decisions in each ADR
|
|
- Create ADR chains for evolutionary decisions
|
|
- Cross-reference ADRs that affect each other
|
|
- Maintain decision dependency maps
|
|
|
|
**ADR Collections**
|
|
|
|
- Group related ADRs by system or domain
|
|
- Create index ADRs for complex decision areas
|
|
- Organize ADRs by architectural layers or concerns
|
|
- Maintain chronological and topical views
|
|
|
|
### Integration with Tools
|
|
|
|
**Version Control**
|
|
|
|
- Store ADRs in same repository as code
|
|
- Use pull requests for ADR review processes
|
|
- Tag ADRs with relevant releases
|
|
- Track ADR changes over time
|
|
|
|
**Documentation Systems**
|
|
|
|
- Link ADRs from architecture documentation
|
|
- Include ADRs in generated documentation
|
|
- Create ADR dashboards and summaries
|
|
- Integrate with project wikis and portals
|
|
|
|
**Development Tools**
|
|
|
|
- Reference ADRs in code comments
|
|
- Include ADR numbers in commit messages
|
|
- Link ADRs from issue tracking systems
|
|
- Integrate with code review tools
|
|
|
|
## Troubleshooting Common Issues
|
|
|
|
### ADRs Not Being Created
|
|
|
|
**Symptoms**: Important decisions made without ADRs
|
|
**Solutions**:
|
|
|
|
- Include ADR creation in definition of done
|
|
- Add ADR checkpoints to review processes
|
|
- Provide ADR training and templates
|
|
- Recognize and reward good ADR practices
|
|
|
|
### ADRs Becoming Outdated
|
|
|
|
**Symptoms**: ADRs no longer reflect current reality
|
|
**Solutions**:
|
|
|
|
- Establish regular ADR review cycles
|
|
- Include ADR validation in retrospectives
|
|
- Assign ADR maintenance responsibilities
|
|
- Create processes for updating or superseding ADRs
|
|
|
|
### Low ADR Quality
|
|
|
|
**Symptoms**: ADRs lack detail or miss key information
|
|
**Solutions**:
|
|
|
|
- Provide ADR writing training and examples
|
|
- Establish peer review requirements
|
|
- Create quality checklists and templates
|
|
- Give feedback on ADR content and structure
|
|
|
|
### ADRs Not Being Used
|
|
|
|
**Symptoms**: Team doesn't reference or follow ADRs
|
|
**Solutions**:
|
|
|
|
- Make ADRs easily discoverable and accessible
|
|
- Reference ADRs in relevant processes and documentation
|
|
- Include ADR awareness in onboarding
|
|
- Demonstrate value through successful outcomes
|
|
|
|
## ADR Templates
|
|
|
|
The BMad framework includes templates for different types of ADRs:
|
|
|
|
- `adr-tmpl.yaml` - General ADR template for any architectural decision
|
|
- Specialized templates for common decision types (technology selection, pattern adoption, etc.)
|
|
|
|
These templates ensure consistency and completeness while providing guidance for documenting different types of architectural decisions.
|
|
|
|
## Related Documentation
|
|
|
|
- [Memory Bank Guide](memory-bank-guide.md) - Persistent context management
|
|
- [Project Scaffolding Guide](project-scaffolding-guide.md) - Standard project structures
|
|
- [Core Architecture](core-architecture.md) - Technical framework details
|
|
- [User Guide](../bmad-core/user-guide.md) - Complete BMad workflow documentation
|