agf-writing-adr

# Writing an ADR (Architecture Decision Record) Use this skill when: - A new technology / framework / vendor is being added to the stack (not already covered by ADR-000) - An existing baseline is being **deviated from** (e.g. swapping Postgres → SQLite for a specific service) - A cross-cutting decision needs explicit record (auth scheme, deployment shape, observability stack, LLM caching policy) - code-reviewer escalates a "this needs ADR" finding **Do NOT write an ADR for**: - Routine library version bumps (lockfile is enough) - Internal refactors that don't change external contract or stack - Bug fixes - Anything one team would forget within a month If unsure → write it. ADR cost is low; the "why" memory is what disappears. ## File path & numbering `docs/adr/NNN-[slug-kebab-case].md` — sequential, zero-padded 3 digits. Examples: - `001-jwt-vs-session-auth.md` - `002-llm-caching-policy.md` - `003-deploy-target-fly-io.md` ADR-000 is reserved for the system architecture baseline. Never reuse a number; if abandoned, mark `Status: Superseded by ADR-NNN`. ## Status lifecycle `Proposed` → `Accepted` → (later) `Superseded by ADR-NNN` / `Deprecated`. Once `Accepted`, **do not edit decisions**; supersede with a new ADR. Allowed in-place edits on Accepted ADRs: - Backfill `## 版本与查证` rows when a deferred row resolves - Typos and broken links Anything else → new ADR. ## Required sections ```markdown # ADR-NNN: [Title] - 状态：Proposed / Accepted / Superseded by ADR-NNN / Depr...