Uh oh!
There was an error while loading. Please reload this page.
docs: trim CLAUDE.md to what the codebase cannot tell a session itself - #10
Merged
Conversation
The root file had grown to 53.7k chars — past the point where Claude Code warns about a memory file — and every session paid for all of it. Three changes, none of them to the rules themselves: Cut four blocks a session can reconstruct from the repo: the Node/pnpm version floors (`engines`, `packageManager`, `.node-version`), the `pnpm vitest run …` scoping block (a standard invocation, and `test:types` is already a script), the `packages/start/src/` file enumeration, and the published-package/tsconfig field restatements. The `declarationMap: false` rationale stays — that one the config cannot explain. The file enumeration was also wrong: it named `ambient.ts`, `drain-report.ts`, `signals.ts` and `uncaught.ts`, none of which have existed since those concepts were folded into `units.ts`, `drain.ts` and `process-handlers.ts`. Two live citations drifted with them — `UnitRecord` is in `units.ts`, and "does not leak between concurrent units" is `units.spec.ts:31` — as did the `docs-examples.test-d.ts` note, which guards `drain.ts`. All three corrected. Moved "Load-bearing runtime invariants" and "Internal design" into packages/start/CLAUDE.md, which loads only when a session works under that directory. Nothing in examples/, the READMEs or CI needs either section, and both are byte-identical to what left the root file. "Public surface" deliberately stays put: examples/ consumes that API. Root file: 53,748 -> 38,624 chars. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
This PR refactors repository guidance by trimming the root CLAUDE.md to remove information that can be trivially reconstructed from the repo/config, and by relocating packages/start-specific internal/kernel-invariant documentation into packages/start/CLAUDE.md so it’s only loaded when working in that package.
Changes:
- Added
packages/start/CLAUDE.mdcontaining the “Load-bearing runtime invariants” and “Internal design” sections for kernel maintenance work. - Removed those internal sections (and other derivable/duplicated blocks) from the root
CLAUDE.md, replacing them with a pointer to the package-local file. - Updated stale references in the root doc to point at current source/test locations (e.g.,
UnitRecord→units.ts).
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
packages/start/CLAUDE.md | New package-local kernel internals doc (invariants + internal design) for packages/start work. |
CLAUDE.md | Trimmed root guidance and replaced detailed kernel internals with a pointer to the package-local doc; fixed drifted references. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
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 freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
The root
CLAUDE.mdhad grown to 53.7k chars — past the point where Claude Code warns about a memory file — and every session paid for all of it. None of the rules changed; this is three maintenance passes over the file.Cut what the repo already says
Four blocks a session can reconstruct with
lsor by reading a manifest:engines,packageManager,.node-version)pnpm vitest run …scoping block — a standard invocation, andtest:typesis already a scriptpackages/start/src/file enumerationThe
declarationMap: falserationale stays. That one the config cannot explain.Fix three references that had drifted
The file enumeration was not merely derivable, it was wrong: it named
ambient.ts,drain-report.ts,signals.tsanduncaught.ts, none of which have existed since those concepts were folded intounits.ts,drain.tsandprocess-handlers.ts. Two live citations went with them, plus thedocs-examples.test-d.tsnote:`UnitRecord` in `ambient.ts`units.ts:5`ambient.spec.ts` → _"does not leak between concurrent units"_units.spec.ts:31cannot drift from `runtime.ts` or `drain-report.ts`drain.ts:7Move the kernel internals behind a directory
"Load-bearing runtime invariants" and "Internal design" now live in
packages/start/CLAUDE.md, which loads only when a session works under that directory. Nothing inexamples/, the READMEs or CI needs either section. Both are byte-identical to what left the root file, and a## Kernel internalspointer replaces them."Public surface" deliberately stays in the root:
examples/consumes that API.Root file: 53,748 → 38,624 chars, back under the warning threshold.
Gate
pnpm format --checkandpnpm knipgreen; the rest of the gate is untouched by a docs-only change. No changeset —CLAUDE.mdis not in the publishedfiles.🤖 Generated with Claude Code