14. Lightweight ADR Tooling

Status

Accepted — 2026-04-19

Context

ADR 0001 established the ADR practice and noted it is “lightweight and low-friction” with “no tooling required.” It also acknowledged the enforcement gap: “ADRs get written only if the author remembers to write them. Drift between actual architecture and documented decisions is possible and will not be caught automatically.”

With 13 ADRs and growing, a multi-agent Claude Code workflow (ADR 0009) that reads ADRs to validate proposed changes, and no index or format validation, three problems have emerged:

  1. No discoverability. The only way to find ADRs is to list the directory or grep. Agents and humans scanning the repo have no table of contents.
  2. No format enforcement. A missing section, mismatched title number, or unrecognized status keyword would go unnoticed until someone reads the file closely.
  3. No scaffolding. Creating a new ADR means remembering the Nygard sections and manually picking the next number.

After evaluating the ecosystem (log4brains, adr-tools, @meza/adr-tools), none fit cleanly: log4brains requires date-based filenames incompatible with the existing NNNN- convention, and the CLI tools are either bash-only or unmaintained. A custom solution matching the existing tools/lint/ pattern is the right fit.

Decision

Add a minimal TypeScript toolset in tools/adr/ with three npm scripts:

  • adr:validate — checks filename format, required Nygard sections, title/number consistency, status keywords, and cross-references. Wired into npm run build after lint:boundaries.
  • adr:toc — generates docs-site/architecture/decisions/README.md with a Markdown table between <!-- adrlog --> markers.
  • adr:new "Title" — scaffolds the next-numbered ADR from a Nygard template with Proposed status.

The tooling uses zero external dependencies (Node.js built-ins only) and follows the tools/lint/check-shared-boundaries.ts pattern: standalone tsx-run scripts, process.exit(1) on failure, terse success output.

CLAUDE.md is updated with heuristics for when a change warrants a new ADR, so agents proactively surface the question rather than waiting for the author to remember.

Consequences

  • Format errors are caught in the build pipeline. This closes the enforcement gap acknowledged in ADR 0001 without adding friction to the writing process itself.
  • New ADRs start from a consistent template, reducing the chance of missing sections.
  • The README table provides a scannable index for both humans and agents, improving discoverability.
  • The tooling is deliberately minimal: it does not manage status transitions, auto-number amendments, or generate changelogs. These remain manual editorial decisions.
  • ADR 0001’s statement “no tooling required” is amended by this decision. The process is still lightweight — the tooling assists and validates, it does not gate or constrain.