Skip to content
ADR Guard

Choose an ADR template or format

Português (Brasil) · Documentation home · Previous · Next

Choose the lightest option that makes the decision and its trade-offs understandable. The matrix distinguishes authoring support from validation support.

Option Best fit Detail and trade-off ADR Guard support
Minimal Focused, low-to-moderate complexity choice with a clear rationale Lowest ceremony; author must include meaningful costs and rationale in the core sections Generated by new/draft with --template minimal; validated by the default canonical mode
Extended Higher-impact, contested, cross-team, or operationally risky choice Explicit drivers, options, rationale, positive/negative consequences, risks, and references Generated by new/draft with --template extended; validated by the default canonical mode; not MADR
Custom A team needs extra canonical sections or organization-specific prompts Flexible guidance, but strict structural and placeholder constraints; maintenance belongs to the team One local file via --template-file; rendered result remains canonical and starts Proposed
MADR 4.0 Teams already use MADR or want its option/outcome structure External format with decision drivers and option analysis; metadata and supported sections differ from canonical ADRs Opt-in validation/indexing with --adr-format madr-4; no built-in new MADR generator

Selection heuristics

Section titled “Selection heuristics”
  • Start with Minimal when a reviewer can understand the problem, choice, rationale, and balanced consequences without separate analysis sections.
  • Move to Extended when options, quality attributes, risks, migration, or several stakeholders need explicit treatment.
  • Use Custom to make recurring team-specific questions visible while retaining the canonical contract. Do not use it to invent a new validation format.
  • Use MADR 4.0 when interoperability with MADR or its decision-outcome structure is a deliberate team choice. Keep it in its own validation set.

Do not select a larger template simply to make a decision look important. A concise complete ADR is better than a long document filled with placeholders.

Exact command boundaries

Section titled “Exact command boundaries”
Terminal window
# Canonical generation and validation
adr-guard new docs/adr --title "Choose the order system of record" --template minimal
adr-guard new docs/adr --title "Choose the order system of record" --template extended
adr-guard new docs/adr --title "Choose the order system of record" --template-file docs/templates/team.md
adr-guard check docs/adr


# Separately authored MADR records, validated in a separate directory
adr-guard check docs/decisions --adr-format madr-4

minimal and en-US are defaults for new. See offline creation, custom template constraints, and MADR compatibility before adopting a non-default option.