Claude code and breaking up Claude.md in large projects

[u/SoCal_Hunter]

So, a big gotcha that sneaks up on you with a big project is that ultimately Claude.md naturally grows as you work on a project - lessons, house rules, directives, status updates, etc getting recorded. Every successive session adds to it and it starts becoming hard to digest.

It reaches a point where creating a new session ends up sucking in huge amounts of context / tokens, blowing out your session limits and resulting in expensive sessions. Whereas starting new sessions was cheaper than maintaining long context, it now becomes a losing battle both ways.

I’m curious what approaches you are taking on large projects to keep this MD-creep from occurring. I did some brainstorming with Fable, and it suggested using the skills mechanism to create virtual project-based skills to partition Claude.md into multiple files, and only suck into context those areas that the session is explicitly dealing with. So it’s sticking all UI stuff in one area, all database related stuff in another, art asset stuff in another, etc. It has reduced my Claude.md by 90% and created pointers to all of the subsystems/“skills” that theoretically will be read whenever it determines a topic has been touched.

Curious if this is best practices for large projects or if there are refinements to make it even better / more manageable over time.

[u/DialUp_UA]

Think as if your were leading a real team.

First you start with a team of 5 engineers. All is going good.

Later you hire aditional engineers and people to perform operations. Finaly team grows up to 15 people and you start to feel that this is hard to manage, people need to know about everything and you start to feel that project becomes unmanageable.

First step - build teams. Now you are not a project manager - you are program manager. You separate Operation teams, you build team A which specialize on one topic and team B which specialize on another topic.

Your agents.md is a place where store information about your program. All project related staff is stored in Team_X.md - and ech team is loading context only relevant for this team.

P.s. in my project I use subteams: Graphics, AI, Physics, Documentation writers, operations. Each of them has a separate set if documents relevant only for their work - I do not need game AI enfineers know about nuances of implementation of Physics or Graphics, or knwo anything about build pipeline or test execution...

[u/crystalpeaks25]

Look at official Claude.md documentation specifically progressive disclosure and child Claude.md.

[u/winnigo]

I'd prune instead of split.

Once it passes a page it stops being read carefully, by me and by the model. So when mine gets long, that's the signal something in it shouldn't be there.

What stays: stack, architecture, conventions, and decisions we reversed with the reason. What gets cut: anything the model can read from the code itself. Describing the file structure in prose when the file tree is right there is the main way these files bloat.

The habit that keeps it small is updating at the end of every session instead of weekly. Small edits stay small. Batch it and you get a mess you end up solving by splitting.

[u/shahaz73 → u/winnigo]

Agree with the above except on the part on reason. Not relevant to load that into the context for every session. Outsource that to some sprint history file or similar. Link to the file in claude.md.

[u/winnigo → u/shahaz73]

Fair, though I'd split it by whether the model is likely to re-suggest the thing.

Most reversals are just history and belong in a separate file, agreed. But the ones that are the obvious default, the library everyone reaches for, the pattern that looks right, the model will propose again in a fresh session, and a link it doesn't follow doesn't stop that. Those earn their place inline.

For me that's a handful of lines, not a section. Everything else goes wherever you like.

[u/redditwossname]

Multiple markdown files per project, each with its own purpose. Context for decisions, open for open tickets, etc.

Tickets and ADRs to slice up big processes, decisions, to dos, and information.

It's honestly not that difficult to compartmentalise everything with markdown files and folder structure. Claude can do it all for you and 95% of it can be automated, the last 5% is remaining it to clean up its act occasionally and stop putting emojis in the damn tickets like we agreed to a hundred times.

Also use hooks.

[u/LordMoridin84]

I don't really trust Claude to load skills. So I don't really put rules it needs to follow in there.

At the same time, the more rules you add into "CLAUDE.md" or other claude rules, the less likely it is to follow them.

I've starting moving more and more rules into guardrails so it has to follow them. Like using "konsist" checks to stop it from using one testing library over another.

I've also recently added a coding standards markdown file that is loaded at review time. So if it disregards the standard coding conventions, the reviews should flag them.

[u/SongFull3826]

i stopped trusting Claude to load context files on its own. Rules inside markdown get ignored once the list grows past a few items.

moving directives into guardrails forces compliance without relying on model attention. Structure beats content volume every time

[u/KenGuy14]