Architecture Decision Records

Comprehensive patterns for creating, maintaining, and managing Architecture Decision Records (ADRs) that capture the context and rationale behind significant technical decisions.

Use this skill when

• Making significant architectural decisions

• Documenting technology choices

• Recording design trade-offs

• Onboarding new team members

• Reviewing historical decisions

• Establishing decision-making processes

Do not use this skill when

• You only need to document small implementation details

• The change is a minor patch or routine maintenance

• There is no architectural decision to capture

Instructions

• Capture the decision context, constraints, and drivers.

• Document considered options with tradeoffs.

• Record the decision, rationale, and consequences.

• Link related ADRs and update status over time.

Core Concepts

🧠 Knowledge Modules (Fractal Skills)

1. 1. What is an ADR?
2. 2. When to Write an ADR
3. 3. ADR Lifecycle

4. Template 1: Standard ADR (MADR Format)

5. Option 1: PostgreSQL

6. Option 2: MySQL

7. Option 3: MongoDB

8. Positive

9. Negative

10. Risks

11. Template 2: Lightweight ADR

12. Template 3: Y-Statement Format

13. Template 4: ADR for Deprecation

14. Positive

15. Negative

16. Template 5: Request for Comments (RFC) Style

17. Event Store

18. Projections

19. Technology

20. Directory Structure

21. ADR Index (README.md)

22. Automation (adr-tools)

23. Before Submission

24. During Review

25. After Acceptance

26. Do's

27. Don'ts