ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity
BMAD-METHOD/docs/adr-guide.md

12 KiB
Raw Blame History

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