AI coding assistants have evolved from mere snippet generators into collaborators capable of reasoning about architectures, respecting conventions and applying internal policies. That evolution, however, depends almost entirely on one factor: the persistent context the model receives at the start of every session. In the case of Claude Code, Anthropic’s coding assistant, that context is channelled mainly through a Markdown file called CLAUDE.md and a directory structure that any experienced system administrator or developer will recognise as a serious configuration layer.
At first glance, CLAUDE.md looks like a plain documentation file. In practice, it works as a behavioural contract between the repository and the model, read automatically at the start of every conversation, versionable with Git and reviewable like any other technical artefact in the project.
Loading hierarchy, scope and precedence
Claude Code does not just read a single file. The system supports several layers that combine in a specific priority order, from lowest to highest specificity. The top layer corresponds to managed policy, located in paths such as /etc/claude-code/CLAUDE.md and reserved for administrators who want to enforce rules across all users on a machine. Above the user level, but below the project, sits the global personal configuration in ~/.claude/CLAUDE.md, intended for stable developer preferences such as response language, commit style or the way changes should be proposed.
At the repository level, the CLAUDE.md file at the root is shared with the team and committed to source control, while CLAUDE.local.md plays the role of personal overrides and should be added to .gitignore. Below those, CLAUDE.md files placed in subdirectories load on demand when the model reads files within that path, which is especially useful in monorepos. Instructions closer to the working directory are evaluated at the end of the context, which gives them greater effective weight in the model’s reasoning.
The /memory command lets developers inspect every file loaded during the active session. The /init command runs an analysis of the repository and generates an initial CLAUDE.md that should be reviewed and corrected, since the automatic scan can miss internal conventions or assign incorrect architectural patterns. After a /compact, the root CLAUDE.md is automatically reinjected; nested ones in subdirectories only reload when the assistant opens a file in that area again.
Modular rules, automatic memory and technical limits
For large projects, keeping everything in a single file becomes unsustainable. The official solution is modular rules in .claude/rules/*.md, which load automatically and accept frontmatter with the paths field, where glob patterns can be defined. That way, a rule such as “all endpoints must validate input with a schema” is only injected when the model works on src/api/**/*.ts, avoiding context bloat in areas of the repository where the rule does not apply.
To this is added automatic memory, available since Claude Code 2.1.59. Enabled by default, it lets the model save build commands, debugging observations, conventions detected in the code and other learnings it considers useful for future sessions. Automatic memory is stored in ~/.claude/projects/<project>/memory/ with a MEMORY.md file as the index and topic files loaded on demand. It can be disabled with the environment variable CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 or managed through the autoMemoryEnabled setting in settings.json.
Technical limits also matter. The official documentation places the recommended maximum size of a memory file at 40,000 characters and warns that going beyond 200 lines reduces the model’s adherence to the instructions, while increasing token costs. Block-level HTML comments (<!-- ... -->) are stripped before the content is injected, which allows leaving notes for human maintainers without consuming context. In monorepos, the claudeMdExcludes setting can ignore files belonging to neighbouring teams so their conventions do not contaminate the model’s reasoning. The --add-dir flag and the CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 variable extend the scope to directories outside the working one, a common need when sharing configuration across repositories.
It is worth remembering that the contents of CLAUDE.md are not injected as part of the system prompt, but as a user message at the start of the conversation. That means it is not a hardened mechanism: the model reads it and tries to follow it, but vague, contradictory or redundant instructions degrade compliance. Explicit rules, expressed as concrete imperatives — “all functions must include type hints”, “external calls require timeout handling”, “database access always goes through a repository class” — work much better than generic maxims about clean code.
Operational best practices for technical teams
Established experience points to a clear pattern. The project root should contain a brief, stable CLAUDE.md, between 20 and 80 lines for small repositories and rarely more than 200 in large projects. That file acts as an index and architectural summary, and anything deep, path-specific or only relevant in part of the codebase moves to .claude/rules/ with scoped frontmatter.
Rules that change weekly do not belong in the file, since execution plans, task lists or TODOs age poorly and generate contradictions. That kind of information should live in tracking systems, custom commands or reusable skills. What does belong is everything a developer or administrator needs to repeat every time someone new joins the project: tech stack, build and test commands, preferred package manager, deployment requirements, development environment quirks and security constraints.
That transparency is precisely what sets CLAUDE.md apart from other strategies. Compared with proprietary configuration files such as .cursor/config.json or the templates embedded in IDE plugins, CLAUDE.md lives in the repository, goes through pull request reviews and leaves a trace in the Git history, which fits regulatory compliance flows and technical audits. In a way, it is to AI what .editorconfig or .eslintrc are to formatting and linting: a declarative, shared mechanism that replaces tribal knowledge.
The cultural benefit is probably the most underrated. Writing a serious CLAUDE.md forces the team to articulate its rules explicitly; if a convention only exists in the technical lead’s head, writing it down turns it into project property. Operations and development teams that invest that time gain something more valuable than raw generation speed: predictability. And in critical infrastructures or long-lived codebases, predictability is the difference between a useful tool and a steady source of incidents.
Frequently asked questions
What is the exact order of precedence for CLAUDE.md files in Claude Code? The official documentation defines five levels, from lowest to highest priority: managed policy by administrators at /etc/claude-code/CLAUDE.md, the user’s global configuration at ~/.claude/CLAUDE.md, the project’s CLAUDE.md shared via Git, CLAUDE.local.md with personal overrides not committed to source control, and finally nested CLAUDE.md files in subdirectories, which load on demand. Instructions closer to the working directory are evaluated at the end of the context, which gives them greater effective weight.
How can a CLAUDE.md be prevented from growing too large and degrading model performance? The recommended technical maximum is 40,000 characters per file, but loss of adherence becomes noticeable beyond 200 lines. The usual strategy is to keep a concise file at the root, between 20 and 80 lines, acting as an architectural index, and move everything specific to .claude/rules/*.md with paths frontmatter that limits loading to certain areas of the repository through glob patterns.
What is the difference between Claude Code’s automatic memory and a hand-written CLAUDE.md? Automatic memory, available since version 2.1.59, lets the model record build commands, debugging observations or conventions detected during the session on its own. It is stored in ~/.claude/projects/<project>/memory/ and loads at the start of each session. CLAUDE.md, on the other hand, contains explicit rules written by the team and versioned with the code. Both systems are complementary: automatic memory works as an internal logbook, while CLAUDE.md acts as the project’s formal contract.
Is it safe to entrust critical policies to CLAUDE.md, or should they be reinforced with other mechanisms? The contents of CLAUDE.md are injected as a user message, not as a system prompt, so the model tries to follow them but does not comply strictly. For critical security or compliance rules, it is advisable to reinforce them with claudeMdExcludes to avoid cross-contamination, hooks that validate changes before applying them, linting tools and CI/CD pipelines, and managed policies in /etc/claude-code/ that cannot be overridden by local configurations. CLAUDE.md guides behaviour, but the final defences must live in the system, not in the model’s reasoning layer.