adr-methodology

Structured frameworks for documenting architectural decisions with human-in-the-loop AI assistance.

Core Principle

AI handles drafting, formatting, and enumeration. Humans provide project-specific context, stakeholder awareness, and final decision accountability.

AI assists with:

• Research and enumeration of options
• Consistent formatting
• Risk/trade-off summarization
• Matrix generation

Humans provide:

• Project-specific context and constraints
• Stakeholder empathy and political nuance
• Final decision accountability

Workflow Stages

Stage 1: Context to Criteria (/adr-assistant:new)

Gather decision context and generate assessment criteria.

1. Ask for problem description, constraints, stakeholders, initial options
2. Select appropriate framework (Salesforce Well-Architected or Technical Trade-off)
3. Generate criteria grouped by framework pillars
4. For each criterion: name, rationale for this decision, definition of "good"
5. Write criteria to .claude/adr-session.yaml
6. Prompt user to refine criteria before analysis

Stage 2: Options Matrix (/adr-assistant:analyze)

Evaluate options against criteria with risk ratings.

1. Read criteria from .claude/adr-session.yaml
2. For each option, rate against each criterion (Low/Medium/High risk)
3. Include rationale for each rating
4. Generate comparison matrix table
5. Write analysis to state file
6. Prompt user to refine ratings before generation

Stage 3: ADR Generation (/adr-assistant:generate)

Output final ADR document using MADR template.

1. Read criteria and analysis from state file
2. Ask user which option they're choosing and why
3. Generate ADR with AI disclosure
4. Auto-detect next ADR number from docs/adr/
5. Write ADR file
6. Clear state file

Assessment Frameworks

Salesforce Well-Architected (Trusted/Easy/Adaptable)

Use for enterprise decisions with security, UX, and scale concerns.

Trusted: Data security, compliance, access control, audit/governance Easy: User experience, deployment complexity, integration effort, maintenance Adaptable: Scalability, future flexibility, cost trajectory, team skill alignment

Technical Trade-off Framework

Use for infrastructure and tooling decisions.

Operational: Setup complexity, maintenance burden, monitoring, failure modes Development: Learning curve, velocity, testing approach, documentation quality Integration: Ecosystem compatibility, migration path, dependency management, lock-in risk

Custom Framework

When neither standard framework fits:

1. Extract 3-5 key decision drivers from context
2. Create criteria that directly measure those drivers
3. Ensure criteria are evaluatable (not vague)
4. Include at least one "reversibility" criterion

Risk Ratings

| Rating | Definition | Governance | |--------|------------|------------| | Low | Minimal risk to requirements, performance, or scale | Standard review | | Medium | Manageable risk with proper governance | Documented mitigation | | High | Significant risk without active mitigation | Explicit acceptance |

Assign Low when: Option aligns naturally, no significant trade-offs, team has experience, reversible Assign Medium when: Trade-offs exist but manageable, requires discipline, some learning curve, partially reversible Assign High when: Conflicts with requirement, requires significant mitigation, team lacks experience, hard to reverse

Consistency rule: At least one option should be Low or Medium for each criterion. If all options are High, the criterion may be a blocker rather than a trade-off.

State File Format

State persists to .claude/adr-session.yaml:

topic: "Database selection for user service"
status: "analyzed"  # new | criteria_defined | analyzed
framework: "technical"  # salesforce | technical | custom
criteria:
  - name: "Data consistency"
    pillar: "Operational"
    rationale: "ACID compliance needed for financial data"
    good_looks_like: "Full transaction support with rollback"
options:
  - name: "PostgreSQL"
    ratings:
      "Data consistency":
        risk: "Low"
        rationale: "Full ACID support, mature transaction handling"

ADR Output Format

Use MADR template. Include AI disclosure section:

## AI Disclosure

This ADR was drafted with AI assistance (Claude). Assessment criteria and
rationale were reviewed by decision-makers listed above. Final decision
made by humans.

Additional Resources

Reference Files

For detailed templates and frameworks, consult:

• references/templates.md - Complete ADR templates (MADR, Nygard, Y-statement)
• references/criteria-frameworks.md - Detailed assessment criteria by framework
• references/risk-ratings.md - Comprehensive risk rating guidelines