Answer stability round 1: 0 🔴, 6 🟡 (0 misread); read the team's files each chunk, say what holds while a proposal is open and make the entry point's place the ecosystem's; the prose round's 8 🟡 are fixed here too
CI / tests (pull_request) Successful in 2m17s
CI / tests (pull_request) Successful in 2m17s
This commit was merged in pull request #531.
This commit is contained in:
+2
-2
@@ -2,8 +2,8 @@
|
||||
|
||||
## Unreleased
|
||||
|
||||
- The technical principles ask for code in files and folders before `// --- name ---` banner comments, and for an entry point a newcomer finds at once, with only the README and the files a tool reads from the root beside it.
|
||||
- In a client repo, the loop reads its team's own `CLAUDE.md` and `AGENTS.md`, proposes each change that aligns them with this setup in a pull request of its own, and records each conflict that stays as a decision in the project's decision record, following the team's rule unless that breaks a project goal.
|
||||
- The technical principles ask for code in files and folders before `// --- name ---` banner comments. They also ask for an entry point a newcomer finds at once: the root holds it, the README and the files a tool reads only from there.
|
||||
- In a client project, the loop reads the team's own `CLAUDE.md` and `AGENTS.md` and proposes each change that aligns them with this setup in a pull request of its own. Where the team declines or doesn't answer, the loop follows the team's rule unless it breaks a project goal, and records the conflict as a decision in the `decisions` record.
|
||||
- The new `project-record open <record>` prints the file in which an agent reads and edits one of a project's five records (`decisions`, `score-anchors`, `comprehension-history`, `reading-cost` and `changelog`), and `project-record save <record>` stores the edit. Every tool now reads and writes a record the same one way, so that a later release can keep a record outside files. No config needs a change.
|
||||
- `loop-inbox` is gone. loop-claude now asks its questions only on its own terminal. A line typed there answers a question, and `/talk` opens the worker's session. The Mattermost DM still tells you a loop waits. To upgrade, quit any `loop-inbox` still open and remove your `~/.local/bin/loop-inbox` link. Once every loop started before the upgrade has reloaded or ended, remove the folder `~/.local/state/loop-claude/`, which nothing reads any more.
|
||||
- rule-hook refuses a Read or a Grep of `~/.claude/.env` or of the `env-file` any project's config names, and a Bash command that names either or searches a folder holding either with `ag`, `grep -r` or `rg`, unless the tool skips the file as hidden or ignored, so that a worker doesn't put a credential in its transcript in passing. A command that hides the path, such as behind a glob or a variable, still goes through.
|
||||
|
||||
@@ -9,6 +9,7 @@ How work proceeds in any repo, unless the repo's `AGENTS.md` says otherwise. The
|
||||
- **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.
|
||||
- **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; 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`.
|
||||
@@ -80,7 +81,6 @@ The rules only reviewers apply, for quality, comments, READMEs and prose, live i
|
||||
|
||||
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.
|
||||
- A client repo's own `CLAUDE.md` and `AGENTS.md` belong to its team. Read both before the first chunk. Propose each change that aligns them with this setup to the team as a pull request of its own, never inside a chunk's. A conflict the team leaves stands: follow the team's rule, unless that breaks one of the project's goals, and record which rule you follow and why as a decision in the project's decision record, so nobody is asked twice.
|
||||
- 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.
|
||||
|
||||
|
||||
@@ -79,11 +79,11 @@
|
||||
- Things a reader finds by name may run far past seven: 100 files named by locale, the cases of an enum, a reference list. A predictable name and a sorted order serve them better than a group would.
|
||||
- Each added level makes a reader open one more folder, file or function to find a thing, so a split must save more than it costs. Keep eight, nine or ten things in one level when splitting them would add more names, files or jumps than it removes. Say why where the level is declared: a comment, the folder's README.
|
||||
- Group by what a reader would name: a feature, a step, what changes together. BANNED: `misc/`, `part2()` or a parameter object that exists only to bring a count down. GOOD: `invoices/`, `payments/`, `reports/`, each holding what changes together; `locales/` holding `de.json` to `zh.json`, flat.
|
||||
- Group code into files, and files into folders. A banner comment (`// --- name ---`) that groups a file's sections is the last resort, kept only where the language or the build cannot split the file, and the file says which limit holds it.
|
||||
- Group code into files, and files into folders. A banner comment (`// --- name ---`) that groups a file's sections is the last resort, kept only where the language or the build cannot split the file, and the file says why it can't be split.
|
||||
- Crossing a limit asks for one of two answers, never a split at any cost: group the things, or record why they stay. Keep a limit only while the comprehension panel's readers (`~/.claude/skills/comprehension-panel/`) find the code it flags hard.
|
||||
* Make the entry point the first thing a newcomer finds.
|
||||
- The root holds the entry point, the README and the files a tool reads only from there, such as the manifest, the lockfile and the licence. Source, tests and tooling live in folders named by what they hold.
|
||||
- The entry point carries the name its ecosystem expects, such as `index.ts` in an npm package, with no other source file beside it.
|
||||
- The root holds the README and the files a tool reads only from there, such as the manifest, the lockfile and the licence, and the entry point where the ecosystem puts it there. Source, tests and tooling live in folders named by what they hold. A repo of several tools applies this to each tool's folder.
|
||||
- The entry point carries the name and the place its ecosystem expects, such as `index.js` at the root of an npm package or `src/main.rs` in a Cargo crate, with no other source file beside it.
|
||||
* Keep It Simple, Stupid (KISS): keep solutions simple, so a reader new to the project understands each part on one read.
|
||||
* Don't Repeat Yourself (DRY) is a guide, not an absolute rule. It aims at one authoritative home per piece of knowledge, one obvious way per need. Before applying it, ask whether the code would be easier to understand, easier to reason about, or easier to maintain if DRY were broken; if so, break it, so long as the spellings cannot disagree (below). A surface people write — a template, data, an API — may accept a second spelling where that makes it easier to use.
|
||||
- A value, rule, definition or concept lives in one place, and everywhere else derives it from there or points at it. A copy that can drift is a second spelling: derive it from its owner, or, for config a human writes, reject it where it is read and name the owner.
|
||||
|
||||
Reference in New Issue
Block a user