Repository navigation
docs(claude): split CLAUDE.md's changelog into path-scoped topic files - #2712
Open
cuong-tran wants to merge 1 commit into
Open
cuong-tran wants to merge 1 commit into
cuong-tran wants to merge 1 commit into
Conversation
CLAUDE.md had grown to 270 KB, and every session loaded all of it. The 90 dated changelog entries added since July 2026 now live word for word, in their original order, in twelve files under .claude/rules/, grouped by area. Each file lists the code it covers in its `paths:` frontmatter, so Claude Code loads it only when one of those files is read or edited. CLAUDE.md keeps its guide sections unchanged and drops to 34 KB. CLAUDE.md gains two sections: Rules That Apply Everywhere, for the ten traps that are not tied to one area, and Topic Notes, a table of the twelve files. The Auto-Update Rule now sends new entries to the topic file that covers the code. Two cross-references that now point into another file name that file. data-storage.md matches ArtistRepositoryImpl.kt, the name that file takes in core once its stray second .kt extension is removed.
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.
What & why
CLAUDE.mdhad grown to 1,102 lines and about 270 KB, and Claude Code loads all of it into every session, roughly 70k tokens before any work starts. Claude Code's docs suggest staying under 200 lines. About 90% of the file was the dated changelog: 90 entries, each recording the traps of one area of the code.This moves those entries, word for word and in their original order, into twelve topic files under
.claude/rules/. Each file lists the code it covers in itspaths:frontmatter, and Claude Code loads it only when Claude reads or edits one of those files. Everything above the changelog inCLAUDE.md(overview, modules, guidelines, common tasks, playback architecture) is unchanged, so the file drops to 636 lines and 34 KB.The twelve files, 11–32 KB each:
playback-desktop,playback-engine,audio-effects,youtube-scraper,lyrics,now-playing,ui-design,analytics-wrapped,home-library,data-storage,integrations,build-and-tooling.Also in
CLAUDE.md:%1$s/%1$dlimit,Color.Blackas a page colour and keeping time controls left-to-right. Path scoping would hide these, so they stay inCLAUDE.md, each naming the topic file that explains it.pathscover the code, widening itspathsor adding a new file and a table row when needed, not toCLAUDE.md. Hub files such asSharedViewModel.ktandApp.ktstay out of everypathslist, or editing them would load every topic at once.Two cross-references between entries now name the file their target moved to. Nothing else in the moved text changed.
Needs maxrave-dev/core#44 for one pattern:
data-storage.mdmatches**/ArtistRepositoryImpl.kt, while core still names that fileArtistRepositoryImpl.kt.kt. This PR does not bumpcore; until it is bumped, editing that one file simply does not loaddata-storage.md.Linked issue
No issue: this changes only the agent guide (
CLAUDE.mdand.claude/rules/), no app code.Checklist
Tested in Claude Code rather than on a device, since no app code changed. A script compared every changelog line before and after: each appears exactly once, apart from the two cross-reference edits. Every
pathspattern matches at least one file in the repo. In a live session, topic files loaded for files inside thecoresubmodule and for each pattern form used (dir/**,**/Name.kt,src/*/…), and a topic scoped to another module did not load. EditingSharedViewModel.ktorApp.ktloads no topic file.