How to Write a Great CLAUDE.md: Best Practices and Tips

When you're writing code with the assistance of a coding agent, there's one thing to always remember: context is key. If an agent/model has a good understanding of your code base, architecture, and other aspects that help it reason, output, and results are improved. Now, of course, you can solely depend on the agent to read through your code base and build up its own understanding, but with large code bases, this is inefficient and on top of that, the underlying LLM is going to have to make some guesses around decisions you made or would make if you wrote the code by hand.

This is where a CLAUDE.md file comes in to help. This file allows you to supply context to the agent in a free-form markdown file that, by default, gets included in every conversation you have with the agent. This means that when you start a new session with the agent, the CLAUDE.md file allows you to inject context by providing any relevant details that will be helpful as the agent assists with code generation. Essentially, it is an onboarding file for the agent. So, should you just do a massive brain dump and push everything into the file so it has everything it could ever need? No, not quite. So, what should you add to this file?

In this blog, I'll share with you many of the CLAUDE.md best practices I've learned for creating and tuning these files over the last year of building Tembo, an autonomous engineering platform that uses agents to augment the productivity of engineering teams. Let's get started by understanding a bit more about the basics of a CLAUDE.md file.

What is a CLAUDE.md file?

A CLAUDE.md file is a markdown-formatted file that lives in the project root of your directory and provides persistent context to Claude Code or other AI coding assistants throughout your development workflow. Think of it as a README file, but instead of being written for human developers joining your team, it's written for your AI pair programmer.

When you're using Claude Code for generating code, the contents of this file are automatically included at the beginning of every conversation. Claude doesn't need to rediscover your project structure, conventions, or constraints every single time you start a new chat. The file typically includes information like your tech stack, architectural decisions, coding conventions specific to your project, known pitfalls to avoid, and any other context that helps Claude generate code that fits seamlessly into your existing codebase.

For example, if your project uses a specific state management pattern or has consistent naming conventions for API endpoints, you'd document that in your CLAUDE.md file. This way, every time Claude generates code, it already knows to follow those patterns without you having to explain them in every single prompt.

What are the benefits of a CLAUDE.md file?

The most immediate benefit is code consistency. When you document your architectural patterns and style guidelines in a CLAUDE.md file, Claude generates code that aligns with your existing codebase from the very first attempt. Instead of generating a React component using class components when your entire codebase uses functional components with hooks, Claude will match your established patterns because you've told it upfront what those patterns are.

Time savings is another major advantage. Without a CLAUDE.md file, you'll find yourself repeating the same context in multiple Claude Code sessions: "Remember, we use Prisma for database access," or "Don't forget we're following the repository pattern for data access." With a properly configured CLAUDE.md file, that context is always present, which means you can get straight to the task at hand instead of providing boilerplate context every time.

You'll also see improved code quality because Claude has a complete picture of your project's constraints and requirements. If your CLAUDE.md file specifies that all database queries should include proper error handling with specific retry logic, Claude will incorporate that pattern automatically. This is especially valuable when working on security-critical feature implementation or when you have performance requirements that need to be consistently applied across your codebase.

Finally, a CLAUDE.md file serves as living documentation of your architectural decisions. As your project evolves and you update the file to reflect new patterns or deprecate old ones, you're maintaining a single source of truth for how code should be written in your project. This has the added benefit of helping human developers, too – your CLAUDE.md file can serve as a quick reference for the team about current best practices.

Are there any negatives to using a CLAUDE.md file?

While a CLAUDE.md file is incredibly valuable, it's not without its downsides. The biggest risk is that a bad CLAUDE.md file can lead to bad output. If your file contains outdated information, contradictory instructions, or guidance that doesn't match your actual codebase, Claude will confidently generate code following those incorrect patterns. If your CLAUDE.md file says to use an old API that you've since deprecated, Claude will keep generating code with that old API, potentially creating technical debt or bugs.

Another challenge is that the instructions can get ignored, particularly as your conversation progresses. This happens because of how context windows work in LLMs. As you have a longer conversation with more back-and-forth messages, your most recent instructions carry more weight than the contents of your CLAUDE.md file. So if you're deep into bug fixes or a debugging session and you give Claude instructions that contradict your CLAUDE.md file, Claude will typically follow your recent instructions. This isn't necessarily bad, but it's something to be aware of – you can't treat the CLAUDE.md file as an unbreakable set of rules.

