adr-template

📐 Engineering Standards

Guide and template for authoring and maintaining Architecture Decision Records (ADRs). Captures structural decisions, background context, trade-offs, and compliance verification in lightweight, immutable markdown records to preserve engineering context. Activate when making significant architectural choices, documenting technical trade-offs, proposing major refactorings, or authoring ADRs.

Version: v0.1.1 License: Apache-2.0 Author: Daniela Petruzalek (daniela@danicat.dev) Digest: b3c58d5e
0
Workspace Install
npx skills add danicat/skills --skill adr-template -y
Global Install
npx skills add danicat/skills -g --skill adr-template -y
JIT Load (On-demand streaming into context)
kungfu load adr-template
Learn (Persist locally or globally with -g)
kungfu learn adr-template
📄 Raw SKILL.md 🐙 GitHub Source ← Back to Catalog

Architecture Decision Records (ADRs) #

Use this skill to write and maintain Architecture Decision Records (ADRs). ADRs are lightweight, plain-text files that capture architectural choices, their context, and their consequences.

1. Core Philosophy #

Architecture consists of decisions that are hard to change. ADRs prevent two primary engineering problems:

  • Context Loss: Future developers often struggle to understand why code was written a certain way, leading to regressions when they remove constraints they do not see. ADRs record the underlying rationale.
  • Discussion Decay: ADRs capture the final conclusion and the forces that shaped it, rather than every detail of the debate.

2. Rules of ADRs #

❗ IMPORTANT
- Keep ADRs lightweight. Limit each record to one or two pages. An ADR is a record of a decision, not a comprehensive design specification.
- ADRs are immutable logs. Do not edit an approved and committed ADR. If a decision changes, write a new ADR and update the status of the old one to "Superseded by ADR-NNNN".
- Document consequences and trade-offs. Every architectural choice has downsides. Explicitly list negative consequences, technical debt, and new constraints.

3. Directory and Naming Conventions #

Store all ADRs in the project documentation folder:

text 
design/adr/
  ├── 0001-record-architecture-decisions.md
  ├── 0002-use-stdio-mcp-transport.md
  └── 0003-transactional-compiler-gated-editing.md
  • File format: Markdown (.md)
  • Naming pattern: NNNN-short-descriptive-title.md where NNNN is a sequential four-digit number starting at 0001.

4. Standard ADR Template #

Use this template when creating an ADR:

markdown 
# ADR-[Number]: [Active Verb Title]

- Status: [Proposed | Approved | Superseded by ADR-XXXX | Rejected]
- Date: [YYYY-MM-DD]
- Author(s): [Names]
- Deciders: [Names of participants in the decision]

## 1. Context
Describe the current situation, background context, and the problem to solve. What technical, organizational, or operational factors are at play? What constraints apply? State facts objectively.

## 2. Decision
State the chosen architectural path clearly. Explain why this path was selected over alternatives. List the other options considered and the reasons for rejecting them.

## 3. Consequences
Detail the impact of this decision. Explicitly list positive gains, negative trade-offs or constraints, and neutral structural shifts.

## 4. Compliance and Verification
How will the team verify that this decision is respected and implemented correctly? Detail the specific automated tests, pipeline checks, or manual hooks that enforce compliance.

5. Verification Checklist #

Before finalizing an ADR, verify the following:

  • Does the ADR clearly state the forces involved?
  • Does it document the alternatives that were discarded?
  • Is the tone objective and factual, avoiding unquantifiable words like "perfect", "flawless", or "elegant"?