Answer the move review's first round
This commit is contained in:
@@ -102,7 +102,7 @@ Prose describing the code as it stands — a comment, a README, an `AGENTS.md`,
|
||||
|
||||
## Technical principles
|
||||
|
||||
The rules every project's code follows, compose-not-entangle first: `~/.claude/principles/technical-principles.md`. Read it before writing, designing or reviewing code.
|
||||
The rules every project follows, compose-not-entangle first: `~/.claude/principles/technical-principles.md`. Read it before writing, designing or reviewing code.
|
||||
|
||||
## Git, commits, and PRs
|
||||
- Never add `Co-Authored-By: Claude ...`, `🤖 Generated with Claude Code`, or any Claude/Anthropic/Agent marker in commits, PR bodies, issue comments, or anywhere else.
|
||||
|
||||
@@ -40,22 +40,22 @@
|
||||
* Handle errors explicitly, as values — avoid the exception path.
|
||||
- Enumerate the cases that can go wrong and return them as explicit results (e.g. a result DTO with an optional error), so failure is part of the signature instead of a hidden second channel.
|
||||
- try/catch lives only at the edges, wrapped tightly around the call that can actually throw (DB, HTTP, filesystem), converting the exception into an explicit result right there. Pure functions and core logic never throw or catch for control flow.
|
||||
- A function that both returns a result and throws for some inputs has two error channels; collapse to one. Exceptions are for truly unrecoverable states at boundaries.
|
||||
- A function that both returns a result and throws for some inputs has two error channels; collapse to one. Throw only for a truly unrecoverable state.
|
||||
* Commands and Queries Separation (CQS)-ish
|
||||
- Queries must never modify data, commands may only return data that is the result of their change.
|
||||
* Copy important contextual information on buisness transactions and equal data, instead of referencing it.
|
||||
- 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.
|
||||
- Prefer explicit, descriptive names over generic ones (`invoiceRowsService`, not `service`).
|
||||
* Name files and folders by what is inside.
|
||||
- BANNED: `scripts`, `utils`, `helpers`, `misc`, `common`, `lib`, `stuff`. GOOD: `e2e-tests/`, `db-migrations/`, `release-tooling/`.
|
||||
* Name things by what they are.
|
||||
- Identifiers: prefer explicit, descriptive names over generic ones (`invoiceRowsService`, not `service`).
|
||||
- Files and folders: name by what is inside. BANNED: `scripts`, `utils`, `helpers`, `misc`, `common`, `lib`, `stuff`. GOOD: `e2e-tests/`, `db-migrations/`, `release-tooling/`.
|
||||
- Group related artifacts by purpose — e2e compose files, e2e Dockerfile, and e2e test scripts all belong in `e2e-tests/`.
|
||||
* 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. Domain decisions and branching belong in the service layer — 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.
|
||||
- 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.
|
||||
- What to sort: attributes, array and object keys, enum members, imports, table rows, and line-based file lists such as `.gitignore`/`.dockerignore`. Exception: `id` goes first.
|
||||
@@ -78,5 +78,8 @@
|
||||
* Semantic versioning, read strictly: a minor only adds, and a major is the only release that changes what exists.
|
||||
- "Exists" is everything a consumer can depend on, not just signatures: an added output column, a removed list value, a changed default, the facts an error names, a dropped runtime version. A consumer takes a minor without editing code, data or scripts.
|
||||
- Batch breaking changes into few majors. Before 1.0.0 the minor is the breaking unit and a patch never breaks.
|
||||
* Prefer a standalone Python script with a `#!/usr/bin/env python3` shebang over a shell script — it runs identically across systems where shell dialects/builtins differ. Read config (credentials, hosts, paths) from CLI params or env vars, never hardcoded.
|
||||
* Indent with hard tabs by default. A project's own settings win: `.editorconfig`, linter/formatter config (Prettier, `rustfmt.toml`, …), or the surrounding file's existing indentation.
|
||||
* Scripts are standalone Python.
|
||||
- A Python script with a `#!/usr/bin/env python3` shebang runs identically across systems where shell dialects and builtins differ.
|
||||
- Read config (credentials, hosts, paths) from CLI params or env vars, never hardcoded.
|
||||
* Indent with hard tabs by default.
|
||||
- A project's own settings win: `.editorconfig`, linter/formatter config (Prettier, `rustfmt.toml`, …), or the surrounding file's existing indentation.
|
||||
|
||||
@@ -11,7 +11,7 @@ The rebuild lifts every dimension, one chunk per item, until the last item opens
|
||||
|
||||
## 0.2.0
|
||||
|
||||
- **Sort `bin/`'s imports on their first binding, per `principles/technical-principles.md` → "Deterministic order".** Today they sort by path, so a module move reorders unchanged lines; the rule does not say how case sorts, and "host packages" names no Python group.
|
||||
- **Sort `bin/`'s imports on their first binding, and say in `principles/technical-principles.md` → "Deterministic order" how case sorts and which groups Python has.** Today they sort by path, so a module move reorders unchanged lines; "host packages" names no Python group.
|
||||
- **Name CLI flags and exit codes among larv-review's external contracts, or record that they do not fire the architecture pass.** A prose pass found the product-owner row names the CLI and the architecture row does not.
|
||||
- **Show the judge's reply when `loop-claude` rejects its verdict.** Its stdout is discarded, so a judge that failed three times running leaves nothing to diagnose.
|
||||
- **Back up `loop-claude`'s transcript archive to a destination other than this repo's remote.**
|
||||
|
||||
Reference in New Issue
Block a user