Files
claude-config/CLAUDE.md
T
2026-11-12 23:21:31 +01:00

22 KiB
Raw Blame History

Global instructions

Working loop

How work proceeds in any repo, unless the repo's AGENTS.md says otherwise. The next release is the earliest one not yet cut. Other words, such as chunk, are defined under "Vocabulary" at the end of this file.

  • Until README.md has a ## Goals and an ## Audience section, writing them is the only work. Not even planning in todo.md. Both are public: an outside reader judges a project by where it is heading and who it is for. Goals or an audience written anywhere else, such as AGENTS.md or docs/, do not count; the one exception is code health, which "Shared goal" below states for every project.
  • Plan todo.md as one scored table, in the shape whose example ~/.claude/bin/rank_todo.py --help shows: every item names the release that ships it. Until todo.md has that shape, reshaping it is the only work, and the human approves it.
  • When the next release has no items and no work has landed towards it, plan it as this chunk. Move the highest-scoring items of later releases into it, and get the human's approval of that set before writing any code.
  • When the next release has no items left and work has landed towards it, its release review is the chunk (larv-review §3 → "Release review"). Once that has merged and the release holds no item, the release is finished: stop. Report what it holds and that it is ready to cut. Under /loop, this ends the loop. Until the human cuts it, only a security fix, or an item its release review filed, lands, into that release; never start a later release's items or plan a new one.
  • Open every chunk with one line: the last version cut, how many changes are unreleased (the entries under CHANGELOG.md → ## Unreleased, or else the commits since the last tag), and the release this chunk ships into. A repo that doesn't publish anything says so once.
  • Read the README's ## Goals and ## Audience before starting a chunk, unless your prompt quotes them. The chunk's items set its scope. The goals choose between ways to deliver those items, and never add to them.
  • Read the plan and the decisions only as far as the chunk needs. Where your prompt quotes chunk-preflight's facts, they hold the next item's L, E + I, tagline and detail, and each item that may join it with its L, E + I, S, tagline and detail; open todo.md only for what they leave out. Otherwise run grep -n '^## Details' todo.md, then read todo.md with the Read tool up to the line it prints, or whole when it prints none. Then read the details of only the items the chunk takes, with ~/.claude/bin/todo-item show <ID>, which prints an item's row and detail. AGENTS.md lists the project principles and the title of each decision no project principle covers. Read an entry in docs/decisions.md only where the project principle or the title leaves open what the chunk or the review needs.
  • Work one chunk at a time, and put every item that can share its review into it. Every review has a fixed cost, so a chunk takes the next plan item plus every other item for which three things hold: they name one release; they fire the same review passes (larv-review §3); and no item outside the chunk blocks one of them. The items need not share a purpose. An item whose risk R, in todo.md, is above 5 ships alone: it joins no chunk, and none joins it. The next plan item is the first that does not wait: an item waits while it is marked question, until the human answers, or while an item that blocks it is still in the plan. Tiny items, a few lines of change each, need not fire the same passes: bundle up to ten that name one release, and that no item outside the chunk blocks, into one chunk. Split a milestone into items in todo.md before starting it. Fix a finding in the chunk's own change within the chunk. File a finding about anything else in todo.md.
  • Ask, don't guess. Three choices are always the human's: a goal; a release, meaning the items planned into it and when it is cut; and a change to loop-claude's routing ladder, its rungs included. Any other rule that asks the human's approval reserves that choice too. Ask about a reserved choice. For any other choice, first check whether the goals already answer it. If they nearly do, propose a change to the goals and show how it answers this case: an answer settles one question, a goal settles every question like it. Otherwise take the option you would recommend, and record it with its reason: in the item's detail, or, where it governs later work, as the next sentence says. A recommendation you can give a reason for is not a guess. Ask only where you have no recommendation. Write every answer once, where it belongs, never only in chat: a goal in README.md, a working rule in AGENTS.md, a standing choice in a comment at the one place it governs, or in docs/decisions.md once made in more than one place. When an answer holds a goal and a choice, write the goal in the README, and record as a choice only what the goal leaves open.
  • Bench a syntax with the people who write it. Before a new or changed spelling of something users read or write ships — markdown, HTML, a config key, a CLI flag — a panel of fresh-context readers, seated as those users from the README's ## Audience, picks it.
  • Implement the simplest change that solves the item, and ship it with /larv-review. Whenever a test can check the change, write that test first and see it fail. Take its expected values from the item, never from the code. larv-review's reviewers hold the change to the technical principles, and a finding against one names it. Read a file in the project's principles folder (~/.claude/bin/project-config principles prints it) only when the item changes it, a finding or a record you write names it, or you decline a finding.
  • Remove a finished item's row and detail from todo.md, and revise any decision that cites it. If the repo publishes something others consume — a package, an image, an API — reword the item for them and move it to CHANGELOG.md under ## Unreleased. A changelog is for the public, never for the next agent. Otherwise delete it; git history is the record. ~/.claude/bin/todo-item finish <ID> removes the row and detail, and adds the bullet you pass with --changelog <bullet>; it refuses while a decision cites the item.
  • Releases are the human's. The version bump and the publishing credentials are theirs, whatever another rule says. Prepare everything else, so cutting a release is one decision.
  • Open each todo.md item or ticket with a bold one-sentence tagline, so the taglines alone say what a release holds. The tagline states the target state, checkable when done: an imperative verb plus what holds afterwards. A present-tense fact reads as the current state and doesn't say anything about what to do. Add "today X" only where the direction is otherwise ambiguous. GOOD: **Accept undefined in MetadataValue and drop such keys on output.** BANNED: MetadataValue accepts undefined; such keys are dropped on output.
  • File a security finding the moment it is found. A security finding — a leaked credential, secret or PII, an auth bypass, an injection — goes under the next release, marked security, naming the exposure and the path it reaches. ~/.claude/bin/rank_todo.py ranks it first in its release, after only the open questions, which wait for me. Never among additive or nice-to-have items, never only in a chunk's summary, and never as a question about where it belongs: file it, say you did, and I will unmark it if I disagree. Fixing it inside an unrelated change is a separate call — say whether it is in the blast radius.

Shared goal

Every project pursues the achieve goal below, ranked above every achieve goal its README states. A project whose code nobody will maintain voids it with one line under ## Goals, before the numbered goals: **Void:** code health, since <reason>. So does a project that opts out of the comprehension check, since the goal then has no signal. An item's Moves cell names it as in code health by 6, and rank_todo.py --help says how much it weighs.

Achieve: Code health: the code stays easy to read, change safely and debug, tomorrow and after seven years of development.

  • Signal: the comprehension panel's overall score rises, always. Under 7.0 it is very important.
  • Counter-signal: defects keep reappearing in functionality that already shipped, or reviewers raise blockers because the implementer misunderstood the current system.
  • Why: a score that rises while changes still misread the code measures the wrong thing.

Fewer items shipped per release is a price this goal accepts, not a counter-signal.

Prose

Everything written — chat, commit messages, comments, docs, code — is in English. Prose meets four priorities, in this order. When two pull against each other, the higher one wins.

  1. Easy to understand. A reader with little time gets it on one read: one idea per sentence, and each term explained before it is used.
  2. Most important first, judged by what the reader wants to know first.
  3. Default to delete. Keep a line, of prose or code, only if a reader needs it and nothing else already says it.
  4. Short. Cut whatever does not clearly help 1–3.

Write the thing, not an introduction to it. State what holds and stop; name a rejected alternative only where that stops a reader choosing it.

Write negations as people say them: after a verb, or after its preposition, write doesn't <verb> anything or anyone, never <verb> nothing or no one. BANNED: stops nothing, depends on no one, so answering in time costs nothing. GOOD: doesn't stop anything, doesn't depend on anyone, so answering in time doesn't cost anything.

Reviewers hold prose to the full rules, with examples: ~/.claude/skills/larv-review/standards/prose.md.

Public API specs

  • Text in public API specs (OpenAPI description/title fields, in a spec file or in code, and the generated api-docs) is read by external consumers. Never leak internal references: no ticket IDs, internal URLs, repo/system code-names, "see ticket X". Describe behaviour in consumer terms. GOOD: Deprecated alias for paymentAccountId. BANNED: …will be removed (ABC-123).
  • Internal code comments, by contrast, may cite a ticket for a footgun or constraint.

Topic rules

Claude Code loads a rule file when a session writes a file its paths: frontmatter matches, or reads one with the Read tool or head -n, never sed. After a write, it loads only once the write is done. Read a rule file before you create a file it covers.

  • The decision log: ~/.claude/rules/decisions.md.
  • README goals and audience: ~/.claude/rules/goals-and-audience.md.
  • todo.md items, their scores and Exempt reasons: ~/.claude/rules/todo-items.md.

The rules only reviewers apply, for quality, comments, READMEs and prose, live in ~/.claude/skills/larv-review/standards/.

Working with the codebase

  • 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 unless a decision puts them there. Example: docker compose run --rm app <tool> ….

  • Tear down test containers after a run.

  • Give every container you start a memory limit and a swap limit, as large as its work needs: --memory 4g --memory-swap 4g on docker run, or mem_limit and memswap_limit in a compose file, scripts included. rule-hook checks only the docker run and docker create in your Bash commands.

  • A heavy command loads the machine for minutes: a full gate, mutation tests, an e2e run, a docker build. Run each one under ~/.claude/bin/run-heavy, as in ~/.claude/bin/run-heavy ./ci.sh. run-heavy waits for one of the heavy slots that every session on the machine shares. It also caps each container the command makes at the slot's share of memory, where the container sets no limits; give a container that needs more its own. Run the command in the background, since run-heavy's wait can outlast the Bash tool's timeout; ~/.claude/bin/wait-for <file> [<pattern>] waits for a line in a log the command writes.

  • Delegate a task to a subagent only when you need just its conclusion: a search or read across many files, or work independent enough to run in parallel. Keep edits, and whatever you must check line by line, in your own thread: you would read a delegated diff again to check it. Score the task's L as for a todo.md item; a task that changes no file, such as a search, is L 1. <model> below is the project's model id, such as claude-opus-5-5: the one loop-claude's prompt names as the project's, or else your own. Launch the subagent with the model and effort of the first case that fits:

    1. A reviewer, a comprehension seat or the security pass: those loop-claude's prompt gives it. Given none, pass no model or effort, so it runs on your model.
    2. An escalated task, below: the rung loop-claude's prompt names for escalation, or case 3's rung where the subagent files or scores todo.md items and that rung is higher.
    3. A subagent that files or scores todo.md items: what ~/.claude/bin/subagent-rung --plan <model> <L> prints, which is never below the project's rung.
    4. Any other: what ~/.claude/bin/subagent-rung <model> <L> prints.
  • Escalate a task that proves too hard for your rung. Four escalation triggers say so:

    1. A re-score of the item's L, made on the project's rung or above, picks a rung above yours.
    2. The same failing test or finding survives two fix attempts.
    3. A pass reports a 🔴 in round 2.
    4. A review rules the work below standard: systems-architect's BLOCK, a finding against larv-review's standards/quality.md, or a vote record-ruling counts as worse, in the report that stands after any relaunch one rung up (larv-review §3 → "Rung up"). It doesn't fire where the fix changes only prose (larv-review §3 says what is prose): fix that on your own rung.

    When one fires, hand the hard part, edits included, to a subagent on the rung loop-claude's prompt names, one above yours. Open the subagent's prompt with the marker loop-claude's prompt gives, then the trigger's evidence. Each later subagent on that task runs on that rung or higher, and each further escalation trigger moves the task one rung higher, up to the highest rung loop-claude's prompt names. Ask the human before going higher. Where loop-claude's prompt names no escalation, as on the ladder's top rung or off it, keep the task in your own thread.

  • Give a subagent only the access its job needs, and state the limits in its prompt. One that only reads, such as a prose review, gets no shell and no edits. A reviewer under ~/.claude/agents/ writes only its report, under ~/.local/state/larv-review/, and rule-hook refuses it every other Write, every Edit and every MultiEdit. One that probes a build tags the image as throwaway and removes it afterwards, writes only to a folder it makes under the chunk's review folder (~/.claude/bin/larv-review review-folder prints it), and removes no image or file it did not create.

  • Check README.md first for build, test, install, and codegen commands, and fix one that misbehaves in the same change. Refresh README.md whenever you change what it describes, keeping it true, not longer.

  • Where ~/.claude/bin/rule-hook does not check it, such as an image named in test code, a Kubernetes manifest or a docker run line, pin a container image to its full patch version and a GitHub Action to a semver tag.

Naming files & folders

  • Name by what's 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/.

Git, commits, and PRs

  • Mark no commit, PR, issue comment or file as the work of Claude, Anthropic or an agent.
  • Commit message and PR title: one line, prefixed with the ticket ID when the work has one. Example: ABC-123 - Regression tests for GET /v4/clients. Never include the repo/project name (like "twu-4") — we're already in that context.
  • When the work has a ticket, read it before starting: verify the change matches it and pull useful context from it.
  • PR summary: short and concise. No test plan (it lives in the ticket), no link to the ticket (it's in the title).
  • Branch for a ticket: exactly the ticket ID, nothing more. ABC-123, never ABC-123-some-description.
  • Branch for a todo.md item without a ticket: item-<ID>, in the worktree <checkout>-item-<ID> beside the checkout, as chunk-preflight makes them.
  • Use gh on GitHub remotes and tea on Gitea remotes (e.g. gitea.larvit.se) — same command shape: tea pr list|create, tea issue, tea release, tea api. Everything in this section applies to both.
  • On GitHub and Gitea, open a chunk's pull request as a draft, mark it ready and merge it with ~/.claude/bin/chunk-pr, which picks gh or tea from the remote; chunk-pr --help says how. Once it has merged, run chunk-pr clean in the chunk's worktree: it removes the worktree and the branch and fast-forwards the main checkout.

Handoffs

  • Write no handoff document. The repo holds everything the next session needs: the plan, the decisions, and every script, sketch or measurement those depend on. A file outside the repo is unreachable from another machine's checkout.
  • Keep four kinds of fact out of the repo, in a memory file: a secret's value; where this machine keeps its copy of one; a quirk of the agent's own environment that a human contributor does not share; data the repo may not publish, unlicensed or holding PII.

Web research

  • A list or threshold a consumer relies on is sourced. Deny-lists, defaults, limits: follow a published standard or a widely deployed tool, and cite it in the decision recording the choice; where none exists, ask. Never assemble one from names that seem plausible.
  • When a page renders client-side and comes back empty/blocked, use the Playwright renderer at ~/code/playwright-for-agents/ — ./pw <url> [options] (see its README). Don't use claude-in-chrome for this.

Compact instructions

Claude Code reads this section by its heading when it compacts a conversation. Keep in the summary:

  • what remains before the chunk is finished;
  • the task loop-claude gave, and each todo.md item the chunk takes with its L and E + I;
  • the worktree, branch and PR;
  • the rung loop-claude named for each review launch, rerun and escalated subagent;
  • each review pass's rounds so far, each open 🔴 and 🟡, and how the answered ones were answered;
  • every question the human answered, with the answer;
  • each escalation trigger that fired;
  • for a reviewer or comprehension seat, every finding and place it has drafted.

Vocabulary

  • chunk — the unit of work, shipped as one PR; "Working loop" says what it holds.
  • cycle — in loop-claude, worker runs and the judge's verdict on each, until the chunk closes or is left for the next cycle. In between, the human answers any interrupt, or the worker resumes with an answer the judge quoted from README.md or the judge's records.
  • gate — the merge gate: the checks a PR passes before it merges.
  • interrupt — loop-claude asking the human, on its terminal and in loop-inbox, for a decision that is theirs. They type a one-line answer in either, or /talk to open the worker's session with claude --resume where they typed it. A release ready to cut opens that session at once, on loop-claude's terminal. A routing call opens claude on that terminal too, in ~/code/claude-config, the checkout where this setup is developed.
  • judge — the headless claude that reads a worker's transcript each cycle and decides whether to interrupt and whether the chunk is finished.
  • judge's records — the files the judge reads beside the README's premises: the project's AGENTS.md and docs/decisions.md, then the human's ~/.claude/CLAUDE.md and the .md files in ~/.claude/rules/ and ~/.claude/skills/larv-review/standards/.
  • paired ruling — the seats vote whether the project reads better, the same or worse at the branch's head than at the base, the commit larv-review ruling-base prints; larv-review --help says how the votes make the ruling.
  • pass — one kind of review a chunk may take, run in rounds by its reviewers until clean; larv-review §3 lists them.
  • place — the smallest addressable unit, such as a function or a section heading, that a seat names with its path:line when it judges how hard the project is to read there.
  • plan — todo.md.
  • premises — the goals and audience under ## Goals and ## Audience in the project's README.md, with code health ("Shared goal") first among the goals unless the README voids it.
  • project's rung — the cheapest rung on loop-claude's routing ladder of the project's model, which is the model loop-claude's prompt names as the project's, or else your own.
  • release — a semver version the human cuts.
  • release review — a release's last chunk: the architecture and principles passes over the whole project, before the release is ready to cut; larv-review §3 → "Release review".
  • reviewer — a reporter of findings: an agent under ~/.claude/agents/, /security-review or a forge's auto-reviewer.
  • round cap — the rounds one pass may take per chunk; larv-review §3 → "Round cap".
  • scoring run — each seat scores the project from 1 to 10, overall and on each dimension. larv-review §3 → "Comprehension check" says which seats score and when one is due.
  • seat — one simulated reader of the comprehension panel, launched per ~/.claude/skills/comprehension-panel/SKILL.md.
  • session — a Claude Code session: one id, what claude --resume continues.
  • trigger — the condition under which a review pass runs on a change it has not seen; larv-review §3 lists them.
  • worker — the headless claude that runs the task in a cycle, in the chunk's session.