A global CLAUDE.md is the user-level instruction file at ~/.claude/CLAUDE.md. Claude Code loads it across your projects, making it useful for personal working preferences you would otherwise repeat each session. Repository-specific commands and architecture belong in the project’s own file. Anthropic treats these instructions as context, so they guide behavior without enforcing security controls.
Applies to: Claude Code memory documentation checked October 6, 2026.
On this page
Where the global file lives
Anthropic lists ~/.claude/CLAUDE.md as the location for user instructions. The tilde refers to your home directory. Its scope follows the user account, while ./CLAUDE.md or ./.claude/CLAUDE.md provides instructions for a particular project. A CLAUDE.local.md file provides personal preferences for one project and can be excluded from version control.
That distinction matters when you work on several repositories. A preferred response language may apply everywhere. A package manager, test command or database migration procedure can differ between projects. Putting the latter in a global file makes an unrelated repository inherit an assumption it cannot satisfy.
Source: Anthropic’s memory file locations.
| Instruction | Suitable location | Reason |
|---|---|---|
| Personal communication preferences | Global CLAUDE.md | Useful across repositories |
| Project build and test commands | Project CLAUDE.md | Depend on the checked-out project |
| Personal project-only preferences | CLAUDE.local.md | Relevant to one project and one developer |
| Rules for specific file paths | .claude/rules/ | Can load for matching paths |
| A repeatable task procedure | A skill | Loaded when that task needs it |
The placement suggestions above are editorial guidance based on Anthropic’s documented scopes. See our CLAUDE.md best practices guide for project-level organization.
What deserves a global instruction
Start with corrections you have made in several projects. Anthropic recommends adding persistent instructions when an agent repeats a mistake, a review catches a fact it should know, or you repeatedly explain the same preference. A global file should retain the corrections that remain useful when the project changes.
Make each instruction concrete enough to check. A preference to explain which checks ran and which did not is more useful than a request for high quality. A requirement to inspect repository instructions before choosing commands is safer across projects than prescribing one universal test command.
Keep personal preferences separate from claims about the codebase. A global instruction cannot establish which test suite exists, which deployment target is configured or which files are generated. Those facts need the current repository. When a preference depends on a condition, state that condition explicitly so it does not turn into an unconditional command in the next project.
Anthropic recommends keeping each CLAUDE.md file under 200 lines. This is a size guideline, not a reason to fill the file. A short set of recurring preferences can be enough. Write effective instructions explains specificity, structure and consistency.
How global and project instructions combine
Claude Code loads instructions from broader scopes before the more specific project context. The files contribute to the conversation together. Within the directory hierarchy, instructions nearer the working directory appear later.
Do not use that ordering as a substitute for resolving contradictions. If the global file tells Claude to use one style and the project’s file requires another, both instructions can still be present. Anthropic warns that conflicting instructions may lead to inconsistent choices. Put project-dependent standards in the project file and remove obsolete global assumptions when you find them.
Nested CLAUDE.md files load when Claude reads or edits files in their subdirectories. A repository may therefore bring in additional instructions after work begins. Diagnosing an unexpected behavior requires checking the applicable files, rather than assuming the global file is the only source.
Source: How CLAUDE.md files load.
Imports help organization, but also consume context
Anthropic supports imports using an at-sign followed by a path outside a code block. Imports can organize personal instructions into separate documents, but the imported text still enters context at launch. Splitting a large global file into imported files does not, by itself, reduce context use.
Relative paths resolve from the file containing the import. The documentation also allows absolute paths and nested imports up to four hops. That makes the location of the importing file part of the configuration: moving a file can change what a relative import resolves to.
For a procedure used only occasionally, consider a skill. For instructions tied to a subset of project files, use path-scoped rules. These mechanisms have different loading behavior and can avoid placing every workflow in every session.
Source: Import additional files.
Check which instructions the session loaded
Anthropic documents /context as a way to inspect memory files loaded into a session. Check that list before editing instructions to fix a behavior problem. If the intended file is absent, investigate the location and session configuration. If it is present, look for conflicting instructions and whether its wording states a specific action.
The current docs also describe /doctor prompt-audit for finding outdated or conflicting instructions, with proposed edits that remain unapplied until requested. That command requires Claude Code v2.1.283 or later and depends on the bundled claude-api skill being available.
After changing a global instruction, start a new session to check the intended setup. Evaluate the behavior on an ordinary task and inspect the loaded files. This is a suggested verification procedure; this guide does not claim an independent test of a particular installation.
Sources: Set up and inspect memory files, audit instruction files.
Keep permission controls in their documented settings
CLAUDE.md text is advisory context. A sentence asking the agent to avoid an action does not create a technical prohibition. Anthropic points to a PreToolUse hook when an action must be blocked regardless of the model’s decision.
Use the tool’s documented permission and sandbox controls for access restrictions. Read the Claude Code hooks guide when a workflow requires a deterministic check. Avoid putting credentials or private environment values into a persistent instruction file merely to make them easy for the agent to find.
The global file’s useful job is to carry stable personal context. Keep repository facts near the repository and verify access controls through their own configuration.
