03beginner4 min read min read
Memory & CLAUDE.md
Give Claude persistent knowledge of your project through CLAUDE.md — the project-level memory file that loads automatically every session.
memoryCLAUDE.mdproject-contextteam-workflowsystem-prompt
Give Claude persistent knowledge of your project through CLAUDE.md — the project-level memory file that loads automatically every session.
By default, Claude Code starts each session with no knowledge of your project. It does not know your naming conventions, which files are off-limits, or the business rules baked into your codebase. You would have to explain this every time.
CLAUDE.md solves this. It is a Markdown file that Claude Code reads automatically at startup, every session, before you type anything. Think of it as a permanent system prompt for your project.
Place it in your repository root:
my-project/
CLAUDE.md ← project-level memory
src/
package.json
Claude reads it on launch. No configuration required.
Here is a real-world template:
# Project: Acme Dashboard
## Stack
- Next.js 16 (App Router, TypeScript strict)
- Tailwind CSS v4 — no tailwind.config.js
- Supabase (PostgreSQL, Row-Level Security enabled)
- Deployed on Vercel
## Coding Standards
- Use `const` over `let` wherever possible
- All async functions must handle errors with try/catch
- Never use `any` — prefer `unknown` and narrow types
- Components go in `components/`, one file per component
- Use `yarn`, never `npm`
## Testing
- Unit tests: Vitest
- E2E tests: Playwright in `e2e/`
- Run tests with `yarn test` before committing
## Forbidden Actions
- Do NOT modify `supabase/migrations/` — migrations are immutable
- Do NOT remove `"use client"` directives without asking first
- Do NOT commit `.env` files or secrets
## Architecture Notes
- Auth is handled by Supabase Auth — do not build a custom auth system
- All database queries go through `lib/db.ts` — never import supabase directly in components| Category | Examples | |---|---| | Stack | Framework, database, CSS library, deployment target | | Coding standards | Naming conventions, import order, preferred patterns | | Testing setup | Test runner, how to run tests, coverage requirements | | Forbidden actions | Files not to touch, patterns to avoid | | Architecture notes | Key design decisions, important invariants | | Terminology | Domain-specific words Claude might misunderstand |
When you run claude in a project directory, Claude Code:
CLAUDE.mdYou do not need to reference CLAUDE.md explicitly. It is always loaded.
For preferences that apply to all your projects (not just one), create a user-level CLAUDE.md:
mkdir -p ~/.claude
touch ~/.claude/CLAUDE.md# Global Preferences
- I prefer functional React components over class components
- Always use TypeScript — never plain JavaScript
- My test runner is always Vitest unless specified otherwise
- Prefer explicit return types on exported functionsUser-level memory is merged with project-level memory. Project-level takes precedence on conflicts.
Commit CLAUDE.md to your repository. When teammates clone the project and run claude, they get the same context automatically — no setup required.
git add CLAUDE.md
git commit -m "chore: add CLAUDE.md project memory"This makes CLAUDE.md a living document. When your stack changes or a new architectural decision is made, update it the same way you update a README.
Never put API keys, passwords, or tokens in CLAUDE.md. It is committed to version control and readable by everyone with repo access. Use environment variables for secrets.
If Claude seems to ignore your CLAUDE.md:
# Confirm Claude found it
claude --print "What does my CLAUDE.md say about coding standards?"If the response is empty, check:
CLAUDE.md (case-sensitive)claude from inside the project directory (or a subdirectory)CLAUDE.md is the single most impactful thing you can add to a project for Claude Code productivity. One well-written CLAUDE.md file eliminates dozens of repeated explanations per week. The next module covers Hooks — lifecycle callbacks that let Claude trigger shell commands automatically before and after tool use.