Skip to main content

4. Use adr-tools for adr

Date: 2025-04-17

Status​

Accepted

Context​

Architecture Decision Records (ADRs) have proven valuable for documenting technical decisions, but managing them manually can be cumbersome. We need a tool that can:

  • Create new ADRs with consistent formatting
  • Maintain proper numbering sequences
  • Generate indexes and navigation
  • Integrate with our existing toolchain
  • Be simple enough for all team members to use

We evaluated several options:

  • Manual management: Too error-prone for numbering and formatting
  • Custom scripts: Would require maintenance overhead
  • adr-tools: Mature, simple CLI tool with good community support
  • Other ADR tools: Either too complex or lacking features we need

Decision​

We will use adr-tools (https://github.com/npryce/adr-tools) for managing our Architecture Decision Records.

Key factors in this decision:

  • Simple command-line interface that's easy to learn
  • Handles numbering and basic formatting automatically
  • Can be installed via ASDF, aligning with our tool version management strategy
  • Mature project with good community support
  • Lightweight with minimal dependencies

Consequences​

What becomes easier:​

  • Creating new ADRs with consistent formatting and numbering
  • Maintaining proper sequence of decision records
  • Onboarding new team members to ADR process
  • Integration with our ASDF-managed development environment

What becomes more difficult:​

  • Dependency on external tool for ADR management
  • Limited customization options for ADR templates

Risks to mitigate:​

  • Tool abandonment risk is low due to simplicity and maturity
  • Backup plan: ADRs are plain markdown files, easily portable to other tools
  • Ensure all team members have adr-tools installed via ASDF