Merge main into claude-md-router
# Conflicts: # CHANGELOG.md # todo.md
This commit is contained in:
@@ -4,6 +4,7 @@
|
||||
|
||||
- `CLAUDE.md` keeps only the rules no file path can scope. The rules for `todo.md` items, comments, decisions and READMEs moved to files under `rules/`. Claude Code loads each one when a session reads or writes a matching file. `loop-claude`'s judge reads them beside `CLAUDE.md`, and the prose and stability reviewers read them where they once read `CLAUDE.md`.
|
||||
- A README no longer holds cross-cutting decisions; `docs/decisions.md` does.
|
||||
- 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.
|
||||
|
||||
@@ -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*. In Ousterhout's terms: prefer deep modules (simple interface, real work hidden) over shallow ones; 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
|
||||
|
||||
@@ -12,6 +12,16 @@
|
||||
- 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 — 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: 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.
|
||||
* Always store timestamps as full ISO datetime in UTC.
|
||||
@@ -51,11 +61,6 @@
|
||||
- A default earns its place where most callers want the same value, a wrong guess does no harm, and the caller can see and change it through a `--help` line or a documented option. Anything else is asked for.
|
||||
- Defaults live at the program's edge: a CLI, a config file, a library's public API. A library still asks for every input that can change between runs, such as data, the clock and randomness; only the code that wires a program together, such as its CLI, defaults those, as "Functional core, imperative shell" asks.
|
||||
- BANNED: a CLI that refuses to run until given `--data-path` and `--seed`, when nearly every run wants the shipped data and fresh randomness. GOOD: it uses the shipped data and fresh randomness unless a flag overrides them, and `--help` names those flags.
|
||||
* 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.
|
||||
- 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.
|
||||
* 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.
|
||||
- An import sorts on its first binding, not its path, so moving or renaming a module reorders nothing. Where lines already group by kind — type imports, host packages — the key sorts within each group.
|
||||
|
||||
Reference in New Issue
Block a user