CLAUDE.md is a router, not a manual: 22.9 KB to 8.3 KB - #725
Open
lmoresi wants to merge 1 commit into
Open
Conversation
lmoresi
force-pushed
the
docs/audit-2026-09
branch
from
September 11, 2026 18:13
fac3b9c to
fb4ccb3
Compare
Every session loads this file verbatim before it loads anything else, and it had grown to more than twice the size of the Style Charter it defers to. That is the wrong way round: the file whose job is to point at the governing documents was the bulkiest thing in the context, and the 2026-09 audit found it competing for attention with the rules it exists to route to. Most of the bulk was duplication of documents that already govern their topic. `docs/developer/guides/branching-strategy.md` already carries the branch roles, the API-versus-implementation discipline, the worktree lifecycle, the branch policy and a section addressed to AI assistants; CLAUDE.md restated 4.3 KB of it. The on-demand documentation list restated the authority map in `docs/developer/index.md`. Both are now one pointer each. The build constraints move to `guides/development-setup.md`, which was a stub that still told developers to run `pixi run underworld-build` — a command the tooling replaced with `./uw build`. It now carries the rebuild rule, the editable-install prohibition and its recovery recipe, the PETSc non-relocatability warning, and how worktree environments work. CLAUDE.md keeps the four hard rules as one line each. Nothing normative was dropped. What remains is what a session needs before it knows where to look: the Charter mandate, session bootstrap and the external planning protocol, the hard constraints, where files go, the rulings that are non-obvious and easy to get wrong (rotated free-slip over Nitsche, the data access contract, unwrap-before-atoms, the ambiguous `model`), the test markers, and the pointer to the authority map. Every path this file names was checked to resolve. Underworld development team with AI support from Claude Code
lmoresi
force-pushed
the
docs/claude-md-trim
branch
from
September 11, 2026 18:13
6db41b3 to
2118b12
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stacked on #723 — it references
scripts/check_test_coverage.py, which landsthere. Retarget to
developmentonce #723 merges.Why
Every session loads
CLAUDE.mdverbatim before it loads anything else. It hadgrown to 22.9 KB — more than twice the Style Charter it defers to. That is the
wrong way round: the file whose job is to point at the governing documents had
become the bulkiest thing in the context, competing for attention with the rules
it exists to route to.
This came out of the 2026-09 audit, which started from the observation that
adversarial review of the advection/particle PRs was turning up Charter
violations that nobody had been reminded of.
What was actually in there
Mostly duplication of documents that already govern their topic.
guides/branching-strategy.mdalready carries the branch roles, theAPI-versus-implementation discipline, the worktree lifecycle, the branch policy,
and a section addressed to AI assistants. CLAUDE.md restated 4.3 KB of it. The
"On-Demand Documentation References" section restated the authority map in
docs/developer/index.md. Both are now one pointer each.The build constraints move to
guides/development-setup.md— which was a stubthat still told developers to run
pixi run underworld-build, a command thetooling replaced with
./uw build. It now carries the rebuild rule, theeditable-install prohibition with its recovery recipe, the PETSc
non-relocatability warning, and how worktree environments work. CLAUDE.md keeps
those four as one line each, because they are the ones that cost an hour when
broken.
What stayed
What a session needs before it knows where to look: the Charter mandate,
session bootstrap and the external planning protocol, the hard constraints,
where files go, the rulings that are non-obvious and easy to get wrong (rotated
free-slip over Nitsche, the data-access contract, unwrap-before-atoms, the
ambiguous
model), solver-stability, the test markers, and the pointer to theauthority map.
Nothing normative was dropped — checked rule by rule against the previous
version — and every path the file names was verified to resolve.
Underworld development team with AI support from Claude Code