brogeby
c48b6e9c94
Add AGENTS.md, CLAUDE.md, and the agents-docs/ tree (workflow, lessons, engineering standards, context map, ADR seed, feature template) plus a domain-bearing CONTEXT.md for each of the six subdomains: toju-app, electron, server, e2e, website, docs-site. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
14 lines
1.2 KiB
Markdown
14 lines
1.2 KiB
Markdown
# ADR-0001: Record Architectural Decisions
|
||
|
||
## Status
|
||
Accepted
|
||
|
||
## Context
|
||
We need a lightweight way to record architectural decisions so that future agents and engineers can understand *why* the system looks the way it does, not just *what* it does. Without ADRs, decisions live in PR descriptions, chat logs, or nowhere — and get re-litigated on every refactor.
|
||
|
||
## Decision
|
||
We use Architecture Decision Records (ADRs) in the Nygard short form. Each ADR lives at `agents-docs/adr/NNNN-slug.md` with a 4-digit zero-padded number, monotonically increasing. The minimum content is a title plus 1–3 sentences each for Context, Decision, and Rationale. Add `Status`, `Considered Options`, or `Consequences` only when they genuinely help.
|
||
|
||
## Rationale
|
||
Nygard short form is the lowest-friction format that still captures the *why*. Heavier templates (MADR, full IEEE 1471) routinely don't get written — the bar to start one is too high. ADRs are append-only: a superseded decision gets a new ADR with a `Supersedes ADR-NNNN` note while the old one stays in place. The 3-criteria gate (hard to reverse, surprising without context, genuine trade-offs) keeps the directory from filling with trivia. See `agents-docs/AGENTS_ADRS.md` for the full contract.
|