diff --git a/AGENTS.md b/AGENTS.md index 33de5fb..82b4b6b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -56,8 +56,20 @@ docs/TECHNICAL-DESIGN.md docs/BACKUPS.md # backup, verification and restore runbook docs/DEPLOYMENT.md # deploy, rollback and operations docs/HANDOFF.md # next task prompt and backlog +docs/adr/ # one file per irreversible decision ``` +## Documentation Policy + +Docs capture decisions and current state, never session narration. + +- **Allowed:** this file, `README`, `docs/TECHNICAL-DESIGN.md`, `docs/adr/NNN-*.md` (one decision: + context, options, decision, consequences), the runbooks (`BACKUPS`, `DEPLOYMENT`) and + `docs/HANDOFF.md`. +- **Forbidden:** phase reports, progress logs, "what I did" narration and per-session summaries. + When a change needs a durable record, update the design doc or add an ADR — do not create a + report file. This applies to AI output too. + ## Commands | Task | Command | diff --git a/docs/adr/README.md b/docs/adr/README.md new file mode 100644 index 0000000..cd85033 --- /dev/null +++ b/docs/adr/README.md @@ -0,0 +1,9 @@ +# Architecture Decision Records + +One file per irreversible or costly decision: `NNN-title.md` with **Context**, **Options**, +**Decision** and **Consequences**. Written by the human, in a few paragraphs — not generated as a +report. + +Use an ADR when a choice is hard to reverse or future-you needs the *why* (money as `long`, money +in exact pesos, ownership enforced twice, history indestructible). For everyday changes, update the +relevant [spec](../specs/) and the code instead.