There's also the maintenance burden to consider. Your CLAUDE.md file needs to stay in sync with your actual codebase as it evolves. If you refactor your authentication system but forget to update the CLAUDE.md file, you'll start getting code suggestions that don't match your new implementation. The CLAUDE.md file is another artifact that needs care and attention during code review and architectural changes.

Tips and Best Practices for Writing a CLAUDE.md File

Although we’ve alluded to some ways to optimize your CLAUDE.md file above, let’s break things down further. Here are five of the most important pieces to remember when creating your CLAUDE.md file:

Don't bloat the file out too much

Even the best frontier models can only reliably follow around 200 distinct instructions. Smaller and older models have an even lower threshold. And as instruction count increases, the model doesn't just struggle with instructions that appear later in the file – it has a harder time following all instructions, even the ones at the beginning.

Think of it like giving someone a massive 50-page manual before they start a task. Even if they read the whole thing, they're unlikely to remember and apply all of it consistently. The same principle applies when you run Claude Code.

So how do you keep your CLAUDE.md file focused? Prioritize information that Claude truly needs for every conversation. Your preferred indent style? That's a job for a linter, not your CLAUDE.md file. Your architectural decision to use microservices with event-driven communication? That absolutely belongs in the file because it affects guiding Claude's approach to designing new features.

A good rule of thumb: if you find your CLAUDE.md file exceeding 500 lines, it's time to refactor it using the progressive disclosure approach I'll talk about next.

Understand how context precedence works

As your conversation with Claude gets further along, your most recent user messages will take precedence over your CLAUDE.md file. This is by design – the model needs to be responsive to your immediate needs and instructions.

Say your CLAUDE.md file specifies that all error handling should use a specific custom error class, but during a debugging session, you tell Claude, "Just throw a standard Error for now so we can test the happy path." Claude will follow your immediate instruction over the CLAUDE.md guidance, which is exactly what you want in that moment.

This can catch you off guard if you're not aware of it. If you're getting code that doesn't match your CLAUDE.md guidelines, check your recent conversation history. You might have inadvertently given Claude instructions that override your documented standards. The solution is to be explicit when you want to deviate temporarily: "For this prototype, ignore the error handling patterns in CLAUDE.md and just use basic try-catch blocks."

Understanding context management is crucial for effective agentic coding workflows.

Use multiple CLAUDE.md files and progressive disclosure

This is one of the most powerful techniques for keeping your relevant context focused and managing context effectively. Try to make your root CLAUDE.md file as universally applicable as possible – think of it as the "always relevant" context. Then, for a specific context that's tied to certain parts of your codebase, use progressive disclosure to keep task-specific context grouped together.

In practice, your root CLAUDE.md file might include:

# Project Context

This is a Node.js microservices application using:

- TypeScript
- PostgreSQL with Prisma ORM
- Redis for caching
- Express for API servers

## Key Directories

- `/src/api` - API endpoints and controllers
- `/src/services` - Business logic layer
- `/src/models` - Database models and schemas
- `/src/middleware` - Auth, validation, and other middleware

## Additional Context Files

For specific components, refer to these context files:

- `.claude/auth-context.md` - Authentication and authorization patterns
- `.claude/database-context.md` - Database schema and query patterns
- `.claude/api-context.md` - API design and endpoint conventions
- `.claude/frontend-context.md` - React component patterns and state management

Before starting work, determine which context files are relevant and read them.

Then in your .claude/auth-context.md file, you'd have detailed information about JWT token structure, refresh token flows, permission checking patterns, and so on. Claude will only load this project-specific context when working on auth-related features, keeping the total instruction count manageable.

An even more sophisticated approach is to list these Claude files with descriptions and instruct Claude to ask you which ones to read, or to present you with its choices for approval before reading them. This gives you explicit control over what context gets loaded for each task. You can even set up custom slash commands in your development workflow to load specific context files on demand.

One important principle mentioned earlier: prefer pointers to copies. Don't include code snippets in these context files if you can avoid it – they become outdated quickly. Instead, use file: line references to point Claude to the authoritative source:

For authentication middleware implementation, see `src/middleware/auth.ts:15-45`
For error handling patterns, reference `src/utils/errors.ts:8-30`

This way, Claude reads the current state of your code rather than stale copies. This approach also helps with version control since your CLAUDE.md files don't need to change every time the core files they reference are updated.

Still use a linter for code style

