What Is CLAUDE.md?
A practical guide to CLAUDE.md in Claude Code: where it loads from, what to include, what to avoid, and how to keep project memory useful.
CLAUDE.md is the durable instruction file Claude Code uses to understand your project. It is where you put the rules you would otherwise repeat in every session: commands, architecture boundaries, coding standards, test expectations, and review habits.
Last checked on May 24, 2026. Claude Code now has several memory and rule surfaces. Use
CLAUDE.mdfor stable project context, not for every random note.
Short Answer
Create a project-level CLAUDE.md when you want Claude Code to behave consistently across sessions. Keep it practical, current, and short enough that it improves context instead of flooding it.
Where Claude Loads Instructions
| Level | Typical location | Use it for | Who sees it |
|---|---|---|---|
| User instructions | ~/.claude/CLAUDE.md | Personal preferences across all projects. | You. |
| Project instructions | ./CLAUDE.md or ./.claude/CLAUDE.md | Shared project rules, commands, architecture notes. | Team members if committed. |
| Local instructions | ./CLAUDE.local.md | Personal project notes, sandbox URLs, local test data. | You; usually gitignored. |
| Rules | .claude/rules/*.md | Topic-specific or file-scoped rules. | Depends on repository policy. |
Claude Code loads relevant instruction files from the working directory hierarchy. Keep the most specific rule closest to the project area it describes.
What to Include
# Project overview
- Main app: Next.js app in `src/app`.
- Content pages: MDX under `content/pages`.
# Commands
- Build: `pnpm build`
- Lint: `pnpm lint`
- Local preview: use the project preview script or standalone server setup.
# Rules
- Preserve existing SEO URLs unless explicitly migrating them.
- Use existing template blocks before adding new custom components.
- Run a build before considering a content migration done.
# Review checklist
- Check links.
- Check dark mode.
- Check mobile layout.What to Avoid
- Long historical notes that no longer affect current work.
- Vague instructions such as "make it better".
- Secrets, API keys, private customer data, or credentials.
- Conflicting instructions between user, project, and local memory.
- Huge pasted docs that should be linked or stored as separate reference files.
Maintenance Rule
Update CLAUDE.md after repeated corrections, not after every one-off mistake. If you had to correct Claude twice about the same project rule, write the rule down. Every few weeks, remove stale sections.