Global vs project CLAUDE.md

Every session starts blank. Claude does not remember what you told it last week, does not know your conventions, does not know which tools are available on your machine, does not know which repos it should not search. Without anything in place, every session is a cold start where you spend the first few minutes re-orienting before you can get to the actual work.

Persistent context is the collection of mechanisms that fix this. They are loaded automatically before every session, without you invoking anything, so the work of orienting Claude is done before you type your first message.

The Three Mechanisms

Global CLAUDE.md

Path: ~/.claude/CLAUDE.md

Loaded into every Claude Code session you start, on any project. This is the right place for things that are always true regardless of what you are working on: your environment, your preferences, your writing style, tools you always have available, rules that apply machine-wide.

Concrete examples of what belongs here:

• Environment quirks: if you are on WSL, the .exe suffix requirement for Windows tools (git.exe, dotnet.exe), path translation for cross-filesystem operations, which package manager to use
• Writing conventions: rules like “never use em dashes,” “direct and concise,” tense and voice preferences for commit messages and PR descriptions
• Commit and PR format: how commit messages should be structured, what goes in a PR body, label requirements, whether to include AI attribution (the answer for us is never)
• Security defaults: which tools need explicit approval, which operations require confirmation before running
• CLI preferences: rg over grep, which databases to default to, environment flags
• What not to do: overly broad searches, committing without asking, destructive git operations

The global file is personal, not shared. It reflects how you specifically work, on your specific machine.

Project CLAUDE.md

Path: {project-root}/CLAUDE.md

Loaded when you open a session in that project. Can reference other files using @path syntax, which causes the referenced file to be loaded inline. Our planning repo uses this to pull in planning/AGENTS.md:

@planning/AGENTS.md

Beyond that import, the project CLAUDE.md is specifically for Claude Code-specific configuration. This is the distinction that matters: AGENTS.md is generic project guidance that any AI system could benefit from. The project CLAUDE.md is Claude Code behavior: things that are specific to how Claude Code itself should operate in this project and that would not belong in a general-purpose agent guide.

What belongs here:

• Which skills to invoke and when: if the project has a preferred entry point for certain workflows, document it here so Claude routes to the right skill automatically
• Agent team behavior: how teammates communicate with the lead, the push and PR gate rule, when to shut down vs hold
• Hook-adjacent rules: behaviors that complement your hooks but do not require hard enforcement, such as documentation maintenance triggers (run /update-docs before committing when you rename an agent)
• Claude Code-specific paths and conventions: where session state files live, where .context/ is used, which settings files to modify for permissions
• Permission and autonomy defaults: how much latitude Claude has to act without asking, under what conditions to stop and confirm

AGENTS.md

Path: {project-root}/AGENTS.md or planning/AGENTS.md

Same loading behavior as project CLAUDE.md, but typically used to separate agent-specific guidance from general developer guidance. In our planning repo, AGENTS.md carries the full planning methodology: how to decompose features, how to run interrogation, quality standards, story templates, rule file index. It is long and dense and only relevant to the agents doing planning work.

Splitting it out keeps CLAUDE.md readable for humans while still ensuring agents get the full methodology loaded.

Memory System

Path: ~/.claude/projects/{project-hash}/memory/

The memory system is different from the two CLAUDE.md files in two important ways: it is written by Claude, not you, and it is organized into discrete topic files rather than a single document.

When Claude learns something worth retaining across sessions, it writes a memory file. Categories:

• User: who you are, your role, your level of familiarity with specific areas, how you prefer to collaborate
• Feedback: guidance you have given about what to avoid or keep doing, corrections, confirmed approaches
• Project: ongoing work, decisions made, active initiatives, context behind current tasks
• Reference: pointers to external systems, where things live, which channels to watch

The files are indexed in a MEMORY.md file that gets loaded first. Claude reads the index, determines which memory files are relevant to the current session, and loads them. You can ask Claude to remember things explicitly (“remember that we pin FluentAssertions at 7.x, not 8.x”) and it will write the appropriate memory file. You can also ask it to forget things.

The practical value: feedback you give once about how Claude should behave gets written to memory and applied in every future session automatically. You stop repeating yourself.

What Goes Where

The question comes up constantly when setting up a project. The deciding factor is scope and who it applies to.

The test for whether something belongs in CLAUDE.md vs a hook: if you are okay with Claude occasionally forgetting it or applying it inconsistently, it can live in CLAUDE.md. If it must hold every single time with no exceptions, it belongs in a hook.

Structuring Your Global CLAUDE.md

A useful pattern is to organize by category with clear headers so Claude can parse it quickly. Our global CLAUDE.md sections:

• Interaction Protocol: how to handle questions vs directives, when to ask vs act, commit and push gate rules
• Local-First Operations: prefer shell commands over model-mediated reads, which tools to use for which operations
• Environment specifics: WSL conventions, path translations, .exe suffixes
• Language/framework conventions: C# patterns, test conventions, async rules
• Commit format: when to prefix with work item number, when to omit
• Writing style: tone, what not to say, voice reference examples
• Pull request conventions: title format, body format, label requirements
• External system access: database defaults, which MCP tools to prefer

Keep each rule short. A rule that takes three paragraphs to explain is probably two rules, or a rule that should live in a more specific location.

Seeding the Memory System

The memory system builds up naturally as you work. Every time you correct Claude, express a preference, or confirm an approach, it is a candidate for a memory write. You can accelerate the process by being explicit:

• “Remember that we always use az boards over the ADO MCP for work item queries because it is faster and uses less context.”
• “Remember that in this repo, the test project for each service is named {ServiceName}.Tests, not a shared test project.”
• “Remember that I prefer not to see summaries of what was just done, just the result.”

Each of those becomes a memory file in the appropriate category. Future sessions start with those preferences loaded.

What not to put in memory: things that are already in CLAUDE.md (duplication), file contents or code snippets (stale immediately), debugging solutions or fix recipes (the fix is in the code, the context is in the commit message), anything you can derive by reading the current repo state.

The Compound Effect

The full picture of a well-configured session:

1. You open Claude Code in your project directory.
2. Your global CLAUDE.md loads: environment, writing style, commit format, prohibitions.
3. The project CLAUDE.md loads: team conventions, agent catalog, output locations.
4. AGENTS.md loads if referenced: planning methodology, quality standards.
5. The memory index loads: Claude reads which memory files are relevant and loads them.
6. Any registered hooks arm silently in the background.

Before you type a single character, Claude knows your environment, your conventions, what is currently being worked on, feedback you have given, which tools to prefer, and what to never do. The first message you send goes directly to the work.

That is the payoff. Each individual mechanism adds a small amount of load time and a small amount of context. Together they eliminate the orientation tax that otherwise accumulates across every session.

The next guide in this series covers putting the full system together: a worked example of a team adopting these tools in sequence, starting from nothing and ending with a workflow where Claude is genuinely an amplifier rather than a tool you manage.