How NCode.Extensions.DataProtection records its decisions: one short Markdown file per decision, kept in this folder and changed in the same pull request as the code it explains.
Write a record for a non-obvious choice that someone would otherwise question again: a design with real alternatives,
a trade-off that looks wrong without its reasons, or a departure from the project template. The conventions themselves
go in AGENTS.md or the instruction files it lists; a record explains why a convention is what it is.
/analyze-decision compares the options and writes one. Work bigger than one plan starts as a design document in
docs/designs/, from its template, and each of its decisions becomes a record here when its
phase lands.
- Copy 0000-template.md to
NNNN-kebab-case-title.md, starting from1000. Numbers below 1000 are the project template's, in project-template/, so an ADR number names one record across both folders..template/Test-AdrIndex.ps1fails a new record numbered below 1000; records the project already had keep their numbers. - Take a number no one else holds. Fetch first, then take the next number above both the highest record numbered 1000
or more on
origin/<default branch>and any record an open branch, pull request or worktree is writing. Check again after rebasing or merging the default branch, and when the number was taken meanwhile, renumber the file, its title, its index row and every link to it. Two records never share a number;.template/Test-AdrIndex.ps1fails when they do. - Add the record to the index below, in the same change.
Proposed: the decision is open.Accepted: the decision holds.Deprecated: the decision no longer applies, and nothing replaces it.Superseded by NNNN: a later record replaces it whole.
Never rewrite the decision of an accepted record; fixing a typo or a broken link is fine. A changed decision is a new
record, and the old record's status and index row say so. When the new record changes only part of the old one, the
old one stays Accepted with a note, "Accepted (amended by NNNN)", and the new one's index row says "(amends NNNN)".
The old record's text is not edited beyond its status line.
A record is a decision the project made, not an authority. Where an external standard or current security practice governs, it wins: a record that conflicts with one is superseded to align with it, never cited to justify the deviation.
- Write every section in the present tense, so it reads the same a year later: what is, and why. Avoid words that date it, such as "now", "new", "currently", "previously", "originally", "we decided to change" or "the first version"; the history belongs in the commit log and in the records a record supersedes.
- Give a volatile fact (a price, a quota, a limit, a supported version) its source and the date it was read, and mark an estimate as an estimate.
- Keep a record short, and link to the code, issues and records it depends on rather than restating them.
The project template's own decisions are in project-template/. Template updates replace
that folder. To decide otherwise, write a record here that says "Supersedes: project-template ADR-NNNN" and list the
override in AGENTS.md.
This project has no decision records of its own yet; its records are numbered from 1000. The template's are in project-template/.
| ADR | Decision | Status |
|---|