Claude Code’s
That makes a bad file costly in two ways. It reduces the room available for the codebase, terminal output, test failures, and the actual task at hand; it can also dilute the instructions that genuinely matter. The winning pattern is not a giant “make the AI behave” prompt. It is durable project context, kept short enough that Claude can consistently act on it.
XDA describes
Anthropic’s Claude Code documentation says the root-level file is appropriate for build commands, directory layout, monorepo structure, coding conventions, and team norms. Those are facts an agent needs early and repeatedly. They prevent predictable failures such as using
The best entries are therefore concrete and testable. “Run
For a Windows-oriented repository, that clarity can include environmental details that are easy to overlook in cross-platform teams: whether contributors should use PowerShell, Git Bash, WSL 2, Visual Studio Build Tools, a particular Node.js version, or a specific path convention. Claude Code now supports native Windows usage as well as WSL configurations, but those environments do not behave identically. A one-line rule stating that test commands must run from WSL, for example, can save a string of confusing failures involving paths, shell syntax, file permissions, or native dependencies.
The most immediately useful recommendation from XDA is also the least glamorous: start with Claude Code’s
That is a sensible shortcut because the mechanical inventory is exactly the work humans are prone to do incompletely. A generated first pass can capture scripts in
But generated context should not become policy without inspection. The tool can see that a command exists; it cannot necessarily know whether it is the approved command for CI, whether it is safe against production-adjacent resources, or whether a seemingly unused directory is a hard compatibility boundary. It also cannot reliably capture the reasons behind project decisions—particularly the exceptions that senior engineers know are expensive to rediscover.
A practical starting file might contain only a project summary, a small directory guide, the standard setup/build/test commands, and a few rules that have already prevented real errors. The next additions should come from recurring friction: a correction the team keeps typing, an incorrect tool invocation, a test Claude consistently forgets, or an architectural rule it repeatedly violates.
That turns
A root
Subdirectory
Skills are better for procedures that are occasionally needed but verbose when loaded all the time: release preparation, deployment checks, dependency-audit routines, or a workflow for reproducing customer bugs. Hooks are the right mechanism when a behavior must be deterministic rather than suggested. If formatting must happen after every edit, a hook or CI enforcement is materially stronger than asking a model to remember.
This is the core architectural lesson: instructions should be loaded according to scope and authority. Project facts belong in
The point is not to discard a project’s engineering knowledge recklessly. A repository’s actual build command, security boundary, and release procedure do not become obsolete because the model improved. The candidates for deletion are workaround instructions: rigid reminders created because an older model reached for the wrong package, made a formatting mistake, or skipped an obvious verification step.
Those rules can become stale in several ways. They may use tokens without changing behavior. They may conflict with later instructions. Worse, they may overconstrain a newer model that can make a sound judgment if given the repository’s real requirements instead of an old collection of defensive patches.
For teams, the safer implementation is a controlled review rather than a dramatic purge. Clone the branch, trim instructions that describe model-specific behavior rather than project truth, then run representative work: a bug fix, a feature touching two services, a test failure investigation, and a documentation update. Compare code quality, test coverage, tool usage, and review findings. Restore only the guidance that demonstrably prevents a regression.
This approach also exposes an uncomfortable possibility: some
Secrets do not belong in either place. API keys, tokens, credentials, internal endpoints, and emergency access instructions should stay in approved secret-management systems. A
The same caution applies to tools connected through Model Context Protocol servers. If Claude Code can interact with Slack, source-control systems, cloud services, or databases, instructions should explain intended use and boundaries—but access controls must be enforced by the tool configuration and identity system, not by prose alone.
For Windows shops experimenting with Claude Code, the immediate payoff is straightforward: run
CLAUDE.md file should be treated less like a sprawling AI instruction manual and more like a compact, version-controlled map of a repository: the commands that matter, the conventions that are non-negotiable, and the architectural facts an agent cannot reliably infer. That is the practical takeaway from XDA’s July 31 report on how Anthropic engineers structure their files—and it is increasingly important for Windows developers using Claude Code through PowerShell, Git Bash, or WSL.
The correction is not that CLAUDE.md is unimportant. It is that many developers have turned it into the wrong kind of document: a catch-all record of every past prompt, model failure, team preference, and edge case. Anthropic’s own current guidance is more disciplined. A root CLAUDE.md loads at session start and remains in context throughout the session, so every unnecessary line consumes attention and context whether the task needs it or not.That makes a bad file costly in two ways. It reduces the room available for the codebase, terminal output, test failures, and the actual task at hand; it can also dilute the instructions that genuinely matter. The winning pattern is not a giant “make the AI behave” prompt. It is durable project context, kept short enough that Claude can consistently act on it.
The File Is Project Memory, Not an AI Persona
XDA describes CLAUDE.md as the equivalent of onboarding a teammate who has just joined a project without knowing its layout, build process, or rules. That analogy holds up, but with one important caveat: a human onboarding document can afford to be broad, historical, and occasionally redundant. A file injected into an AI coding session cannot.Anthropic’s Claude Code documentation says the root-level file is appropriate for build commands, directory layout, monorepo structure, coding conventions, and team norms. Those are facts an agent needs early and repeatedly. They prevent predictable failures such as using
npm in a pnpm repository, running an expensive end-to-end suite when a targeted test is sufficient, or adding a feature to the wrong service boundary.The best entries are therefore concrete and testable. “Run
pnpm test --filter api after changing API handlers” is useful. “Write high-quality code” is not. “API route handlers must validate request bodies with Zod” has operational value. “Follow established patterns” forces the model to guess which patterns are established and where they live.For a Windows-oriented repository, that clarity can include environmental details that are easy to overlook in cross-platform teams: whether contributors should use PowerShell, Git Bash, WSL 2, Visual Studio Build Tools, a particular Node.js version, or a specific path convention. Claude Code now supports native Windows usage as well as WSL configurations, but those environments do not behave identically. A one-line rule stating that test commands must run from WSL, for example, can save a string of confusing failures involving paths, shell syntax, file permissions, or native dependencies.
/init Should Be the Draft, Not the Policy
The most immediately useful recommendation from XDA is also the least glamorous: start with Claude Code’s /init command rather than a blank editor. Anthropic documents /init as the way to generate a starter CLAUDE.md from a codebase, giving the agent a chance to identify common commands, visible conventions, and major structure.That is a sensible shortcut because the mechanical inventory is exactly the work humans are prone to do incompletely. A generated first pass can capture scripts in
package.json, a test runner, a linter, build targets, and the outline of a repository. It can also provide a baseline that a team can review in a pull request rather than relying on every developer to create incompatible local notes.But generated context should not become policy without inspection. The tool can see that a command exists; it cannot necessarily know whether it is the approved command for CI, whether it is safe against production-adjacent resources, or whether a seemingly unused directory is a hard compatibility boundary. It also cannot reliably capture the reasons behind project decisions—particularly the exceptions that senior engineers know are expensive to rediscover.
A practical starting file might contain only a project summary, a small directory guide, the standard setup/build/test commands, and a few rules that have already prevented real errors. The next additions should come from recurring friction: a correction the team keeps typing, an incorrect tool invocation, a test Claude consistently forgets, or an architectural rule it repeatedly violates.
That turns
CLAUDE.md into a record of observed needs rather than a speculative catalogue of everything that might someday go wrong.
Put Instructions Where They Load When Needed
The more significant development is that Anthropic no longer framesCLAUDE.md as the sole answer to customization. In a June 18 Claude Code post, Anthropic laid out seven ways to steer the tool, including root and subdirectory CLAUDE.md files, rules, skills, subagents, hooks, output styles, and system-prompt additions. The distinction is not cosmetic: each mechanism has a different context cost and loading behavior.A root
CLAUDE.md is always-on project context. It is the right place for information nearly every task needs. Anthropic’s guidance is to keep the file below 200 lines, assign it an owner, and review changes as carefully as code. That is far more actionable than the vague advice to “keep prompts concise.”Subdirectory
CLAUDE.md files solve a common monorepo problem. Rules for app/api do not need to burden a developer changing a React component under app/web; instructions within a subdirectory can load only when Claude reads files there. A team with a Windows desktop client, a cloud API, infrastructure-as-code, and test automation should not force each workstream’s specialist rules into every session.Skills are better for procedures that are occasionally needed but verbose when loaded all the time: release preparation, deployment checks, dependency-audit routines, or a workflow for reproducing customer bugs. Hooks are the right mechanism when a behavior must be deterministic rather than suggested. If formatting must happen after every edit, a hook or CI enforcement is materially stronger than asking a model to remember.
This is the core architectural lesson: instructions should be loaded according to scope and authority. Project facts belong in
CLAUDE.md; path-specific requirements belong close to the code they govern; recurring procedures belong in skills; deterministic enforcement belongs in automation.The “Delete It” Advice Is Really a Regression Test
XDA also reports advice attributed to Claude Code creator Boris Cherny: periodically deleteCLAUDE.md, skills, and hooks—roughly every six months—and see how a newer model performs without them. The exact timing has not appeared in Anthropic’s formal documentation, but the underlying idea is consistent with the company’s published warning against accumulating instructions without testing whether they still improve outcomes.The point is not to discard a project’s engineering knowledge recklessly. A repository’s actual build command, security boundary, and release procedure do not become obsolete because the model improved. The candidates for deletion are workaround instructions: rigid reminders created because an older model reached for the wrong package, made a formatting mistake, or skipped an obvious verification step.
Those rules can become stale in several ways. They may use tokens without changing behavior. They may conflict with later instructions. Worse, they may overconstrain a newer model that can make a sound judgment if given the repository’s real requirements instead of an old collection of defensive patches.
For teams, the safer implementation is a controlled review rather than a dramatic purge. Clone the branch, trim instructions that describe model-specific behavior rather than project truth, then run representative work: a bug fix, a feature touching two services, a test failure investigation, and a documentation update. Compare code quality, test coverage, tool usage, and review findings. Restore only the guidance that demonstrably prevents a regression.
This approach also exposes an uncomfortable possibility: some
CLAUDE.md files are compensating for weak repository documentation. If an agent needs dozens of rules to find the correct test command or understand module ownership, the long-term fix may be improving README files, contributor documentation, scripts, and CI messages—not endlessly growing the AI context file.
Treat the File as Code—and Keep Secrets Out of It
A shared root file is often checked into Git, which makes it part of the engineering surface area. It should have an owner, meaningful review, and a clear separation between shared standards and personal preferences. Anthropic supports user-level memory for preferences that should follow an individual across projects, while repository-level context should remain about the repository.Secrets do not belong in either place. API keys, tokens, credentials, internal endpoints, and emergency access instructions should stay in approved secret-management systems. A
CLAUDE.md file may be read by an agent, copied into session context, exposed to anyone with repository access, and retained in Git history if committed. It is documentation, not a vault.The same caution applies to tools connected through Model Context Protocol servers. If Claude Code can interact with Slack, source-control systems, cloud services, or databases, instructions should explain intended use and boundaries—but access controls must be enforced by the tool configuration and identity system, not by prose alone.
For Windows shops experimenting with Claude Code, the immediate payoff is straightforward: run
/init, cut the output down to the facts that affect daily work, put platform-specific setup and command requirements in plain language, and split specialized guidance out of the root file. The next time a model upgrade arrives, review that context like any other dependency. The file should describe how the project works—not preserve every limitation of the last model that touched it.
References
- Primary source: XDA
Published: 2026-07-31T19:36:46+00:00
Your CLAUDE.md is probably wrong, and here's how Anthropic's engineers actually structure theirs
Your file is probably doing more harm than good
www.xda-developers.com
- Related coverage: docs.anthropic.com
Advanced setup - Claude Code Docs
System requirements, platform-specific installation, version management, and uninstallation for Claude Code.docs.anthropic.com - Related coverage: docs.anthropic.com
Claude 如何记住你的项目 - Claude Code Docs
使用 CLAUDE.md 文件为 Claude 提供持久指令，并让 Claude 通过自动记忆功能自动积累学习内容。docs.anthropic.com - Related coverage: anthropic.com
Best practices for Claude Code - Claude Code Docs
Tips and patterns for getting the most out of Claude Code, from configuring your environment to scaling across parallel sessions.www.anthropic.com - Related coverage: resources.anthropic.com
Webinar: The Story of Claude Code
In this technical session, you'll hear directly from the creators of Claude Code about its development journey and the challenges overcome with live demos.resources.anthropic.com - Related coverage: anthropic.com
How we contain Claude across products \ Anthropic
Anthropic is an AI safety and research company that's working to build reliable, interpretable, and steerable AI systems.www.anthropic.com - Related coverage: skool.com
Delete your skills before you judge Opus 5 · Claude Code Pirates
📜 The team at Every spent a week with Opus 5 before launch, and their Day 0 verdict is blunt: it's a hard model to love. It argued with instructions, stopped bwww.skool.com - Related coverage: resources.anthropic.com
Claude Code Advanced Patterns: Subagents, MCP, and Scaling to Real Codebases
PDF documentresources.anthropic.com