Skip to content

docs(claude): split CLAUDE.md's changelog into path-scoped topic files - #2712

Open
cuong-tran wants to merge 1 commit into
maxrave-dev:devfrom
cuong-tran:docs/split-claude-md
Open

cuong-tran wants to merge 1 commit into
maxrave-dev:devfrom
cuong-tran:docs/split-claude-md

Conversation

@cuong-tran

Copy link
Copy Markdown
Contributor

What & why

CLAUDE.md had 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 its paths: frontmatter, and Claude Code loads it only when Claude reads or edits one of those files. Everything above the changelog in CLAUDE.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:

  • Rules That Apply Everywhere: ten one-line traps that are not tied to one area, such as kotlin-lsp not being a compile gate, what may be logged, Compose Resources' %1$s/%1$d limit, Color.Black as a page colour and keeping time controls left-to-right. Path scoping would hide these, so they stay in CLAUDE.md, each naming the topic file that explains it.
  • Topic Notes: a table of the twelve files, so an agent can open one directly for a question before touching any code.
  • Auto-Update Rule: new entries go to the topic file whose paths cover the code, widening its paths or adding a new file and a table row when needed, not to CLAUDE.md. Hub files such as SharedViewModel.kt and App.kt stay out of every paths list, 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.md matches **/ArtistRepositoryImpl.kt, while core still names that file ArtistRepositoryImpl.kt.kt. This PR does not bump core; until it is bumped, editing that one file simply does not load data-storage.md.

Linked issue

No issue: this changes only the agent guide (CLAUDE.md and .claude/rules/), no app code.

Checklist

  • This PR addresses an accepted issue (linked above)
  • I wrote or personally reviewed every line of this change
  • I tested it on Android and/or Desktop (say which, and how)

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 paths pattern matches at least one file in the repo. In a live session, topic files loaded for files inside the core submodule and for each pattern form used (dir/**, **/Name.kt, src/*/…), and a topic scoped to another module did not load. Editing SharedViewModel.kt or App.kt loads no topic file.

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.
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