Skip to content

Split CLAUDE.md into always-loaded rules and an on-demand DECORATOR.md; prepare 2.4.0 - #6

Merged
chorta merged 1 commit into
mainfrom
claude/claude-md-size-limit-62f2d8
Sep 30, 2026
Merged

chorta merged 1 commit into
mainfrom
claude/claude-md-size-limit-62f2d8

Conversation

@chorta

@chorta chorta commented Sep 30, 2026

Copy link
Copy Markdown
Contributor

Why

Claude Code warned that CLAUDE.md was 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, sync also compiles canvas-rules/ and component-library READMEs into the same file.

Moving everything into DECORATOR.md and 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 read DECORATOR.md" for everything would be worse: rules like never running verify --accept have to be in context before the agent knows it needs them.

What changed

Renderer (scripts/lib/rules.mjs)

  • New marker for rules/*.md: <!-- on-demand: before you … -->, on its own line inside a ## section.
    • The rule files keep the text above the marker, plus a generated pointer such as "Before you copy a template, read this section in full in DECORATOR.md."
    • DECORATOR.md gets the whole section.
    • A marker above a rule's first section moves the rest of that rule. The kickoff interview uses this.
  • New generated output, DECORATOR.md, at the root. Nothing imports it.
  • Compilation fails on:
    • a marker with no trigger, or one split across lines;
    • two markers in one block;
    • two rules that move sections with the same heading;
    • a marker in a project's canvas-rules/ file. Those rules always load in full.
  • Component-library READMEs now compile into DECORATOR.md. The rule files keep the "Project component libraries" preamble (what relaxes, and what never does) and one pointer per library.

Rules (rules/)

  • 18 sections now sit behind markers. Each keeps a short actionable rule in the always-loaded files, for example "Keep pull-right on the wide canvas section" and "Copy both search blocks verbatim". The measured detail moved verbatim.
  • Unchanged and still loaded in full: the chrome integrity gate, navigation, accessibility, and security sections.
  • A few "this file" and "above" references in moved text were reworded so they still make sense inside DECORATOR.md.
  • The always-loaded site-name text now says the rename is the agent's to make, with no --accept needed. A test session hesitated without it (see Testing).

CLI (bin/cli.mjs)

  • init and add write DECORATOR.md and list it in the manifest.
  • Migration: sync and check treat DECORATOR.md as managed wherever a rule file is. A project set up by 2.3.0 gets the file on its next sync, and check fails until then. Without this, CLAUDE.md would point at a missing file.
  • sync and check print a note (not a failure) when a project's CLAUDE.md passes 40,000 characters, showing how much canvas-rules/ and canvas-components/ add.

Docs and release

  • README gains a new section, "What loads every session, and what loads on demand". Also updated: the skill's pointers and their library/ copy, both templates/*-README.md files, and CHANGELOG.md.
  • Version 2.4.0 in package.json and .claude-plugin/plugin.json.
File Before After
CLAUDE.md 49,901 chars, 987 lines 24,739 chars, 538 lines
AGENTS.md, .cursorrules, Copilot instructions about 49,800 chars each about 24,650 chars each
DECORATOR.md — 39,553 chars, read on demand

Reviewer notes

  • The size budget is 25,000 characters, not 20,000. test/rules.test.mjs fails if the kit's compiled CLAUDE.md goes 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.
  • Behavior change for projects with component libraries: README bodies are no longer loaded into every session. Agents read them from DECORATOR.md before using the library.
  • The 40,000 figure comes from Claude Code 2.1.207's own check, which is applied per file: the larger of 40,000 characters and a share of the context window.
  • After merge, publish a GitHub release tagged v2.4.0 to trigger the npm publish.

Testing

  • npm test passes: 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.
    • CLI tests: DECORATOR.md install, drift detection, the 2.3.0 → 2.4.0 migration, and the size note.
    • The tarball test now also excludes the repo's own DECORATOR.md.
  • Headless Claude Code sessions (claude -p, Sonnet) in scratch projects:
    • "Rename the site to Division of Physical Sciences": the session read the site-name section of DECORATOR.md first. 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.
    • "Create about-us.html from the two-column template…": the session never opened DECORATOR.md, but the always-loaded one-line rules covered the task. pull-right was kept, both search blocks were intact, and every asset pointed at the CDN. verify reported only the expected "no golden recorded yet" notices. This is why every moved section keeps its one-line rule in the always-loaded files.
  • Not checked: the interactive startup warning and /context, which headless runs don't show.

🤖 Generated with Claude Code

…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>
@chorta
chorta merged commit f4180af into main Sep 30, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant