Move the rules that reach past code back to CLAUDE.md
This commit is contained in:
@@ -96,10 +96,16 @@ Prose describing the code as it stands — a comment, a README, an `AGENTS.md`,
|
||||
- Always start a new git worktree when doing something in a codebase, and clean it up when done. Unless told otherwise, branch it off a freshly-updated default branch (`git fetch origin`, then base on `origin/main`), not whatever happens to be checked out.
|
||||
- Keep the project's main checkout (e.g. `~/code/log`, never a worktree) current: when it is behind `origin` — a merge landed, or a fetch shows it — run `git pull --ff-only` there instead of reporting the lag, never with `--autostash`: a dirty checkout is a finding to report, not to carry along.
|
||||
- Run a project's language runtime, package manager, and task runner through its container/tooling setup, never directly on the host. Example: `docker compose run --rm app <tool> …`.
|
||||
- Tear down test containers after a run.
|
||||
- Check `README.md` first for build, test, install, and codegen commands; one that misbehaves is fixed per "A false claim is a bug". Refresh `README.md` whenever you change what it describes ("Refresh `README.md` to match").
|
||||
- Sort wherever order carries no meaning (`~/.claude/principles/technical-principles.md`) — attributes, array and object keys, enum members, imports, table rows, and line-based file lists such as `.gitignore`/`.dockerignore`. Exception: `id` goes first.
|
||||
- Pin GitHub Actions to semver tags (`@v3`, `@v3.1.2`), not commit SHAs — including third-party actions. SHA-pin only in special pipelines that test our own specific builds.
|
||||
- Pin container images to the **full patch version** everywhere they're referenced — Dockerfile `FROM`, compose `image:`, base images in test fixtures: `node:24.18.1-bookworm-slim`, `mysql:8.4.7`, `alpine:3.23.3`. Never a floating major or minor (`node:24`, `node:24.18`, `:latest`, `:lts`): the same commit then builds a different image on different days, so a green pipeline says nothing about the next run, a base change lands with no diff to review, and any size or performance figure measured against it silently goes stale. Let a bot (Renovate/Dependabot) raise the bumps as reviewable PRs — that is where a base change belongs. (Actions are the exception above: a semver tag is fine there, because the action's own release is the reviewable unit.)
|
||||
|
||||
## Naming files & folders
|
||||
- Name by what's inside, not by catch-all. BANNED: `scripts`, `utils`, `helpers`, `misc`, `common`, `lib`, `stuff`. Use explicit names: `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/`.
|
||||
|
||||
## Technical principles
|
||||
|
||||
The rules every project follows, compose-not-entangle first: `~/.claude/principles/technical-principles.md`. Read it before writing, designing or reviewing code.
|
||||
|
||||
@@ -33,7 +33,6 @@
|
||||
- Write tests first for the behaviour we want, then implement until they pass.
|
||||
- Changing tests and changing other code are two separate processes — be very careful about doing both at once.
|
||||
- Use properly randomised UUID v7s — never `aaaa-0000`-style placeholders.
|
||||
- Tear down test containers after a run.
|
||||
* Test coverage should not decline.
|
||||
* Idempotent data writing.
|
||||
- Typical example: `PUT /resource/{id}` instead of `POST /resource` + Idempotent-Id header.
|
||||
@@ -47,10 +46,7 @@
|
||||
- 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.
|
||||
* 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/`.
|
||||
- Prefer explicit, descriptive names over generic ones (`invoiceRowsService`, not `service`).
|
||||
* 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.
|
||||
@@ -58,7 +54,6 @@
|
||||
- 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.
|
||||
- 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.
|
||||
* Keep It Simple, Stupid (KISS).
|
||||
- Keep solutions simple and easy to understand, so it is dead easy to grasp what they do.
|
||||
|
||||
Reference in New Issue
Block a user