Add Persistent Project Context to Claude Code
Claude Code can remember details about your project across sessions if you set up persistent context files. This guide shows you how to create and use those files so you don’t have to re-explain your project every time you start a new session.
What You’ll Need
- Claude Code installed and logged in (CLI tool from Anthropic).
- A terminal or command prompt.
- Basic familiarity with your project’s file structure.
Step-by-Step
- Create a CLAUDE.md file in your project’s root directory. This is the main file Claude Code reads automatically at the start of every session. Use a text editor to create it.
- Add project overview: Write a concise paragraph describing what your project does, its architecture, and key technologies. For example: “This is a React frontend with a Node.js backend, using PostgreSQL. The frontend is in
src/, backend inserver/.” - Document conventions: List coding style rules, naming conventions, and any specific patterns you use. For instance: “Use functional components with hooks, never class components. Prefer named exports.”
- Include build and test commands: Write the exact commands to install dependencies, run tests, and build the project. Example: “
npm install,npm test,npm run build.” - Add common pitfalls: Note any known issues or things to avoid. For example: “Do not modify the
dist/folder; it’s generated by the build.” - Save and test: Save the file. Start a new Claude Code session in the project directory and ask a question like “What does this project do?” to verify it reads the context.
- Use subdirectory CLAUDE.md files (optional): Place additional CLAUDE.md files in subdirectories for module-specific context. Claude Code reads the root file and then the closest one to the current file.
- Update regularly: Keep the file current as your project evolves. Review it every few weeks or when major changes happen.
Common Mistakes
- Too much detail: Writing a 10-page document defeats the purpose. Keep it concise and focused on what Claude needs to know.
- Outdated info: Forgetting to update the file when you change commands or structure leads to confusion.
- Ignoring subdirectory files: Not using them when you have a large monorepo means Claude may miss module-specific context.
- Putting secrets in the file: Never include API keys or passwords in CLAUDE.md, as it may be committed to version control.
- Not testing: Assuming it works without verifying. Always test with a new session.
Tips
- Use markdown formatting: Claude Code supports markdown, so use headings, bullet points, and code blocks for readability.
- Include examples: Show a sample file structure or a code snippet to illustrate conventions.
- Be specific: Instead of “use modern JS,” say “use ES6+ syntax, avoid var.”
- Leverage the @import feature: You can import other files into CLAUDE.md using
@path/to/fileto keep it modular. - Check the official docs: Anthropic’s documentation on memory and context is a good reference for advanced features.
Troubleshooting
- Claude doesn’t seem to read the file: Ensure the file is named exactly
CLAUDE.md(case-sensitive) and is in the project root. Also, make sure you’re running Claude Code from that directory or a subdirectory. - Context is not applied to a specific file: If you have subdirectory CLAUDE.md files, check that the file you’re working on is under that subdirectory. Otherwise, move the relevant context to the root file.
- Changes not taking effect: Claude Code reads the file at session start. If you edit it mid-session, restart the session or use the
/memorycommand to refresh. - File is too large: If Claude seems to ignore parts, try breaking it into smaller files and using
@importto include them. - Formatting issues: If Claude doesn’t understand the structure, simplify. Use plain text with simple bullets instead of complex tables.
Frequently Asked Questions
Can I have multiple CLAUDE.md files in one project?
Yes, you can have a root CLAUDE.md and additional ones in subdirectories. Claude Code reads the root file first, then the closest subdirectory file to the file you’re working on.
Does CLAUDE.md work with any project type?
Yes, it’s language-agnostic. You can use it for Python, JavaScript, Ruby, or any other language. The content should be tailored to your project’s needs.
How often should I update CLAUDE.md?
Update it whenever significant changes occur: new dependencies, changed commands, or architectural shifts. A good rule is to review it monthly or when you notice Claude giving outdated advice.
Can I include environment variables in CLAUDE.md?
You can mention them, but never put actual secret values. Instead, note which variables are required and where they’re defined (e.g., in .env.example).
What if Claude Code still doesn’t remember after adding the file?
Check that the file is in the correct location and that you’ve restarted the session. Also, ensure you’re using a recent version of Claude Code, as memory features are actively developed.
Is there a way to see what context Claude is using?
Yes, you can ask Claude to summarize the project context it has, or use the /memory command in the CLI to view and manage memory.
Related
Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.