11 KiB
Phase 0 — split project CLAUDE.md into .claude/rules/ (design)
Date: 2026-10-26 · flow: /ship-feature · branch: feature/claude-md-split
Contract: .claude/tasks/contracts/2026-10-26-claude-md-split-0042.md
Parent: BDR-125 (context mod queue), TODO.md "Phase 0, no mod".
Intent
The project CLAUDE.md of this repo (5,285 chars) loads in every session of
this repo; four of its five sections only matter when a matching file is
being read. Move those four into project-scope path rules
(.claude/rules/<name>.md with paths: frontmatter), prove they load, and
give the other projects the same lever through a /onboard split mode and
generators that emit path rules from day one. No mod, subtract-only.
Decided with the user (2026-10-26): this run covers this repo, the mode and
the generators; the per-repo pass over the six other repos runs after the
merge through the shipped /onboard split, one chore/claude-md-split
branch per repo, user approval per repo, never an automatic merge. The
InstructionsLoaded proof hook is permanent. The transient-artifacts rule
carries a # static-check: skip marker. The gitignore socle gains
!.claude/rules/. Generator skeleton set: docker, testing, ci.
1. This repo's rules
| Rule file | paths: |
Source section (CLAUDE.md, verbatim) |
|---|---|---|
.claude/rules/rules-maintenance.md |
rules/**, CLAUDE.global.md |
## rules/ maintenance |
.claude/rules/graphify-vendored.md |
skills/graphify/**, install-plugins.sh, .graphify_version |
## Machine-owned: the vendored graphify skill |
.claude/rules/mods.md |
mods/**, skills/model-router/**, lib/tests/mods.test.sh |
## mods/ — function-hooks plugins (Claude Code mods) |
.claude/rules/transient-artifacts.md |
docs/superpowers/**, .audit/** (+ # static-check: skip) |
## Transient planning artifacts |
Frontmatter shape = rules/a11y.md: paths: ["glob", ...] on one line.
The skip marker is a YAML comment line inside the frontmatter, invisible to
the engine. Body text moves verbatim; the title line becomes # <section title>. CLAUDE.md keeps its header, ## Health Stack, and a two-line
pointer: path-scoped rules live in .claude/rules/ and load on Read of a
matching file; the four names listed.
.gitignore: !.claude/rules/ right after .claude/* (line 122).
templates/gitignore/standard.gitignore: same line after .claude/*
(order matters: a negation must follow the ignore it carves; reconcile
appends missing lines at the end, which is after any existing .claude/*).
lib/gitflow-test.sh: one chk "socle: !.claude/rules/" beside the
!.claude/deploy/ assertion.
2. Static check and proof hook
lib/project-rules.sh (our code, strict limits, shellcheck):
check [dir](default.claude/rules): for each*.md: frontmatter delimited by---present; apaths:line whose value is a JSON-style array of double-quoted globs; each glob matches ≥1 path in the working tree (shopt -s globstar dotglob nullglob, so the symlinkedskills/model-router/**and the gitignoredskills/graphify/SKILL.mdcount, and a typo matches nothing). A frontmatter line# static-check: skipexempts that file's globs (printed as SKIP). Exit 0 andproject-rules: N rule(s) okon success; exit 2 and one<file>: <reason>line per failure. An empty or absent dir is exit 0 with0 rule(s)(a project without rules is not an error).sections <CLAUDE.md>: prints<chars>\t<line>\t## <heading>per top-level section, for the split-mode classification table.extract <CLAUDE.md> "<heading>" <out.md> <globs-json>: writes<out.md>with the frontmatter and the section body (title demoted to#), removes the section from CLAUDE.md. Deterministic, idempotent failure (heading absent → exit 2, nothing written). Used by the onboarder in MODE: split and by the per-repo pass.
lib/tests/project-rules.test.sh (picked up by make test via the
lib/tests/*.test.sh glob): fixtures in mktemp -d: a good rule passes;
an unmatched glob fails with the culprit; a missing frontmatter fails; the
skip marker passes an unmatched glob; sections lists sizes; extract
round-trips (rule written, section gone, second call exit 2); then the real
check on this repo's .claude/rules (exit 0). PASS/FAIL tally like
doctrine-citers.test.sh.
hooks/instructions-loaded.sh: reads the hook JSON on stdin, appends one
jq -c line {ts, cwd, file_path, memory_type, load_reason, trigger_file_path} to ~/.claude/logs/instructions-loaded.jsonl
(mkdir -p), always exits 0, never prints to stdout (a stdout line would
reach the model). Registered in settings.json under "InstructionsLoaded"
beside the other classic hooks. No hooks suite exists: the hook test lives
in lib/tests/project-rules.test.sh (fixture JSON on stdin, HOME pointed
at a temp dir, the appended line asserted, stdout asserted empty).
Proof for this repo (recorded in the journal): claude -p "/context" on
develop BEFORE any edit (baseline, same measure as 2026-10-23), the same on
the branch after the split, one fresh interactive session that Reads one
matching file per rule, then grep path_glob_match ~/.claude/logs/instructions-loaded.jsonl | tail -4 pasted.
3. /onboard split
skills/onboard/SKILL.md: right after the MODEL GATE, a MODE DISPATCH
paragraph: $ARGUMENTS starting with the token split → § SPLIT MODE;
anything else → the existing flow unchanged. The description gains the
trigger ("split CLAUDE.md", "découpe le CLAUDE.md"), the argument-hint gains
split, RULES line "NO skipping STEP 0, 1, 2" gains "(split mode runs its
own steps, § SPLIT MODE)". Routing rows, test locks (model-routing,
effort-routing, loops-heavy, plan-challenger, security-auditor) and
routing.json:67 keep their anchors.
§ SPLIT MODE (steps):
- Precondition:
CLAUDE.mdat the project root, else print "nothing to split, run /onboard" and stop.git status --porcelainclean on the CLAUDE.md path, else stop (an in-flight edit would be lost). - Baseline:
claude -p "/context"at the root; refused → the user runs! claude -p "/context"; the always-on total is noted. bash ~/.claude/lib/project-rules.sh sections CLAUDE.md; classify each##section: always-on (overview, stack, build/test/lint commands, conventions, workflow expectations, exceptions) or path-scoped (one module, one folder, Docker, migrations, CI, a tool's gotchas); propose a file name and globs fromgit ls-filesfor each path-scoped one, and verify every proposed glob matches ≥1 tracked path before showing it.- Gate (prose table, per project): section · chars · keep / move →
<name>.md· globs. The user edits or approves; "keep everything" is a valid answer that ends the mode. bash ~/.claude/lib/gitflow.sh start chore claude-md-split(a project without gitflow: a plain branch, said so).- Dispatch
Agent(subagent_type="onboarder")withMODE: split, the project root, and the approved table verbatim (LRN-126: every field crosses the prompt). It runsextractper row, writes the pointer lines into CLAUDE.md, adds!.claude/rules/after.claude/*when that line is present and the negation absent, runscheck, commitschore(claude-md): split N sections into .claude/rules/, reports. - After:
claude -p "/context"again, the delta and the rule list go to that project's.claude/memory/journal.md; the InstructionsLoaded proof is the user's next session there (one Read per rule, grep the log). Neverfinish: merge on the user's signal.
Skill edit through /writing-skills: RED first (a sonnet subagent given the CURRENT skill and a scratch repo holding a copy of this repo's pre-split CLAUDE.md, asked to "/onboard split": it has no mode and runs or asks for the full onboard), then the edit, then GREEN on the same scratch (the subagent produces the classification table and stops at the gate).
agents/onboarder.md: a MODE: header: absent → today's PHASES 1-5
(generate config); MODE: split → the split executor above (PHASES
S1-S4: extract rows, pointer lines, gitignore negation, check + commit).
Stays sonnet, effort medium (BDR-077).
4. Generators born split
templates/project-rules/ skeletons, each with paths: and 3-6 lines of
section stubs (HTML comments like the CLAUDE.md template):
docker.md:["Dockerfile*", "docker-compose*", "compose*.y*ml", ".dockerignore"]testing.md:["tests/**", "test/**", "**/*.test.*", "**/*.spec.*", "**/conftest.py"]ci.md:[".github/workflows/**", ".gitlab-ci.yml", ".circleci/**"]
onboarder (default mode) PHASE 1b and scaffolder PHASE 1b: for each
skeleton, emit .claude/rules/<name>.md when ≥1 of its globs matches a
path in the project tree (onboarder: the real tree; scaffolder: the tree it
just scaffolded, so a Docker-relevant project gets docker.md), filled from
the BRIEF where known, else the template stubs. Then run project-rules.sh check and report the emitted list. The onboarder's PHASE 4 gitignore check
also appends !.claude/rules/ after an existing .claude/* line
(the socle covers gitflow-init projects; this covers the rest). The
scaffolder's .gitignore is reconciled by STEP 5f gitflow init before
the root commit, so the socle line lands first (LRN-066, BLK-010).
templates/project-CLAUDE.md keeps every section (commands stay always-on);
its header comment gains one line naming .claude/rules/.
5. Cleanup and citers
rules/README.md:9→ "see.claude/rules/rules-maintenance.mdin the claude-config repo".doctor.sh:76comment: "the project CLAUDE.md" (drop "29-line").ARCHITECTURE.mdtree gains.claude/rules/(doc pipeline, STEP 8).install-plugins.shGUARDED_CONFIGS unchanged:graphify claude installstill rewrites CLAUDE.md and the trap still reverts it..claude/tasks/TODO.md: phase 0 item updated (done parts, per-repo pass queued as its own item with the repo order).- Registries append-only: BDR-065 and LRN-154 keep their old location text.
- Manual step (user):
claude mcp remove -s user higgsfield; journal line.
6. Testing and proof
make testgreen (new suite + gitflow-test socle assertion + hook test).shellcheck *.sh hooks/*.sh lib/*.shclean.project-rules.sh checkexit 0 on this repo./contextbefore/after at the repo root; the fourpath_glob_matchlog lines from one real session.- RED → GREEN pressure test transcript summary for
/onboard split.
7. Out of scope, risks kept
- The per-repo pass (six repos) and whether path rules load inside sub-agents: measured on faunosteo first, during that pass.
- A
paths:rule loads on Read, not on Write of a new file: generator rules load once the scaffolded file is edited (Edit needs a Read). - The pre-commit
.claude/**exemption lets a rules-only commit land on develop; split mode always branches first.