Move one spelling per goal into the technical principles as DRY read as knowledge
This commit is contained in:
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user