Every time you start a new chat session with Claude Code, it’s starting from zero knowledge about your project. It doesn’t know your tech stack, your conventions, or where anything lives. A well-written CLAUDE.md file fixes that by giving Claude the context it needs before it writes a single line of code.

This is context engineering, and your CLAUDE.md file is one of the most important pieces of it.

Why It Matters

Without a context file, Claude has to discover basic information about your project — what language you’re using, how the CLI works, where tests live, what your preferred patterns are. That discovery process burns tokens and time. A good CLAUDE.md front-loads that knowledge so Claude can get to work immediately.

If you haven’t created one yet, you can generate a starter file with the /init command. Claude will analyze your project and produce a reasonable first draft. It’s a solid starting point, but you’ll want to refine it over time.

The File Naming Problem

If you’re working on a team where people use different tools: Cursor has its own context file, OpenAI has theirs, and Google has theirs. You can easily end up with three separate context files that all contain slightly different information about the same project. That’s a maintenance headache.

It would be nice if Anthropic made the filename a configuration setting in settings.json, but as of now they don’t. Some tools like Cursor do let you configure the default context file, so it’s worth checking.

My recommendation? Look at what tools people on your team are actually using and try to standardize on one file, maybe two. I’ve had good success with the symlink approach , where you pick your primary file and symlink the others to it. So if CLAUDE.md is your default, you can symlink AGENTS.md or GEMINI.md to point at the same file.

It’s not perfect, but it beats maintaining three separate files with diverging information.

Keep It Short

Brevity is crucial. Your context file gets loaded into the context window every single session, so every line costs tokens. Eliminate unnecessary adjectives and adverbs. Cut the fluff.

A general rule of thumb that Anthropic recommends is to keep your CLAUDE.md under 200 lines. If you’re over that, it’s time to trim.

I recently went through this exercise myself. I had a bunch of Python CLI commands documented in my context file, but most of them I rarely needed Claude to know about.

We don’t need to list every single possible command in the context file. That information is better off in a docs/ folder or your project’s documentation. Just add a line in your CLAUDE.md pointing to where that reference lives, so Claude knows where to look when it needs it.

Maintain It Regularly

A context file isn’t something you write once and forget about. Review it periodically. As your project evolves, sections become outdated or irrelevant. Remove them. If a section is only useful for a specific type of task, consider moving it out of the main file entirely.

The goal is to keep only the information that’s frequently relevant. Everything else should live somewhere Claude can find it on demand, not somewhere it has to read every single time.

Where to Put It

Something that’s easy to miss: you can put your project-level CLAUDE.md in two places.

• ./CLAUDE.md (project root)
• ./.claude/CLAUDE.md (inside the .claude directory)

A common pattern is to .gitignore the .claude/ folder. So if you don’t want to check in the context file — maybe it contains personal preferences or local paths — putting it in .claude/ is a good option.

Rules Files for Large Projects

If your context file is getting too large and you genuinely can’t cut more, you have another option: rules files. These go in the .claude/rules/ directory and act as supplemental context that gets loaded on demand rather than every session.

You might have one rule file for style guidelines, another for testing conventions, and another for security requirements. This way, Claude gets the detailed context when it’s relevant without bloating the main file.

Auto Memory: The Alternative Approach

Something you might not be aware of is that Claude Code now has auto memory, where it automatically writes and maintains its own memory files. If you’re using Claude Code frequently and don’t want to manually maintain a context file, auto memory can be a good option.

The key thing to know is that you should generally use one approach or the other. If you’re relying on auto memory, delete the CLAUDE.md file, and vice versa.

Auto memory is something I’ll cover in more detail in another post, but it’s worth knowing the feature exists. Just make sure you enable it in your settings.json if you want to try it.

Quick Checklist

If you’re writing or revising your CLAUDE.md right now, here’s what I’d focus on:

• Keep it under 200 lines — move detailed references to docs
• Include your core conventions — package manager, runtime, testing approach
• Document key architecture — how the project is structured, where things live
• Add your preferences — things Claude should always or never do
• Review monthly — cut what’s no longer relevant
• Consider symlinks — if your team uses multiple AI tools
• Use rules files — for detailed, task-specific context

That’s All For Now. 👋