Enforce Architecture Decision Records
Require every ADR to carry a single status, real context, a decision, and consequences.
A decision record with an empty Consequences section is a decision nobody finished thinking about.
Prompt for your coding agentOpen in Claude ↗
Add mediva to this repo (npm i -D mediva) and write docs/adr/_template.mdv.md. Write every new ADR in docs/adr so that npx mdv check docs/adr reports nothing; fix every finding before committing.
Starters are being rebuilt; write this by hand.
<!-- mdv: document strict ordered -->
<!-- mdv: section occurs=0..1 heading.mask="<text>" -->
# ADR 0007: Adopt structured JSON logging
<!-- mdv: section required content.lead.mask="<word|oneOf: [Proposed, Accepted, Rejected, Deprecated, Superseded]|ci>[.][ <text>]" -->
## Status
Accepted
<!-- mdv: section required content.words.min=15 content.none=@placeholders -->
## Context
Our services log free-form text, so on-call engineers cannot filter an incident's logs by request, tenant, or error class.
<!-- mdv: section required content.words.min=10 content.none=@placeholders -->
## Decision
Every service emits one JSON object per log line through the shared logger package.
<!-- mdv: section required content.words.min=10 content.none=@placeholders -->
## Consequences
Dashboards and alerts can query fields directly; ad-hoc print debugging now has to go through the logger.# ADR 0007: Adopt structured JSON logging
## Status
Maybe
## Context
We need to pick a logging approach soon.
## Decision
We will adopt structured JSON logging.
## Consequences
TBD
## Notes
randomadr-0007.md
Shape: fix the form; this does not change what the document claims
19 error Section "Notes" is not allowed here unexpected-section
help: Move the content into a declared section, or remove the section
✖ 1 problem (1 error, 0 warnings)
mdv explain <rule-id> for detailsstrict ordered locks the four sections; the # ADR … title is the one declared exception. Named _template., the contract covers every record in the folder, so npx mdv check in CI needs no flags.
Variations
| Want | Add |
|---|---|
an optional ## Alternatives Considered | occurs=0. before Consequences, or drop ordered |
| machine-readable metadata | front date date=iso (Frontmatter) |
| a cited driving issue | issue. on Decision |