Claude Code Memory (CLAUDE.md)

Persist project conventions and session notes with CLAUDE.md memory files.

Claude CodeIntermediate

Why

Stack Overflow's 2025 Developer Survey reports 9.7% of developers use Claude Code, and JetBrains' January 2026 AI Pulse found 18% of professional developers use it at work, up 1.5x since September 2025. CLAUDE.md is auto-loaded into every Claude Code session, so conventions, architecture, and gotchas persist without re-explaining.

This is the equivalent of .cursorrules but for the terminal agent, and it dramatically improves consistency across sessions.

When

Add a CLAUDE.md when you re-explain the same conventions each session, when new teammates use Claude Code, or when output drifts from project patterns. Avoid Claude Code for quick single-line edits where visual diff review matters — use an IDE tool like Cursor instead.

How

1. Create CLAUDE.md in the project root (committed to git). 2. Put the stack, build/test commands, and architecture rules first. 3. Add "do/don't" rules and gotchas the agent keeps getting wrong. 4. Use # to add a memory inline during a session: "# always use zod for validation". 5. Keep it under ~50 lines; move long docs to /docs and reference them. 6. Nest CLAUDE.md in subdirs for directory-scoped rules.

Example

# CLAUDE.md Stack: Astro 7 + React 18 + Tailwind 3, TypeScript strict. Build: npm run build (tsc -b && astro build). Test: npm test (vitest). - Data in src/data/*.ts only; never inline in components. - Named exports; default export only for Astro pages. - Validate all API input with zod. - Don't add new deps without asking. - i18n: 9 locales, en at root.

Common Problems

⚠Error: Cannot find module '@anthropic-ai/claude-code' → run `npm install -g @anthropic-ai/claude-code`; requires Node.js 18+.
⚠"Error: ENOTFOUND api.anthropic.com" → check `echo $ANTHROPIC_API_KEY` is set and network/proxy allows api.anthropic.com:443.
⚠Error: Rate limit: "429 Too Many Requests" → run `/cost` to check usage, `/compact` to shrink context, or wait for quota reset.

Best Practices

✓Lead with build/test commands so the agent can run the gate autonomously.
✓Use inline # memory for one-off gotchas; promote recurring ones to CLAUDE.md.
✓Measure the outcome with a concrete metric (time saved, defect rate, test coverage) so the practice can be justified and improved.

FAQ

What is Claude Code Memory (CLAUDE.md)?

Persist project conventions and session notes with CLAUDE.md memory files. It helps developers quickly grasp the core value and use cases of Claude Code Memory (CLAUDE.md).

How do I get started with Claude Code Memory (CLAUDE.md)?

To get started with Claude Code Memory (CLAUDE.md), focus on these points first: Create CLAUDE.md in the project root (committed to git).

What are common mistakes with Claude Code Memory (CLAUDE.md)?

Common mistakes when using Claude Code Memory (CLAUDE.md) include: Error: Cannot find module '@anthropic-ai/claude-code' → run `npm install -g @anthropic-ai/claude-code`; requires Node.js 18+.; "Error: ENOTFOUND api.anthropic.com" → check `echo $ANTHROPIC_API_KEY` is set and network/proxy allows api.anthropic.com:443.; Error: Rate limit: "429 Too Many Requests" → run `/cost` to check usage, `/compact` to shrink context, or wait for quota reset..

What are the best practices for Claude Code Memory (CLAUDE.md)?

Best practices for Claude Code Memory (CLAUDE.md) include: Lead with build/test commands so the agent can run the gate autonomously.; Use inline # memory for one-off gotchas; promote recurring ones to CLAUDE.md.; Measure the outcome with a concrete metric (time saved, defect rate, test coverage) so the practice can be justified and improved..

How do I learn more about Claude Code Memory (CLAUDE.md)?

Start with the official docs, then search real-world examples on GitHub. Validate patterns in a small scratch repo before applying them to production code.