Trim always-loaded Claude context and add llm-docs discovery - #14701
Merged
Conversation
The file sat well over the documented ~200-line guidance for an always-loaded memory file. Removed content derivable from the codebase (directory-walkthrough prose, the internal steps of configure.sh, the flaky-test phase list that already lives in its linked dev-doc) and redundant restatements, keeping the non-guessable commands, file paths, subsystem registration points, and gotchas. 276 to 85 lines; no guidance a reader still needs was dropped.
The llm-docs/ deep-dive docs had no mechanism steering a reader to the relevant one when a matching task came up. Each topical doc now has a one-line discovery pointer inside a rule under .claude/rules/ whose paths: frontmatter matches the doc's own source, so it surfaces lazily only when that area is edited, with no added always-loaded cost. Topic-specific docs with no sufficiently narrow existing rule get a small dedicated rule, so e.g. a reveal.js pointer never loads on unrelated format work. The convention is documented in llm-docs-maintenance.md for future docs.
CLAUDE.md: correct the filter list to pipeline order (quarto-pre runs before crossref/layout) and drop a run-tests example that merely repeated the testing/overview.md pointer beside it. Converge rule-to-rule duplication to single sources: filters/overview.md and schemas/zod-usage.md now point to dev-tools/dev-call-commands.md for the dev-call commands instead of restating them (also fixing a bare 'quarto' invocation that bypassed the dev binary), and testing/typescript-tests.md references testing/overview.md for the shared core-files table.
The callout CSS the doc covers lives in shared scss (_bootstrap-rules.scss, revealjs/quarto.scss) that a callout-specific glob cannot match, so a standalone callout rule never surfaced when that CSS was edited. sass-theming's paths already cover those scss files and callout styling is theming work, so the pointer belongs there alongside the sass-theming-architecture pointer.
Path-scoped discovery pointers only fire once a matching source file is being edited, so they miss the planning/investigation phase where a subsystem deep-dive is most useful. CLAUDE.md is always loaded, so it now states when (before non-trivial work on an unfamiliar area) and how (ls llm-docs/, read the topic-named doc) to consult llm-docs/ directly, with the path-scoped rules as the lazy backstop.
Moving the callout pointer wholesale into sass-theming dropped discovery for the doc's non-scss key files (styles-callout.html, callout.lua), since sass-theming only matches scss/theming paths. Restore a callout rule scoped just to those callout-specific files; sass-theming keeps the pointer for the shared scss. Together they cover all four of the doc's key files with no cross-topic pollution.
… files The branch review found these two discovery rules omitted narrow, topic-specific source files their linked llm-docs list as key: the pandoc-template rule missed package/src/common/update-pandoc.ts (the writePandocTemplates updater that copies the templates), and the code-signing rule missed the macOS entitlements/distribution files and the keychain/sign-files GitHub actions. Adding them keeps each scope tight to its own topic.
Collaborator
✅ Snyk checks have passed. No issues have been found so far.
💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse. |
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
2 participants
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
.claude/context files that load into every Claude Code session on this repo had grown past the documented guidance for always-loaded memory files (.claude/CLAUDE.mdwas 276 lines against a ~200-line target), inflating the baseline token cost of each session. Separately, the architecture deep-dives underllm-docs/had no discovery mechanism, so a relevant doc was rarely read even when a task would benefit from it.Context compression
.claude/CLAUDE.mddrops from 276 to 79 lines. Removed only content derivable from the codebase (directory-walkthrough prose, the internal steps ofconfigure.sh, a flaky-test phase list that already lives in its linked dev-doc) and restatements duplicated by the rule files; the non-guessable commands, paths, subsystem registration points, and gotchas stay.llm-docs discovery
Each
llm-docs/*.mddeep-dive is now reachable from a one-line pointer inside a path-scoped rule under.claude/rules/whosepaths:frontmatter matches the doc's own source. The pointer loads lazily, only when that area is edited, so there is no added always-loaded cost. Topic-specific docs with no sufficiently narrow existing rule get a small dedicated rule, so a pointer never loads on unrelated work — a reveal.js pointer fires only on reveal.js source, not on all format edits..claude/CLAUDE.mdalso gains an always-loaded instruction to consultllm-docs/directly during planning or investigation, since the path-scoped pointers only fire once a matching file is open.Rules cleanup
A pass over
.claude/rules/converged content duplicated across rule files (and between a rule file and CLAUDE.md) to single sources, and corrected two accuracy issues found along the way: the filter list in CLAUDE.md now reflects the real pipeline order, and a stray barequartoinvocation was pointed back at the dev binary.The convention for adding future
llm-docs/*.mddocs is recorded in.claude/rules/llm-docs-maintenance.md.