docs: split CLAUDE.md per-HAL — cross-cutting root, per-generation files load on-demand#312
Merged
Merged
Conversation
…les load on-demand
Root CLAUDE.md (40.8k chars) tripped the Claude Code 40k warning and grows
with nearly every feature PR. Cross-cutting operational knowledge stays in
the root (~30k); per-generation register/descriptor/mechanism facts move to
src/{jaguar1,jaguar2,jaguar3,kestrel}/CLAUDE.md, which Claude Code loads
on-demand when reading files in that subtree (@imports load eagerly, so a
nested split is the only form that reduces startup context).
No fact dropped: hex-register + backticked-token audit of old vs new corpus
is clean (deliberate drops: one issue-# tag, the SipHash formula that lives
in docs/fhss.md). Cross-references repointed (CMakeLists.txt,
docs/8852c-quirks.md, RtlJaguar3Device.h); the stale rail-sag CLAUDE.md tag
in tests/bench_onair.py dropped.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
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.
Root CLAUDE.md hit the Claude Code 40k-char warning (40,779 chars) and grows with nearly every feature PR. This splits it along the loading semantics the harness actually implements: nested subdirectory CLAUDE.md files load on-demand (when files in that subtree are read), while
@importsload eagerly at startup — so a nested split is the only form that reduces per-session context.Layout
CLAUDE.mdsrc/kestrel/CLAUDE.mdsrc/jaguar1/CLAUDE.mdsrc/jaguar3/CLAUDE.mdsrc/jaguar2/CLAUDE.mdThe root keeps cross-cutting knowledge (capability map + naming traps, build, hardware testing, logging, env knobs, hopping/chanmig, architecture, gotchas, TX path) and states the convention up top: new per-generation facts go in the subtree file, cross-cutting facts in the root. Per-generation register-level facts (Kestrel
_V1banks/descriptors/cold-boot, the RF18 value-edge trap,0x8ac/0x9b0narrowband encodings, the coex runtime thread, per-packet TX-power mechanisms, HAL file maps) move to the subtree files.Zero information loss
Audited: every hex register and backticked token from the old file is present in the new corpus. The only deliberate drops are one issue-# tag and the SipHash permutation formula (which lives in
docs/fhss.md).Cross-references
CMakeLists.txt,docs/8852c-quirks.mdandsrc/jaguar3/RtlJaguar3Device.hrepointed at the subtree files; the stale "(CLAUDE.md defence #1)" tag intests/bench_onair.pydropped (rail-sag guidance no longer lives there). Build green — the only non-doc changes are comments.🤖 Generated with Claude Code