Anthropic’s engineering team has quietly overhauled the playbook for one of the most important files in a Claude Code project — and the new rule is brutally simple: every line you add to CLAUDE.md had better earn its keep. The company now advises developers to cap the file at 200 lines, split specialized instructions into subdirectory files and skills, and throw out any rule that just papers over a past model’s weakness. It’s a discipline shift, and for Windows developers using Claude Code through PowerShell, Git Bash, or WSL, following it can mean shorter sessions, fewer token-costly reruns, and a lot less context-fighting.
What Changed in Anthropic’s Guidance
The CLAUDE.md file has always been the project’s “onboarding doc” for Claude Code: a way to hand the AI agent build commands, directory layouts, and coding conventions at the start of every session. But as the tool matured, many developers turned it into an instruction dump — a sprawling collection of every past prompt, every edge case, and every model failure they’d ever hit. Anthropic’s own engineers now say that approach backfires.
The company’s published best practices (updated in June and amplified by an XDA report on July 31) make several concrete recommendations:
- Cap the root CLAUDE.md at 200 lines. Anthropic’s Claude Code documentation explicitly sets this ceiling. A root file loads in full at session start and stays in context, so longer files steal tokens from the actual task, test output, and codebase.
- Use the
/initcommand to generate a starter file. Claude Code can scan a repository and guess its structure, build scripts, and common conventions. Let it do the grunt work, then trim the result down to what’s genuinely necessary. - Split context by scope. Rules that apply to only one part of a monorepo belong in a subdirectory CLAUDE.md, which loads only when Claude reads files there. Recurring procedures (release checklists, deployment routines) should live in skills, not in the always-on root file. Hooks and CI checks are better than natural-language instructions when a behavior must be enforced deterministically.
- Periodically delete and rebuild. Claude Code creator Boris Cherny recommends wiping your CLAUDE.md, skills, and hooks every six months and seeing what the current model actually needs. Many rules originally written to correct a past model’s bad habits will be dead weight with a newer release.
The shift is from “write down everything the AI might forget” to “record only what the codebase cannot tell it.”
Why a Lean CLAUDE.md Matters — and Who It Hurts Most
The threat of context bloat isn’t academic. Every word in the root CLAUDE.md eats into Claude’s finite context window, leaving less room for the actual code you want changed, the terminal output from a failed test, and the conversation that follows. A file bloated to 500 lines can silently push critical project details out of the model’s attention, leading to more hallucinations or forgotten guidelines.
For Windows developers, the stakes are slightly different. Claude Code now runs natively on Windows as well as inside WSL, but the two environments are not identical. A CLAUDE.md that says “run tests with npm test” might work under WSL but spawn endless path errors when invoked from PowerShell. A rule that mandates a Unix-style forward slash for file paths can break native Windows tools. The opposite — assuming Windows command idioms — can confuse a model running in WSL. Anthropic’s lean-file philosophy forces you to add only those environment-specific details that cause real friction, not every hypothetical. For a team with a Windows desktop client, a cloud API, and infrastructure-as-code, that means strictly limiting the root file to cross-cutting facts, while leaving the Windows client’s build instructions in its own subdirectory CLAUDE.md.
How to Split Your Instructions: The New Hierarchy
Anthropic’s updated architecture distinguishes seven mechanisms for steering Claude Code, each with a different context cost and loading behavior. For everyday project work, the hierarchy looks like this:
| Mechanism | When It Loads | Best For |
|---|---|---|
| Root CLAUDE.md | At session start, always in context | Project-wide commands, directory map, core conventions |
| Subdirectory CLAUDE.md | When Claude reads files in that directory | Module-specific rules, API versions, local test commands |
| Skills | On demand, invoked by name | Release procedures, dependency audits, bug-reproduction steps |
| Hooks | After every edit or command | Deterministic formatting, linting, security checks |
| System prompt additions | Session start, alongside root file | Global output style, tool-usage preferences |
Root and subdirectory CLAUDE.md files are markdown; skills are separate text files loaded by Claude when needed. The practical upshot: you stop asking one file to do five jobs badly. If a rule applies only to the “app/api” directory, put it in app/api/CLAUDE.md, not in the root. If it’s a checklist you run before every release, turn it into a skill.
Stopping the Context Bloat: Practical Steps for Your Project
1. Start with /init and slash courageously. Run the command, review the output, and delete everything that isn’t a concrete, testable fact. “Run pnpm test --filter api after changing API handlers” stays; “Write high-quality code” goes. For Windows users, explicitly state the shell: “All commands in this file assume Git Bash” or “Run build commands from PowerShell 7.”
2. Split by directory when your repo has boundaries. A monorepo with a React frontend, a .NET API, and Terraform definitions should have three subdirectory CLAUDE.md files. Keep the root file to: the project summary, a high-level directory tree, a single standard build command for CI, and the handful of conventions that genuinely apply everywhere.
3. Move procedures to skills. A verbose release-prep checklist doesn’t need to be in session memory while you’re fixing a UI bug. Store it as a skill and invoke it only when you’re about to ship.
4. Automate the things that must not fail. If your team requires that all TypeScript files pass prettier --check, don’t ask Claude to remember it; enforce it with a hook or a pre-commit CI check. Natural-language instructions are requests; hooks are guarantees.
5. Keep secrets out, period. CLAUDE.md is source-controlled and read by the model; never put API keys, tokens, internal endpoints, or credentials in it. Use a proper secrets manager.
The Six-Month Purge and the Future of AI-Specific Rules
Boris Cherny’s advice to delete your entire CLAUDE.md, skills, and hooks every half year sounds drastic, but it’s a powerful regression test. Many of the rules you wrote last year were compensations for an older model’s blind spots — formats it got wrong, packages it forgot to install, tests it skipped. When the model improves, those rules become noise, and they can even overconstrain a newer, smarter release.
Instead of a blind wipe, consider a controlled review: create a branch, delete any instruction that looks like a model-specific workaround, then run your usual tasks — a bug fix, a cross-service feature, a documentation update. Compare the results with and without the trimmed context. Restore only the lines that demonstrably prevent a regression. This process turns your CLAUDE.md into what it should have been all along: a record of your project’s truth, not a museum of past AI failures.
For Windows developers, the same discipline applies. A rule saying “use WSL for all commands” might have been essential with an early Claude Code build that didn’t support PowerShell well. A newer agent may handle native Windows paths just fine, and that instruction could be steering it away from a more direct workflow. Test it.
Anthropic’s message is consistent: treat your context file like code — version it, review it, refactor it, and don’t let it grow stale. The future of AI-assisted development won’t be about writing longer prompts; it will be about writing the right short ones.