Put team instructions where everyone receives them

Learning objective

Map user ~/.claude/CLAUDE.md, project CLAUDE.md or .claude/CLAUDE.md, and directory-level instruction scopes; diagnose missing team rules stored only in personal configuration.

Core idea

Choose an instruction file by its audience and when its contents must enter context. A convention in your home directory can shape every project you open without reaching anyone who clones the repository. A committed project instruction reaches the team; a nested instruction reaches sessions working in that part of the tree.

Claude Code reads these Markdown files as guidance. Their contents accumulate in context rather than behave like settings with a winner at each scope. Locating a rule correctly makes it available, but neither its location nor emphatic wording guarantees compliance. Diagnose delivery before rewriting the rule, and use a hook when an operation must run at a defined event.

How it works

Match the location to the audience

The documented instruction locations separate personal preferences from shared conventions:

The dot directory in .claude/CLAUDE.md does not make that file personal. It is an alternative location for project instructions. Commit it if the team should receive it. Conversely, CLAUDE.local.md is a personal project file even though it lives beside the shared code. Add it to .gitignore so it is not committed; do not assume its filename alone prevents sharing.

A gitignored CLAUDE.local.md exists only in the worktree where you created it. It is not a reliable delivery mechanism for another worktree or teammate. For a personal convention that should apply across projects, use the user-level file. For a convention that everyone needs, use the shared project file rather than telling teammates to copy your local notes.

Organizations can also deploy managed instructions. The documented locations are /Library/Application Support/ClaudeCode/CLAUDE.md on macOS, /etc/claude-code/CLAUDE.md on Linux and WSL, and C:\Program Files\ClaudeCode\CLAUDE.md on Windows. Individual settings cannot exclude this managed file. Its organizational distribution distinguishes it from a developer’s home file.

Separate startup loading from directory loading

Claude Code loads CLAUDE.md and CLAUDE.local.md in the working directory and its ancestors at launch. If you start in packages/api/, the repository’s root instructions and the API directory’s instructions enter context immediately. If you start at the root, the nested API file loads when Claude reads, writes, or edits another file in its directory.

The launch directory therefore changes which instructions are present before the first task. A database rule placed in packages/api/src/db/CLAUDE.md can be absent from an API session until Claude accesses that subtree. This is appropriate for database-only guidance. It is the wrong location for a rule every API task needs before examining files.

Across the directory hierarchy, files are concatenated from the filesystem root toward the working directory. Within a directory, CLAUDE.local.md is appended after CLAUDE.md. Reading an instruction later does not cancel conflicting text read earlier: Anthropic warns that Claude might follow either conflicting instruction. Keep shared and personal files consistent rather than treating the nested file as an override.

Use execution mechanisms for mandatory actions

A line such as “format every edited file” in CLAUDE.md asks Claude to remember a convention. A Claude Code command hook runs a script at a lifecycle event. For a shared formatter, configure the hooks key in .claude/settings.json, select PostToolUse, and use matcher: "Edit|Write" with an inner hook whose type is "command" and whose command runs the formatter. The hook input includes tool_input.file_path for these file tools.

PostToolUse runs after a successful tool call. An Edit|Write matcher covers those tools, not a Bash command or an external process that rewrites the same file. It also cannot prevent the completed edit. The convention’s prose explains the expected style; the configured script performs the formatting on the selected event. This is Claude Code configuration, distinct from the Agent SDK policy hooks in 1.5.1 and 1.5.3.

Key distinctions and trade-offs

User scope versus project-local scope: Both are personal, but ~/.claude/CLAUDE.md spans projects while CLAUDE.local.md supplies notes for one project. Neither replaces a committed team instruction.

Root versus nested scope: Root instructions are available from the start of a root session. Nested files defer package details until the session accesses that area, avoiding unrelated guidance. Put a prerequisite higher than the work it governs.

Instruction hierarchy versus enforcement: The hierarchy determines delivery and context order. A settings-based hook determines when a script executes. Moving prose into a more specific file does not turn it into a deterministic gate.

Keeping everything at the root improves initial availability but loads package conventions into unrelated work. Keeping everything deeply nested can delay instructions a task needs immediately. Choose the smallest scope that still makes the rule available before the relevant decision.

Architecture / decision scenario

A developer-productivity team uses Claude Code in a repository containing API and web packages. The lead’s sessions use the correct test command, but a new teammate’s sessions choose a different runner. The repository root has no test instruction; the command exists only in the lead’s ~/.claude/CLAUDE.md.

Move the shared test command into a committed root CLAUDE.md or .claude/CLAUDE.md. Keep the lead’s personal response preference in the home file. Store a private sandbox URL in root CLAUDE.local.md and ignore that file. Put API-only error conventions in packages/api/CLAUDE.md, accepting that a root session receives them when it accesses API files.

The team also requires formatting after Claude’s file-tool edits. Configure hooks.PostToolUse in shared .claude/settings.json with the Edit|Write matcher and a command hook for the project formatter. Do not claim that this matcher covers every possible disk change. Check loaded launch instructions with /context and use /memory to edit the misplaced rule; 3.1.4 owns that diagnostic workflow.

Common exam traps

• Treating a successful session on one laptop as proof that the repository distributes its rules.
• Assuming .claude/CLAUDE.md is private because it lives in a dot directory.
• Putting team standards in CLAUDE.local.md and expecting a clone to receive them.
• Expecting nested instructions to be present at the start of every root session.
• Assuming a more specific instruction overrides contradictory text higher in the tree.
• Equating a formatting instruction with a configured formatter hook.

What to remember

Choose the file by audience, then check when it loads. User instructions are personal across projects; local instructions are personal within a project; committed project and nested files carry team guidance. Context order does not resolve contradictions. Use the hooks settings key and an appropriate lifecycle event when the requirement is to execute a script rather than deliver advice.

Knowledge check

References

• Anthropic, How Claude remembers your project
• Anthropic, Settings files and precedence
• Anthropic, Automate actions with hooks
• Anthropic, Hooks reference