The CLAUDE.md file

Introduction to CLAUDE.md

One of the most useful parts of Claude is the CLAUDE.md file. It gives Claude persistent memory about your project. When you open up Claude without a CLAUDE.md file, it has to start fresh every single time. It has to re-explore your codebase, understand what dependencies are needed, and identify the features that are already implemented. Sometimes, it has to make assumptions, which makes it harder for us to steer Claude in the right direction.

That’s where CLAUDE.md comes in. It is a Markdown file that you add to the root of your project, and Claude reads it automatically every time you start a session. It acts like an onboarding script for your codebase. Simply put, the contents of the CLAUDE.md file are appended to your own prompt.

Getting Started with the /init Command

You can run the /init command, which will make Claude generate a CLAUDE.md file based on your codebase. Let’s look at an example for a Next.js 15 app using the App Router, Tailwind CSS, and Drizzle ORM. The file might include:

• Commands: Dev server, run tests, lint.
• Code Style: Use two-space indentation, prefer named exports.
• Architecture: All API routes go in app/api, use Server Actions instead of API routes where possible.

It is quite straightforward. Now, if I ask Claude to create a React component, it already knows how to style it with Tailwind or any other CSS framework I am using. Claude does a better job right off the bat versus having to manually understand where everything is first.

Hierarchy of Memory Files

You can share this file in your version control for your team to use, but there is actually a hierarchy of memory files depending on who they are for:

1. Project Level: The CLAUDE.md that lives in the root directory of your project.
2. User Level: A CLAUDE.md file that lives in your configuration folder. This one is just for you and applies across all your projects. You should put your personal preferences here, such as how you prefer to write code comments.

Tips for Effective Context Management

To get the most out of Claude's memory, follow these three tips:

• Explicit Saving: If you have to correct Claude to do something—like always using Server Actions instead of API routes—explicitly ask Claude to save this to memory. This ensures that when you return to the project, it will remember every single time.
• Referencing Documentation: If you have docs in your project that you want Claude to reference, just use the @ symbol with the file path.
• Iterative Refinement: We recommend starting a project without a CLAUDE.md file initially. This allows you to see where you have to constantly course-correct the model. This practice keeps your CLAUDE.md file compact, containing only the necessary information that Claude needs to work effectively.

Conclusion

The difference between a frustrating AI session and a productive one comes down to context. The CLAUDE.md file is how you provide that context. Start with your stack, your preferences, and your commands, and then build from there as you go.