CLAUDE.md at scale: when one file stops working
CLAUDE.md is right for one repo. It runs out across twelve repos, two machines, and clients that never read the file. What to keep, and what to move out.
CLAUDE.md is the right tool for one repository. It runs out in three specific places: when the same instructions belong in twelve repos, when the knowledge is about you rather than the code, and when you open a client that never reads the file. A longer CLAUDE.md fixes none of them. Keep the file small and repo-specific, and put the portable part in a layer any client can read over MCP.
How the file actually loads
Worth knowing before deciding what to put in it.
Claude Code walks up the directory tree from where you launched it and concatenates every CLAUDE.md and CLAUDE.local.md it finds, root-down, so the file closest to your working directory is read last. Files in subdirectories below you load later, when Claude reads something in that directory. All of it lands in the context window at session start and costs tokens on every turn.
Anthropic’s own guidance is under 200 lines per file, because longer files reduce adherence. @path imports help you organize, but they don’t buy context back: imported files are expanded and loaded at launch too, up to four hops deep.
The one mechanism that genuinely defers loading is .claude/rules/ with a paths frontmatter field. A rule scoped to src/api/**/*.ts only enters context when Claude touches a matching file. If your CLAUDE.md is bloated with instructions that matter to one corner of the codebase, that’s the move.
There’s also auto memory, where Claude writes its own notes to ~/.claude/projects/<project>/memory/. The MEMORY.md index loads at session start, capped at the first 200 lines or 25KB. It’s useful and it’s plain markdown you can edit. It’s also, per the docs, machine-local: not shared across machines or cloud environments.
Where it stops scaling
The same paragraph in twelve repos. Your commit-message convention, your testing philosophy, the fact that you want standard library over frameworks — none of that is about the repository. You can hoist it to ~/.claude/CLAUDE.md, and you should. That covers every project on one machine.
One machine. The laptop, the desktop, a Codespace, or a cloud agent. Each gets its own ~/.claude/, its own auto memory, its own drift. You notice it the first time you fix a misunderstanding on one machine and hit the identical misunderstanding on another that afternoon.
Only Claude Code reads it. Claude Code reads CLAUDE.md, not AGENTS.md. The documented workaround is a CLAUDE.md that imports AGENTS.md, which tells you how per-repo and per-tool this layer is. Meanwhile claude.ai doesn’t read your repo file at all, Cursor has its own rules format, and ChatGPT has neither. You explain yourself once per tool, forever.
The pattern under all three: CLAUDE.md is scoped to a checkout on a disk, and a lot of what you’re putting in it isn’t.
What stays in the file
Keep everything that’s true of this codebase and only this codebase:
- Build, test, and lint commands.
- Directory layout and where new code goes.
- Conventions that differ from the tool defaults, the ones a new teammate would get wrong.
- Gotchas with a reason attached. “Don’t deploy by hand, CI applies migrations first” earns its lines.
- Routing: pointers to the docs that carry the detail.
That last one is the highest-leverage shape. The CLAUDE.md for the codebase behind this site is under 80 lines and is mostly a table: topic, file, when to read it. Nothing about the data model lives in it; there’s a row pointing at docs/data-model.md. Session start pays for the index, not the encyclopedia, and a task that never touches the schema never loads the schema.
What moves out
Three kinds of thing belong somewhere every client can reach.
Who you are and how you work. Languages, stack, review standards, the tone you want in writing, the things you never want done. This is one document, it’s true in every repo, and it should be in scope before you type anything.
Reusable how-tos. The way you cut a release, your house style for an API, the checklist for a migration. In Claude Code these are skills — packaged instructions loaded on trigger rather than at launch. Written once, they should be available to every assistant you use, not copied into each repo that needs them.
Durable decisions and work in flight. Why you picked a service. What broke last time. What you want done next. None of that belongs in a file that loads into every session forever, and none of it should be trapped on one machine.
What’s worth keeping for your AI goes deeper on the curation question. The short version: save what you’d groan at re-explaining.
Wiring the layer underneath
vtriv is a hosted context layer that speaks MCP. Connect once and the same profile, skills, knowledge, and projects are readable and writable from every client:
claude mcp add --transport http vtriv https://mcp.vtriv.com/mcpClaude Desktop and claude.ai: Settings → Connectors → Add custom connector, https://mcp.vtriv.com/mcp. Cursor: Settings → MCP → Add server, type streamableHttp, same URL. Codex CLI: codex mcp add vtriv --url https://mcp.vtriv.com/mcp. It’s Streamable HTTP with OAuth 2.1, so the client opens a browser sign-in and there are no keys to paste.
Then move the three categories over.
Your profile is one markdown document that stays in scope for every session in every context. Ask an assistant to write it and it calls vtriv_create_document; from then on, a fresh chat in any client already knows your stack and your preferences. This is the part ~/.claude/CLAUDE.md was doing, minus the machine.
Skills go in as Agent Skills bundles: a SKILL.md plus any supporting files. Global skills are in scope across every connection; context skills are walled to one workspace, which is how team conventions stay with the team. Same progressive disclosure as Claude Code skills: the assistant sees names and descriptions, and loads the body when a task calls for it.
Knowledge goes in with vtriv_write, which takes a path in a markdown tree, so an architecture decision lands at something like topic/queue-design.md and stays findable. Leave the path off and it goes to inbox/, searchable immediately, filed later or never. Capture should be free; filing is the part worth deferring.
Work goes in as task records on a project. Assignment, status, dependencies, comments, and custom fields are stored state; vtriv_tasks lets a client filter that state. An external runner decides when and whether to execute a task, then writes progress and results to the record. In our daily use, an external runner read this task from vtriv and updated it with the result.
Reading it back is one call. vtriv_context returns who you are, what skills exist, and what’s active. vtriv_search runs hybrid semantic and keyword search across everything. vtriv_pack assembles the relevant passages into a single bundle inside a token budget, which beats a search-then-fetch loop when you’re starting real work.
What this doesn’t replace
CLAUDE.md stays. Claude Code will always read it first and it’s the right home for repo-specific mechanics. That’s the correct scope for a file that lives in the repo. What changes is the file’s job. It stops being the place you dump everything Claude should know and becomes an index for this codebase, while the portable material lives somewhere your other machines and other clients can see it.
The test is concrete: open a session on a different machine, in a different client, and ask a question only last week’s session could answer. If it answers, the layer is real. If you’re setting this up on the chat side too, giving Claude persistent memory across sessions walks the same wiring from a conversation-first angle, and a ChatGPT memory alternative you can read covers the vendor-neutral case.
The free tier holds 50 documents and 25 skills, with unlimited projects and tasks — enough to move your ~/.claude/CLAUDE.md off one laptop and see whether it holds. Get started.