Lightweight ADR (Architecture Decision Record) convention — engineering/process decisions as one-screen records. MIT.

LICENSE

MIT License

Copyright (c) 2026 Yakiv Kramarenko

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

lightweight-adr-convention.md

title	Lightweight ADR convention
created	2026-06-24
type	convention
license	MIT © 2026 Yakiv Kramarenko

Lightweight ADRs — engineering & process decisions

A minimal Architecture Decision Record convention: record engineering/process decisions ("how we work") as one-screen ADRs an agent or a human can write and read cheaply. One file per decision: ADR-NNN-short-title.md.

Scope is engineering/process only. Product/feature decisions live with their feature (next to the feature's own docs), not here.

To add one: copy the template below, take the next number, start at status: proposed. Propagation: a decision that changes a documented convention updates that doc in the same pass.

Expanded version — a fuller home with worked example ADRs: https://github.com/automician/adrs-for-agents (MIT). This gist is the original standalone form.

ADR format

Frontmatter + four sections. Minimum for a terse one-off: id + status + date + ## Decision; in practice fill all four.

---
id: ADR-001
status: proposed # proposed | accepted | superseded | deprecated
date: 2026-06-24
tags: [docs] # grep/index aid — keep present
# supersedes: ADR-NNN   # only when this replaces another
# superseded-by: ADR-NNN
---

# ADR-001: <outcome-implying title>

## Context

<situation / forces / why now.>

## Decision

<For accepted: the decision as flat prose. For proposed: open the heading or
first line with a working-hypothesis marker and the event that would verify it —
`## Decision (proposed — working hypothesis)` or
`**Proposed (working hypothesis).** Verified by <event>.` — then the question
and candidate options. Options read well as labeled `Alternative A / B / C`
bullets, each with a `Cost:` / `Risk:` line, the pick tagged `(this proposal)`.>

## Consequences

<trade-offs accepted, follow-ons, what this enables or blocks.>

## Trigger to revisit

<the event/condition that reopens this — or "never". For a proposed ADR, prefer
two gates: **Move proposed → accepted when:** … and **Move to superseded /
deprecated when:** ….>

Statuses

• proposed — drafted and recommended (or an open decision-shaped question); awaiting a decision. This is "ready for review".
• accepted — the decision is ratified.
• superseded — replaced by a later ADR (superseded-by:); kept, never deleted — the record of the reversal is the value.
• deprecated — no longer applies, no direct successor.

Conventions

• Number = permanent identity. ADR-NNN is the stable handle — cite the number, never the path. Numbers are never reused (not across supersession, not to fill gaps), so files can be renamed or re-grouped later (e.g. a topic suffix once the log spans multiple areas) without breaking a reference.
• tags keep the log greppable — filter by topic in search.
• Refs are grep-derived, not indexed. Link related docs inline where relevant; no maintained cross-ref index. When related docs genuinely have no inline home, gather them in a trailing ## Connected section — residual only, not an index of everything.
• Amend in place. When later work refines a landed ADR, add a dated bullet in Consequences (**Update YYYY-MM-DD:** …) leaving the original prose intact — no separate changelog.
• Decision-meta stays visible. Status markers, working-hypothesis caveats, verifying events, dated amendments are decision-bearing — keep them in body prose. Only pure provenance/process asides go in <!-- -->.