mcaf-adr-writing

Create or update an ADR (Architecture Decision Record) under `docs/ADR/` using `docs/templates/ADR-Template.md`: context, decision, alternatives, consequences, rollout, and verification. Use when changing architecture, boundaries, dependencies, data model, or cross-cutting patterns; ensure it is self-contained, has a Mermaid diagram, and defines testable invariants.

⭐31stars🔀4forks📁View on GitHub🕐Updated Jan 3, 2026

When & Why to Use This Skill

This Claude skill automates the creation and maintenance of Architecture Decision Records (ADRs) to ensure technical consistency and long-term maintainability. It streamlines the documentation of architectural shifts, boundaries, and dependencies by generating standardized Markdown files complete with Mermaid diagrams, testable invariants, and executable verification steps.

Use Cases

  • 1. Documenting Major System Changes: Use this skill when modifying system boundaries, data models, or cross-cutting patterns to ensure the rationale and consequences are captured for the team.
  • 2. Technical Debt Management: Record the 'why' behind specific design trade-offs and alternatives considered, preventing future 'guesswork' and providing clear context for new developers.
  • 3. Enforcing Architectural Standards: Define 'MUST/MUST NOT' invariants and link them to specific test IDs or static analysis commands to ensure the implementation stays true to the design.
  • 4. Visualizing System Evolution: Automatically generate and update Mermaid diagrams within ADRs to provide a visual representation of module interactions and architectural boundaries.
namemcaf-adr-writing
description"Create or update an ADR (Architecture Decision Record) under `docs/ADR/` using `docs/templates/ADR-Template.md`: context, decision, alternatives, consequences, rollout, and verification. Use when changing architecture, boundaries, dependencies, data model, or cross-cutting patterns; ensure it is self-contained, has a Mermaid diagram, and defines testable invariants."
compatibility"Requires repository write access; produces Markdown docs with Mermaid diagrams."

MCAF: ADR Writing

Outputs

  • docs/ADR/ADR-XXXX-<short-title>.md (create or update)
  • Update docs/Architecture/Overview.md when boundaries/interactions change

Decision Quality (anti-guesswork checklist)

Before writing, make the ADR executable (no placeholders, no hand-waving):

  • Decision: one sentence. If you can’t write it, you don’t have a decision yet.
  • Scope: what changes / what does not + which module(s) are affected (match docs/Architecture/Overview.md names).
  • No invented reality: every component you mention exists in the repo today, or is explicitly part of this change (named + where it will live).
  • Invariants: write as MUST / MUST NOT statements and say how we prove each (test or static analysis).
  • Verification: use exact commands from AGENTS.md and link scenarios → test IDs.
  • Stakeholders: Product / Dev / DevOps / QA — what each role must know to execute safely.

Workflow

  1. Confirm the decision scope:
    • what changes (and what does not)
    • what module(s) are affected
    • follow AGENTS.md scoping rules: Architecture map → linked ADR/Feature → entry points (do not scan everything)
  2. Start from docs/templates/ADR-Template.md.
    • keep the ADR’s ## Implementation plan (step-by-step) updated while executing
  3. Write the ADR as a decision record:
    • Context: constraints + why this is needed now
    • Decision: a short, direct statement
    • Diagram (mandatory): include at least one Mermaid diagram for the decision (boundaries/modules/interactions)
    • Alternatives: 1–3 realistic options with pros/cons
    • Consequences: trade-offs, risks, mitigations
  4. Make it executable for the team:
    • follow AGENTS.md Task Delivery rules (analysis → plan → execute → verify)
    • include the invariants that must be proven by tests
    • include verification commands copied from AGENTS.md
    • include rollout/rollback and “how we know it’s safe”
  5. Make impacts explicit:
    • code/modules affected
    • data/config changes (including migration/rollback)
    • backwards compatibility strategy
  6. Add verification that proves the decision:
    • which tests must exist/change
    • which suites must stay green
  7. If the decision changes boundaries, update docs/Architecture/Overview.md (diagram, modules table, dependency rules).

Guardrails

  • ADRs are self-contained: no hidden context, no “as discussed”.
  • ADRs justify why; feature docs describe what the system does.
  • If you can’t state the decision in 1–2 sentences, the ADR is not ready.