Files
claude-config/CLAUDE.md
T

27 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. A rule names a project's files by their usual paths: todo.md, AGENTS.md, CHANGELOG.md and the files under docs/. Each is where the project's config puts it, which ~/.claude/bin/project-config prints and chunk-preflight's facts quote. Where the config names a Jira epic as the plan, the plan is the epic's open child issues. Read and edit a project record in the file ~/.claude/bin/project-record open <record> prints, and run project-record save <record> after each edit. Other words, such as chunk, are defined under "Vocabulary" at the end of this file.

  • Until the goals file has a ## Goals and an ## Audience section, writing them is the only work. Not even planning. In a README 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.
  • Keep a plan in 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.
  • Read and change the plan's items only with ~/.claude/bin/todo-item, which lists, shows, files, edits, moves and finishes them; todo-item --help says how. It reads a plan in Jira as it does a file. There it edits and moves only an issue the loop filed; of an issue a person filed it sets only the scores, with --comment telling the team why. Two open the file itself: whoever plans a release, to compare Scores across releases, which todo-item list doesn't print; and whoever edits ## Scoring or ## Renamed, or reshapes an old table.
  • 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.
  • Where someone cut a release that still holds items, those items are the next release's. Move them there as the chunk's first change and say so in its opening line; where todo-item cannot move an item, such as an issue a person filed in a Jira plan, ask the human in the chunk's summary to move it. Where the plan names no later release, ask the human which one they belong to.
  • 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.
  • A client project's CLAUDE.md and AGENTS.md in its repo belong to its team. Read both at the start of each chunk there. Propose each change that aligns them with this setup in a pull request of its own, never inside a chunk's; the one edit a chunk makes there is a decision's title in AGENTS.md. Until the team accepts a proposal, and after it declines or doesn't answer, follow the team's rule unless it breaks one of the project's goals. Record each such conflict as a decision in the decisions record, as rules/decisions.md asks: which rule you follow, why, and the open proposal's PR. Then nobody is asked twice.
  • Read the goals file'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; run todo-item only for what they leave out. Otherwise run ~/.claude/bin/todo-item list, which prints every item's row in the plan's order, without details. 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 the plan, 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 the plan 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 the goals file, 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 goals file, 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 goals file'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 principles folder the project's config sets (~/.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 from the plan, 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 item with its detail, and adds the bullet you pass with --changelog <bullet>; it refuses while a decision cites the item. A plan kept in Jira takes no bullet, since the issues' history is its changelog: finish there refuses --changelog. A chunk finishes its items as it merges, through chunk-pr merge --finish <ID>, which takes the same flags (larv-review §5).
  • 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 plan 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 goals file 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 the project's readability floor it is very important. The floor is 7.0, unless the project's config sets readability-floor.
  • 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. Where a project's config names another language, which ~/.claude/bin/project-config language prints, the prose that project's readers see is in that language instead: its docs, comments, commit messages, pull requests and tracker text. These stay English: chat, names in code, a reviewer's report, and what a tool reads, which is the fixed words of a title, such as Answer <pass> round <n>:, todo.md's table, and a record's headings, such as ## Unreleased. 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: prose.md in the project's review standards, which "Topic rules" below defines.

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.
  • Goals and audience: ~/.claude/rules/goals-and-audience.md.
  • Plan items, their scores and Exempt reasons: ~/.claude/rules/todo-items.md. Read it before you file, score, edit or move an item: a session that runs todo-item never opens todo.md itself, so the rule doesn't load.

The rules only reviewers apply, for quality, comments, READMEs and prose, are the project's review standards: the folder its config sets as standards, which ~/.claude/bin/project-config standards prints.

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 the project's config sets tooling-on-host = true or 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 plan 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 plan items and that rung is higher.
    3. A subagent that files or scores plan 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 the review 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.
  • Where the project's config names a commit-title, pull-request-title or branch template, fill it instead of following the formats in this section. {summary} is the one line that says what the change does, without a ticket ID, and {id} is the ID of the chunk's first item. A chunk without a plan item, such as a release review, works on a branch that doesn't fit the branch template, and its titles are the summary alone. ~/.claude/bin/project-config --help describes the templates, and chunk-preflight's facts quote them. A title a tool reads, such as Answer <pass> round <n>: …, Drop item <ID>: … or Release review of <release>, is the template's {summary}.
  • 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 plan item without a ticket: item-<ID>, in the worktree <checkout>-item-<ID> beside the checkout, as chunk-preflight makes them. Under a branch template, chunk-preflight names both by the template.
  • Where the project's config keeps a file in the config's folder, ~/.claude-projects/<key>/, such as the plan or a record, commit each change you make to that file in the folder's own git repo, on its only branch. Two chunks may commit there at once, so commit only that file: git commit -m <title> -- <file>, after git add <file> where it is new. Where git finds index.lock held, the other chunk is committing: try again. Title that commit as you would title the change in the checkout: where a commit in the checkout goes with it, give it the same title.
  • 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 plan 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 the premises or the judge's records.
  • gate — the merge gate: the checks a PR passes before it merges.
  • goals file — the file holding a project's ## Goals and ## Audience: the one its config names as goals-and-audience. Read it in the file ~/.claude/bin/project-record open goals-and-audience prints. It is README.md, unless a client's project keeps it in the config's folder, or in a Jira epic's description, which the loop only reads.
  • interrupt — loop-claude asking the human, on its terminal, for a decision that is theirs. They type a one-line answer there, or /talk to open the worker's session there with claude --resume. A release ready to cut opens that session at once. 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 premises: the project's AGENTS.md and docs/decisions.md, then the human's ~/.claude/CLAUDE.md and the .md files in ~/.claude/rules/, then those in the project's 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 — where the project keeps its items, as the plan setting of its config names it: a todo.md at a path, or a Jira epic.
  • premises — the goals and audience under ## Goals and ## Audience in the project's goals file, with code health ("Shared goal") first among the goals unless the goals file 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.
  • project record — one of five documents a project keeps beside its plan, each where its config names it: decisions, score-anchors, comprehension-history, reading-cost and changelog.
  • release — a semver version the human cuts, or in a client's project someone on its team.
  • 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.