Add functional core, imperative shell to the technical principles, and let a decision link one

This commit is contained in:
2026-09-30 22:55:22 +02:00
parent 4bc8aae9c8
commit 888206cac5
2 changed files with 5 additions and 1 deletions
+1 -1
View File
@@ -112,7 +112,7 @@ How work proceeds in any repo, unless that repo's `AGENTS.md` says otherwise.
**The inversion: a decision record owns what a call site may not say.** A rejected alternative, or what something deliberately does not cover, is banned beside the code precisely because the decision record holds it — a standing choice a future reader would otherwise relitigate, where a `CHANGELOG` holds what changed in a release. **The decision log has one home: `docs/decisions.md`**, or `docs/decisions/` split by area once it outgrows one file. `AGENTS.md` carries a one-line index of the titles, so a session or a reviewer sees that a decision exists without loading its reasoning. An entry states the decision, its date, who made it, and the premise it rests on ("valid while X") so it can expire honestly when that premise dies. A decision found anywhere else — an `AGENTS.md` body, a comment, or a README section that is neither a goal nor how one is met — moves there and leaves its index line behind. A goal stays a goal in the README; the log records only what the goal leaves open.
**Every decision links to a goal.** An entry names the goal it serves; one that cannot is a missing goal, and an entry already in the repo with no goal behind it is a finding. Propose the goal, never a reason of your own — the ask rule above says how.
**Every decision links to a goal or a technical principle.** An entry names the goal it serves or the principle in `~/.claude/principles/technical-principles.md` it applies; one that can do neither is a missing goal, and an entry already in the repo with neither behind it is a finding. Propose the goal, never a reason of your own — the ask rule above says how.
**Link, don't inline — and keep the link bare.** A mechanism identical across call sites or repos is documented once in the canonical source and pointed at with a one-line bare link. Don't summarize what's behind the link or restate the identifier's own name.
+4
View File
@@ -32,6 +32,10 @@
- Example set order.client_firstname instead of order.client_id and fetching firstname from the clients table.
* Explicit over implicit.
- Avoid magic, avoid "clever" solutions, only abstract when the API can clearly describe what is happening.
* Functional core, imperative shell.
- Decisions live in pure functions, data in and data out; the shell around them performs the effects and holds no branching of its own.
- Every side effect comes from outside: output, time, randomness, network and storage are injectable, so a test runs exactly the code production runs.
- BANNED: `new Date(entry.msTimestamp ?? Date.now())` in a formatter; a test swapping `globalThis.fetch`. GOOD: the clock is a parameter, defaulted to the system clock only where the program is wired together.
* Deterministic order wherever order carries no meaning.
- Sort it, on a key that does not move: the name a line introduces, never where it came from. A sorted list is searchable, its diff shows only what changed, and two edits to it conflict only where they mean to.
* Keep It Simple, Stupid (KISS).