CLAUDE.md
By Mike Schreiber · Updated 31 October 2026
CLAUDE.md
CLAUDE.md is a Markdown instruction file that gives Claude Code persistent guidance about a project, personal workflow, or organization. It captures information that would otherwise need repeating, such as test commands, coding conventions, and architectural constraints. Claude treats its contents as context, not enforced configuration or a saved conversation. [1]
Scope and behavior
Project instructions belong in ./CLAUDE.md or ./.claude/CLAUDE.md and can be shared through version control. Personal defaults belong in ~/.claude/CLAUDE.md; private project preferences can go in CLAUDE.local.md, which should be gitignored. Files above the working directory load at launch, while instructions in subdirectories load on demand. Loaded instructions accumulate rather than reliably overriding conflicting guidance. [1]
Keep instructions concrete, consistent, and preferably under 200 lines. Move narrowly applicable guidance into path-scoped rules and longer procedures into skills. For mandatory restrictions, use permissions or hooks rather than relying on prose. [1]
Practical example
For a JavaScript repository, a small project file might contain:
# Project instructions
- Use pnpm for dependency management.
- Run pnpm test before proposing a commit.
- Ask before adding production dependencies.
- Preserve the public API unless explicitly asked to change it.
Run /init to generate a starting file, review its assumptions, and use /context to confirm it loaded. Add rules based on recurring corrections rather than copying an entire project manual. [1]
Instructions, memory, and project records
CLAUDE.md differs from auto memory, which contains notes Claude writes itself. Neither should be confused with session transcripts: Claude Code stores conversations separately and provides resume and export commands. [1][2]
An MCP memory server is another distinct mechanism: a service exposing stored context through MCP tools or resources. Local servers commonly run on the same machine over stdio; hosted servers run remotely, commonly using Streamable HTTP. Hosting does not itself guarantee shared memory, retention, or transcript portability. Those depend on the server implementation; MCP defines context exchange, not an application's memory policy. [3]
Hark belongs in the project-record category, not universal transcript transfer. Its briefs and handoffs draw from a shared record of inventory, health, work, authority, and decisions. When a linked repository's CLAUDE.md or AGENTS.md is selected as authoritative, Hark mirrors it rather than authoring competing instructions. [4]