Stop treating your CLAUDE.md like a

Stop treating your CLAUDE.md like a static readme file; it’s actually the "operating system" for your project's context window.

My team spent the first month with Claude 3.5 Sonnet just treating the project context as a dumping ground. We’d paste the same five boilerplate instructions into every new chat: "use TypeScript," "don't use Tailwind for this specific module," "follow our custom naming convention for hooks." It was a massive waste of tokens and mental energy. Once we started utilizing a .claudemd or CLAUDE.md file in the root directory, the "hallucination rate" regarding our architecture dropped significantly.

The mistake most people make is writing a high-level summary. If you just write "This is a CRM app," Claude already knows that from the code. The file needs to be a set of hard constraints and "gotchas" that aren't immediately obvious from looking at a single file.

We structured ours into three aggressive sections:

The "Never Do This" List
This is the most important part. We explicitly listed patterns that the AI loves to suggest but we hate. For example, we banned the use of useEffect for data fetching in favor of our internal wrapper. When Claude tries to be "helpful" by suggesting a standard React pattern that breaks our architecture, the .claudemd acts as a guardrail.

The Command Cheat Sheet
We put our exact build and test commands in there. Instead of saying "run the tests," we give it the exact string:

npm run test:unit -- --grep "UserAuth"

This stops the back-and-forth where the AI guesses the script name, fails, and then apologizes.

The State of the Union
We use a "Current Focus" section that we update manually. If we're migrating from REST to GraphQL for a specific module, we write: "Currently migrating /api/users to GraphQL; ignore existing REST endpoints in that folder." This prevents the AI from suggesting fixes for deprecated code.

Adoption wasn't seamless. Our lead dev hated it at first because he felt it was "extra documentation" (which is the death knell for most dev docs). He argued that the code should be self-documenting. But the turning point was when he realized he could onboard a junior dev to a complex legacy module in half the time because Claude could actually explain why we did things weirdly, provided the "why" was in the markdown file.

The biggest speed gain isn't in the coding itself, but in the "prompting overhead." I no longer spend three prompts correcting the AI's stylistic choices. I just say "implement X" and it follows the project's DNA because the context is baked into the environment.

If you're still manually typing "use functional components" every time you open a new session, you're treating the tool like a chatbot instead of an integrated agent. Move the constraints into the repo.