Move one spelling per goal into the technical principles as DRY read as knowledge

This commit is contained in:
2026-10-01 18:05:52 +02:00
parent 4eb41a00a6
commit 26877dc761
2 changed files with 5 additions and 9 deletions
-7
View File
@@ -36,13 +36,6 @@ Shorter is better, none is best — chat output, commit messages, comments, docs
The design rules every project follows, compose-not-entangle first: `~/.claude/principles/technical-principles.md`. Read it before designing or reviewing code.
## One spelling per goal
- **One authoritative home per fact.** A value, rule or definition lives in one place, and everywhere else derives it from there or points at it. A copy that can drift is a second spelling: derive it from its owner, or, for config a human writes, reject it where it is read and name the owner.
- **One obvious way per need.** Before adding a way to do something, find the existing one and use it. Where two spellings serve the same caller for the same need, keep one and reject the other as early as possible — at load, parse or compile — with an error naming the one to use: `token {p} renders a level that {p.first} reads a path into; name the fields you want instead`.
- **Different needs may have different ways.** A public API may offer a convenience beside the general form — a one-line call for the common case over the primitive for the rest — where each serves a caller or scenario its docs name, and the convenience is built from the primitive. Code that looks alike but encodes different knowledge is not a second spelling: merging it is the wrong abstraction.
- **Two spellings that can disagree are a correctness bug**, whatever the reason for having both: derive one from the other, or reject the combination.
## Working loop
How work proceeds in any repo, unless that repo's `AGENTS.md` says otherwise.
+5 -2
View File
@@ -48,8 +48,11 @@
- 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).
- Keep solutions simple and easy to understand, so it is dead easy to grasp what they do.
* Don't Repeat Yourself (DRY).
- Reuse code instead of duplicating it; one concept, one implementation.
* Don't Repeat Yourself (DRY): one authoritative home per piece of knowledge, one obvious way per need.
- A value, rule, definition or concept lives in one place, and everywhere else derives it from there or points at it. A copy that can drift is a second spelling: derive it from its owner, or, for config a human writes, reject it where it is read and name the owner.
- Before adding a way to do something, find the existing one and use it. Where two spellings serve the same caller for the same need, keep one and reject the other as early as possible — at load, parse or compile — with an error naming the one to use: `token {p} renders a level that {p.first} reads a path into; name the fields you want instead`.
- Different needs may have different ways. A public API may offer a convenience beside the general form — a one-line call for the common case over the primitive for the rest — where each serves a caller or scenario its docs name, and the convenience is built from the primitive. Code that looks alike but encodes different knowledge is not a second spelling: merging it is the wrong abstraction.
- Two spellings that can disagree are a correctness bug, whatever the reason for having both: derive one from the other, or reject the combination.
* All critical flows should have good traces, from where something was initiated until it completed.
- Use traceparent OTLP and standardized logging for this.
* Prefer the vendor-neutral option, and know what leaving would cost.