Repository navigation
Split CLAUDE.md into always-loaded rules and an on-demand DECORATOR.md; prepare 2.4.0 - #6
Merged
Merged
Conversation
…d; prepare 2.4.0 The generated CLAUDE.md had grown to 49,901 characters, past the 40,000 at which Claude Code warns that a memory file will impact performance, and Claude Code loads all of it in every session. An @DECORATOR.md import would not have helped: imported files load at launch too and count toward the same warnings. A marker in a rules/ section, <!-- on-demand: before you ... -->, now moves what follows it to a generated DECORATOR.md. The rule files keep the rule above it and a pointer naming the task. CLAUDE.md drops to 24,739 characters, and AGENTS.md, .cursorrules, and the Copilot instructions shrink the same way. Component library READMEs compile into DECORATOR.md as well. sync adds DECORATOR.md to projects an earlier release set up, and sync and check print a note when a project's canvas rules push CLAUDE.md past 40,000. test/rules.test.mjs holds the kit's CLAUDE.md to 25,000 characters and checks that every pointer lands on a section. Co-Authored-By: Claude Opus 5.5 <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
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.
Why
Claude Code warned that
CLAUDE.mdwas too large. The generated file was 49,901 characters and 987 lines. Claude Code warns about any memory file over 40,000 characters (more on larger-context models), and it loads the whole file in every session. In consumer projects,syncalso compilescanvas-rules/and component-library READMEs into the same file.Moving everything into
DECORATOR.mdand importing it with@doesn't work. The Claude Code memory docs say imported files still load at launch. Each import also counts as a separate file toward the same warnings, and there is a combined-size warning too. A plain "go readDECORATOR.md" for everything would be worse: rules like never runningverify --accepthave to be in context before the agent knows it needs them.What changed
Renderer (
scripts/lib/rules.mjs)rules/*.md:<!-- on-demand: before you … -->, on its own line inside a##section.DECORATOR.md."DECORATOR.mdgets the whole section.DECORATOR.md, at the root. Nothing imports it.canvas-rules/file. Those rules always load in full.DECORATOR.md. The rule files keep the "Project component libraries" preamble (what relaxes, and what never does) and one pointer per library.Rules (
rules/)pull-righton the wide canvas section" and "Copy both search blocks verbatim". The measured detail moved verbatim.DECORATOR.md.--acceptneeded. A test session hesitated without it (see Testing).CLI (
bin/cli.mjs)initandaddwriteDECORATOR.mdand list it in the manifest.syncandchecktreatDECORATOR.mdas managed wherever a rule file is. A project set up by 2.3.0 gets the file on its nextsync, andcheckfails until then. Without this,CLAUDE.mdwould point at a missing file.syncandcheckprint a note (not a failure) when a project'sCLAUDE.mdpasses 40,000 characters, showing how muchcanvas-rules/andcanvas-components/add.Docs and release
library/copy, bothtemplates/*-README.mdfiles, andCHANGELOG.md.package.jsonand.claude-plugin/plugin.json.CLAUDE.mdAGENTS.md,.cursorrules, Copilot instructionsDECORATOR.mdReviewer notes
test/rules.test.mjsfails if the kit's compiledCLAUDE.mdgoes past 25,000. Getting to 20,000 would have meant condensing the integrity-gate text or loading accessibility and security only on demand, and I did neither. When a rule needs to grow, move its detail behind a marker rather than raising the budget.DECORATOR.mdbefore using the library.v2.4.0to trigger the npm publish.Testing
npm testpasses: compile check, library check, and 134 tests. New coverage:test/rules.test.mjs: how markers split sections, markers inside code fences, invalid markers, every pointer matching a heading, no@imports, and the 25,000 budget.DECORATOR.mdinstall, drift detection, the 2.3.0 → 2.4.0 migration, and the size note.DECORATOR.md.claude -p, Sonnet) in scratch projects:DECORATOR.mdfirst. It renamed both pages identically, added a short form, and ran no--accept. On the first run it hesitated before reading that section; the site-name wording above fixed that on the rerun.DECORATOR.md, but the always-loaded one-line rules covered the task.pull-rightwas kept, both search blocks were intact, and every asset pointed at the CDN.verifyreported only the expected "no golden recorded yet" notices. This is why every moved section keeps its one-line rule in the always-loaded files./context, which headless runs don't show.🤖 Generated with Claude Code