Gabriel Brown
89761a7da3
Agent instructions, skills, SSH host aliases and expansion triggers are worth having identical on every machine one person owns, and belong in none of the shared configuration. They live in user/ now, with a manifest saying where each piece goes and a link-user stage that puts it there. That stage does nothing unless the machine said yes. Somebody who clones Panama to try the desktop keeps their own ~/.claude/CLAUDE.md exactly where it was; the question names the destinations and defaults to no. Anything displaced goes to config/old rather than being deleted. ~/.claude/CLAUDE.md and ~/.codex/AGENTS.md were byte-identical copies of one file, which is the drift this exists to prevent. Also adds the vitals toggles for the battery and Claude usage readouts, which had preferences and no way to reach them.
53 lines
2.3 KiB
Markdown
53 lines
2.3 KiB
Markdown
# ADR format
|
|
|
|
ADRs live in `docs/adr/`, numbered sequentially: `0001-slug.md`, `0002-slug.md`. Scan the directory
|
|
for the highest existing number and increment. Create `docs/adr/` lazily, only when the first ADR is
|
|
needed.
|
|
|
|
## Template
|
|
|
|
```md
|
|
# {Short title of the decision}
|
|
|
|
{One to three sentences: the context, what was decided, and why.}
|
|
```
|
|
|
|
That is the whole template. An ADR can be a single paragraph. The value is in recording *that* a
|
|
decision was made and *why*, not in filling out sections.
|
|
|
|
## Optional sections
|
|
|
|
Include these only where they add something. Most ADRs need none of them.
|
|
|
|
- **Status** frontmatter (`proposed | accepted | deprecated | superseded by ADR-NNNN`): useful once
|
|
decisions start getting revisited.
|
|
- **Considered options**: only where the rejected alternatives are worth remembering.
|
|
- **Consequences**: only where a non-obvious downstream effect needs calling out.
|
|
|
|
## When an ADR is warranted
|
|
|
|
All three must hold:
|
|
|
|
1. **Hard to reverse.** An easy decision to reverse does not need a record; it will simply be
|
|
reversed.
|
|
2. **Surprising without context.** If nobody would wonder why, nothing needs explaining.
|
|
3. **The result of a real trade-off.** With no genuine alternative there is nothing to record beyond
|
|
"we did the obvious thing."
|
|
|
|
### What qualifies
|
|
|
|
- **Architectural shape.** "The write model is event-sourced; the read model is projected."
|
|
- **Integration patterns between contexts.** "Ordering and Billing communicate via domain events, not
|
|
synchronous HTTP."
|
|
- **Technology choices carrying lock-in.** Database, message bus, auth provider, deployment target.
|
|
Not every library: the ones that would take a quarter to swap.
|
|
- **Boundary and scope decisions.** "Customer data is owned by the Customer context; others reference
|
|
it by ID only." The explicit noes are as valuable as the yeses.
|
|
- **Deliberate deviations from the obvious path.** "Manual SQL instead of an ORM, because X."
|
|
Anything a reasonable reader would assume the opposite of. These stop the next engineer from
|
|
"fixing" something deliberate.
|
|
- **Constraints invisible in the code.** "Response times must stay under 200ms because of the partner
|
|
API contract."
|
|
- **Rejected alternatives where the rejection is non-obvious.** Picking REST over GraphQL for subtle
|
|
reasons earns a record, or someone proposes GraphQL again in six months.
|