Don't use your CLAUDE.md file to document code style guidelines and expect Claude to apply them perfectly. This is a common mistake that leads to frustration. Instead, continue using a linter (ESLint, Prettier, Ruff, etc.) and have Claude use the linter output to make corrections as needed.

Code style rules are exactly the kind of numerous, finicky instructions that contribute to that 200-instruction limit I mentioned earlier. If you put "always use single quotes," "add trailing commas in multiline arrays," "use 2 spaces for indentation," and dozens of other style rules in your CLAUDE.md file, you're burning through your instruction budget on things that an automated tool can handle better.

Your workflow should be:

1. Claude generates code
2. Run your linter (or have pre-commit hooks run it automatically)
3. If there are style violations, show Claude the linter output and ask it to fix them

In your CLAUDE.md file, you might include something simple like:

Code style is enforced by ESLint and Prettier. If linter errors are reported,
fix them according to the linter output rather than trying to predict style rules.

This approach has the added benefit of catching style issues that Claude might miss even with detailed instructions. The linter is the source of truth, not the CLAUDE.md file. Some teams even integrate this into their git commit workflow to ensure tests pass and style checks are clean before code gets committed.

Don't auto-generate the file

I've seen teams try to automatically generate their CLAUDE.md files from code comments, Git history, or other sources. While the impulse makes sense, this is one file where you need to be meticulous about both length and content, so rolling the dice on it by generating it is usually not the best move.

Your CLAUDE.md file is one of the most important elements in making sure Claude generates code with the results you expect. An auto-generated file will likely include:

• Too much information (bloating your context window)
• Irrelevant details that don't affect code generation
• Missing context that isn't captured anywhere else in your codebase

Architectural decisions about why you chose a particular pattern often don't appear in code or comments, but are crucial for Claude to know. Similarly, constraints like "we're planning to migrate from REST to GraphQL in Q2, so new endpoints should be designed with that in mind" won't be captured automatically, but are vital project-specific context.

Treat your CLAUDE.md file like you would a critical piece of infrastructure. Review it during code review when architectural changes happen. Update it thoughtfully as your project evolves through pull requests. The effort you put into maintaining a high-quality CLAUDE.md file will pay dividends in better code generation and fewer rounds of revision.

How to Add a CLAUDE.md to your Tembo Project

Adding a CLAUDE.md file to your Tembo project is straightforward. Simply create a file named CLAUDE.md in the project root directory of your repository. Tembo's agent platform will automatically pull this file and include it in every conversation the agent has about your codebase.

If you're using progressive disclosure with multiple context files, create a .claude directory in your project root and place your additional markdown files there. Your main CLAUDE.md file can then reference these supplementary Claude files as needed.

The agent will load the root CLAUDE.md file by default, and based on your instructions, can selectively load additional relevant files from the .claude directory when they're relevant to the task at hand. This keeps your agent context-aware while ensuring it has access to all the information it might need without overloading the context window.

When you run Claude Code through the command line tool (the Claude Code CLI), it will automatically detect and load your CLAUDE.md file. You can also use custom slash commands to load additional context files mid-conversation if you need to bring in specific context for a particular task.

For teams using multiple Claude instances across different parts of a large codebase, having well-organized CLAUDE.md files ensures consistent behavior across all sessions.

Conclusion

A well-crafted CLAUDE.md file makes Claude Code feel less like a tool that's constantly learning about your project and more like a team member who already understands your code structure, style guidelines, and architectural decisions. By providing clear, focused context about your architecture, patterns, and constraints, you enable Claude to generate code that fits seamlessly into your existing codebase from the very first attempt.

Remember the key principles: keep your file focused and under that 200-instruction threshold, use progressive disclosure for specialized context, let automated tools handle what they're good at (like linting), and maintain your CLAUDE.md file as a critical piece of infrastructure rather than treating it as an afterthought.

The upfront investment in creating and maintaining a quality CLAUDE.md file will save you countless hours in your software development workflow – less time correcting misaligned code, re-explaining context, and refactoring generated code to match your standards. Start with the basics – your tech stack, key directories, and major architectural constraints – and evolve the file as you learn what context Claude needs most. This is one of the core best practices for anyone doing serious agentic coding work.

Whether you're using Claude Code from the command line, integrating Claude through an API, or working with a web UI, having comprehensive documentation in your CLAUDE.md file is what separates a frustrating experience from a productive one.

Your CLAUDE.md file is your agent's onboarding document. Make it count.