Make Project Context Durable

Some knowledge should affect every task in a repository: the build command, architectural boundaries, naming conventions, and a rule never to publish without approval. Other knowledge matters only when working in a particular directory or performing a specific workflow. Mixing everything into one always-loaded file consumes context and weakens attention to the rules that matter.

Claude Code provides several mechanisms with different loading behavior. CLAUDE.md holds durable instructions that should be present across sessions. `.claude/rules/` can scope guidance to parts of a project. Skills provide reference material or repeatable workflows that load when relevant or invoked. Auto memory records machine-local learnings across sessions. Choose by lifecycle and audience, not by which file you discovered first.

User instructions in `~/.claude/CLAUDE.md` apply across your projects. A repository's `./CLAUDE.md` or `./.claude/CLAUDE.md` is shared through version control and should describe project facts. `CLAUDE.local.md` is for personal project-specific notes and belongs in `.gitignore`. Managed instructions may be supplied by an organization and cannot be treated as editable project content.

Directory hierarchy matters. Instructions above the working directory load at launch, while instructions in child directories can load when Claude enters those parts of the project. This supports monorepos, but it also means two sessions started from different directories may receive different context. Use `/context` when behavior suggests the wrong instructions loaded rather than adding the same rule in several places.

Include facts Claude cannot reliably infer: exact setup and verification commands, unusual architecture decisions, repository etiquette, environment quirks, and safety boundaries. Exclude generic advice, tutorials, file-by-file descriptions, and volatile status. Anthropic's guidance recommends keeping the file concise; the extension overview offers a practical rule of thumb of fewer than 200 lines.

Treat the file like code. When Claude repeats a mistake, first ask whether a precise durable rule would prevent it. Add the smallest useful instruction, observe whether behavior improves, and prune duplicates or stale entries. A long document full of emphatic rules is not stronger; it creates competition for limited context.

CLAUDE.md supports `@path/to/import` references. Use imports to point at authoritative project documents such as a short architecture decision, test runbook, or shared agent instructions. Relative imports resolve from the file containing the import, and external imports require approval. Keep the imported material focused because it joins the session context.

Claude Code reads CLAUDE.md rather than AGENTS.md directly. If a multi-agent repository already uses AGENTS.md, Anthropic documents a simple bridge: create CLAUDE.md and import `@AGENTS.md`, then add only Claude-specific notes below it. This avoids two instruction files drifting apart while preserving tool-specific extensions.

Use `/memory` to inspect instruction and memory locations, and `/context` to see what actually entered the current session. Auto memory is stored locally by project and can record recurring learnings, but it is not a team source of truth and is not automatically shared to another computer or cloud environment. Review it like notes, not policy.

When a rule, skill, hook, or MCP server seems absent, diagnose the effective configuration instead of rewriting it blindly. Anthropic's configuration debugging guide points to `/context`, `/doctor`, `/hooks`, and `/mcp` for different layers. Record where the setting lives, which scope wins, and whether the current session needs to be restarted or reloaded before testing again.