Answer prose round 1: functional core is a rule no other principle overrides, the banned call order is one only memory enforces, the changelog states the principle's exception as written, and one list of injected inputs

This commit is contained in:
2026-10-13 00:33:07 +02:00
parent 42b6caf2dc
commit 9f9dfc7245
3 changed files with 5 additions and 5 deletions
+1 -1
View File
@@ -2,7 +2,7 @@
## Unreleased
- A technical principle, "Prefer deep modules": a small, intuitive interface in front of a lot of hidden work, which hides how it works but never what it depends on. It wins over "Explicit over implicit" unless it makes a call harder for someone new to the project to follow. "Functional core, imperative shell" moves up to second place and is enforced as strictly as "Compose, do not entangle". The systems architect holds modules to the principle instead of its own wording.
- A technical principle, "Prefer deep modules": a module puts a small, intuitive interface in front of a lot of hidden work, and hides how it works but never what it depends on. It wins over "Explicit over implicit" unless hiding the work makes it harder for someone new to the project to tell what a call does. "Functional core, imperative shell" moves up to second place, a core rule beside "Compose, do not entangle" that no other principle overrides. The systems architect holds every module to it.
- A hook blocks each Bash, Edit, MultiEdit and Write call that breaks a rule a program can check: a commit message that is not one line passed with `-m`, a Claude or Anthropic attribution, a container image short of a full patch version, an Action pinned to anything but a semver tag, an unsorted block in an ignore file, and a commit of a `todo.md` that `rank_todo.py --check` rejects. `CLAUDE.md` states those rules only where the hook cannot check them; `~/.claude/bin/rule-hook --help` states what it checks. A call overrides a rule with `# rule-override <rule>: <reason>`. larv-review's new overrides pass, run before stability, accepts or rejects each override the chunk logged, and the PR body lists each with its ruling; a rejected override means the chunk keeps the rule. An override that touches a credential, a security rule or a production system, or cannot be undone, is asked of you.
- A project may opt out of larv-review's architect, product-owner pass or comprehension check in every chunk, through a `docs/decisions.md` entry titled `review opt-out: …` that names the goal that skipping them serves. A project without such an entry is reviewed as before. Opting out of the comprehension check also skips the scoring run due at a release's end, so the floor blocks nothing; the opt-out ends with a chunk that ships a plan item naming the floor, which removes the comprehension check from the entry. The principles audit always runs.
- A README goal states the project's aim and intent, and no longer names a step of the work, such as "kill weak candidates early". Such steps go in a method section further down the README and name the goal they serve.
+1 -1
View File
@@ -17,7 +17,7 @@ You are an elite Systems Architect with decades of experience designing software
**Question the requirement, not just the structure.** Complexity with a reason is not automatically worth its cost. For every complexity hotspot — reasoned or not — name the requirement that forces it and sketch the simpler design that drops or relaxes it. When a near-equivalent solution achieves almost the same result far more simply, propose the trade and name the delta precisely ("drop per-source ordering → the entire reorder buffer disappears") so the owner can accept or reject it. A small, named loss of functionality bought with a large complexity reduction is one of the best wins available — surfacing that option is your job; deciding it is the owner's.
**Simple to reason about, not merely simple to call.** A clean external API over a core you cannot follow to the bottom is a shallow win. Trace the key data structures and core abstractions down to their foundation and confirm the core is genuinely simple to *understand*, not just convenient to *implement against*. Hold every module to "Prefer deep modules" in `~/.claude/principles/technical-principles.md`. Complexity is dependencies + obscurity, and it surfaces as change amplification (one change touches many places) and cognitive load (a reader must hold too much in their head). Hunt both, all the way down.
**Simple to reason about, not merely simple to call.** A clean external API over a core you cannot follow to the bottom is a hollow win. Trace the key data structures and core abstractions down to their foundation and confirm the core is genuinely simple to *understand*, not just convenient to *implement against*. Hold every module to "Prefer deep modules" in `~/.claude/principles/technical-principles.md`. Complexity is dependencies + obscurity, and it surfaces as change amplification (one change touches many places) and cognitive load (a reader must hold too much in their head). Hunt both, all the way down.
**Be non-pragmatic about fundamentals.** You are deliberately uncompromising on architectural choices that shape the system for years. Do not bend on:
- Functional core, imperative shell separation
+3 -3
View File
@@ -12,15 +12,15 @@
- Functions: a function takes what it needs as arguments and returns what it produces. One that works only after another has set up shared state, or leaves state for the next to find, is entangled with it. BANNED: `validate(conf)` that fills defaults `send(conf)` relies on. GOOD: `send(withDefaults(conf))`.
- Tests and tooling: a test, script or pipeline stage that passes only because another ran first is entangled; it states what it needs and gets it.
- Proximity is not a reason. Reusing a listener, config file, table, module or service because it is already there, when the new thing has no relationship to it, is how entanglement gets in. If you cannot name the seam, there is none.
* Functional core, imperative shell — enforced as strictly as "Compose, do not entangle".
* Functional core, imperative shell — a core rule beside "Compose, do not entangle": no other principle overrides it.
- 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.
- Keep delivery-layer entrypoints thin: inject services, validate + hand off the request data, map the service's return to a response. An entrypoint reaching into a payload to decide *what to do* is the smell. BANNED: `if (body.tx.source === 'notification') { /* drop, skip enqueue */ }` in a route handler. GOOD: the entrypoint forwards `source` on the event → the service decides drop-vs-process and returns a result → the entrypoint maps that result to a status code.
* Prefer deep modules: a small, intuitive interface in front of a lot of hidden work.
- A caller should know what a call does and what it returns, without knowing how it does it. `fs.writeFile("notes.txt", data)` hides opening the file, encoding, buffering, permissions and the disk itself. Yet anyone reading that line knows the outcome: the data is written, or the call fails and says why.
- A module hides how it works, never what it depends on. The clock, randomness, data and storage still come in from outside, as "Functional core, imperative shell" requires.
- A shallow module costs more to learn than it saves. BANNED: a wrapper that only renames the function it calls; a module whose callers must make three calls in the right order. GOOD: one call that does the whole job and handles the order itself.
- A module hides how it works, never what it depends on: what "Functional core, imperative shell" injects stays injected.
- A shallow module costs more to learn than it saves. BANNED: a wrapper that only renames the function it calls; a module whose callers must make three calls in an order nothing but their memory enforces. GOOD: one call that does the whole job and handles the order itself.
- When this pulls against "Explicit over implicit", the deep module wins, unless hiding the work makes it harder for someone new to the project to tell what the call does.
* Make invalid states unrepresentable.
- Example: using a time-only type in the database when we actually want to store a time of day introduces risk for errors.