ADR Format Validation Workflow - AI Engineering Book from SovIAR

ADR-26017: ADR Format Validation Workflow¶

Title¶

ADR Format Validation Workflow

Date¶

2026-02-01

Status¶

proposed

Context¶

Architecture Decision Records (ADRs) are critical governance artifacts that document significant technical decisions. Without consistent format enforcement, ADRs can drift in structure, making them harder to maintain and parse programmatically.

Previous validation (check_adr.py) only covered:

Index synchronization
Status value validation
Title consistency between header and frontmatter

Missing validations led to inconsistent ADRs:

Some lacked required frontmatter fields (id, date, tags)
Date formats varied (ISO vs text dates)
Tags were undefined or inconsistent
Required sections (Context, Decision, Consequences) were sometimes missing

The ADR template (adr_template.md) defined expected structure, but there was no automated enforcement.

Decision¶

We will implement comprehensive ADR format validation in check_adr.py with config-driven rules stored in adr_config.yaml.

Validation rules added:

Required frontmatter fields: id, title, date, status, tags
Date format: Must match YYYY-MM-DD (ISO 8601)
Tag validation: Only tags from predefined list in config
Required sections: Context, Decision, Consequences, Alternatives, References, Participants

Migration support:

New --migrate flag to add YAML frontmatter to legacy ADRs
Extracts status from ## Status section
Uses file modification date as date field
Adds default tags

Single Source of Truth: All validation rules defined in adr_config.yaml to avoid drift between template and validator.

Consequences¶

Positive¶

Consistent ADR format across all records
Early error detection during CI/pre-commit
Self-documenting configuration (adr_config.yaml)
Legacy ADRs can be migrated automatically
ADRs are parseable by other tools (documentation generators, search)

Negative / Risks¶

Initial migration effort for non-compliant ADRs. Mitigation: --migrate flag automates frontmatter generation.
Stricter validation may require updates to existing ADRs. Mitigation: Run --verbose to identify issues before enforcement.
Adding new tags requires config update. Mitigation: Config is version-controlled and documented.

Alternatives¶

Manual review only: Rejected - doesn’t scale, inconsistent enforcement.
Separate linter tool: Rejected - adds dependency, duplicates ADR parsing logic.
JSON Schema validation: Rejected - YAML frontmatter validation needs custom logic for section detection.
IDE-based validation: Rejected - not portable across editors, no CI integration.

References¶

Participants¶

Claude Code (implementation)
Repository maintainers (review)