add-adr

Add an ADR

An ADR captures one architecturally significant decision — what was decided, why, and what was rejected. The set lives in docs/adr/, is managed by Log4brains (.log4brains.yml), and is published as a static site from main.

ADRs are immutable. Once merged, the only thing that changes is the status. A decision that gets reversed doesn't get edited — it gets a new ADR, and the old one is marked superseded by [link]. Write it as a record of what was true on the date, not as living documentation.

When it earns an ADR

Write one when the decision constrains future work and someone will later ask "why is it like this?" — a framework or library choice, a persistence or hosting pattern, a convention every slice has to follow. Skip it for reversible implementation details, bug fixes, and anything a code comment covers.

1. Filename

YYYYMMDD-<kebab-slug>.md, where the date is when the decision was made, not when the record was written.

The slug usually leads with the category, but it isn't mandatory — both shapes exist in the repo:

20251018-api-use-fastendpoints-instead-of-minimal-apis.md
20260515-vertical-slices-use-a-folder-per-slice.md
20260612-use-aggregate-specification-classes-with-factory-methods.md

2. Start from the template

Copy docs/adr/template.md. It carries the full section structure with inline <!-- --> guidance on what each part is for and which are optional. Don't hand-roll the skeleton — the template is the source of truth for the shape.

docs/adr/index.md is the Log4brains site homepage, not a manual index. There is nothing to register — dropping the file in docs/adr/ is enough.

3. Title

H1, pattern [Category] - [Decision], or just the decision when no category fits:

• API - Use FastEndpoints instead of Minimal APIs
• Database - Use SQL Temporal Tables when data auditing is required
• Use Aggregate Specification Classes with Factory Methods