How to Write Better CLAUDE.md Files

Most CLAUDE.md files fail for a boring reason: they try to be a wiki, a policy handbook, and a scratchpad at the same time.

If you want Claude Code to act like a useful project collaborator, not an overconfident intern, you need context engineering, not prompt stuffing.

Key Takeaways

• A strong CLAUDE.md is short, stable, and opinionated.
• Research suggests bloated repository context files raise cost and can reduce task success, so less is often more [1].
• Claude Code uses a hierarchy of memory files, and CLAUDE.md acts as guidance, not absolute enforcement [2].
• The best files define rules, workflows, and boundaries, then link out to deeper docs.
• Local CLAUDE.md files for risky subdirectories are often smarter than one giant root file [2][3].

---

What makes a CLAUDE.md file actually work?

A CLAUDE.md file works when it gives Claude only the persistent context it needs to make better decisions across sessions, without overwhelming the context window. The sweet spot is concise guidance: architecture, rules, and workflow defaults, not a giant dump of everything you know about the repo [1][2].

Here's the thing I keep noticing: developers often confuse "more context" with "better context." They are not the same. The ETH Zurich paper on repository-level context files found that context files often increase cost by over 20% and can even reduce success rates when they add unnecessary requirements [1]. That's a brutal result, but it matches reality. A noisy file makes the model work harder, not smarter.

The source-level analysis of Claude Code explains why. CLAUDE.md is loaded as part of user context, and Claude Code also uses a hierarchy of memory files, including project and local variants [2]. That means your file matters, but it competes for attention with the rest of the conversation and loaded context. You cannot treat it like a magic system prompt.

So my rule is simple: put only the things Claude should remember every single time.

What should you put in a root CLAUDE.md?

A root CLAUDE.md should define project identity, non-negotiable engineering rules, and the default workflow Claude should follow before making changes. It should not duplicate your README, API docs, or every implementation detail already available elsewhere [1][2].

The most useful root file usually covers three ideas.

First, tell Claude what this project is and how to think about it. One or two paragraphs is enough. State the stack, the product purpose, and the architectural shape.

Second, define the hard rules. These are the things you do not want to repeat in chat: test commands, linting requirements, migration rules, security boundaries, commit expectations, and forbidden shortcuts.

Third, define the working style. Should Claude make a plan first for larger changes? Should it prefer small diffs? Should it read the relevant module docs before editing? Put that here.

A bad version looks like this:

# CLAUDE.md
This is our platform. It has many services. Please be careful.
Use best practices. Write clean code. Think step by step.
See docs for more.

A better version looks like this:

# CLAUDE.md

## Project
B2B SaaS app for invoice automation.
Stack: Next.js, TypeScript, Postgres, Prisma, BullMQ.
Primary architecture: API routes -> service layer -> Prisma models.

## Non-negotiables
- Run `pnpm test` for touched packages before finishing.
- Run `pnpm lint` and fix issues, do not ignore warnings.
- Never change Prisma schema without generating a migration.
- Do not introduce new dependencies without explicit justification.
- Prefer editing existing patterns over creating new abstractions.

## Workflow
- For changes touching 3+ files, propose a short plan first.
- Read nearby module docs before editing payment, auth, or queue code.
- Keep diffs small and reversible.
- If uncertain, surface assumptions instead of guessing.

That is enough. Clear beats comprehensive.

---

Why should CLAUDE.md stay short?

CLAUDE.md should stay short because repository context files become counterproductive when they add too many instructions, too much redundancy, or too much generic guidance. Concise files help the model focus on the few constraints that truly matter on every task [1][2].

The research result here is worth repeating. Developer-written context files gave only marginal gains on average, while LLM-generated ones often hurt performance [1]. The common failure mode was not that models ignored instructions. It was the opposite: they followed them, explored more, ran more tools, spent more tokens, and still did not solve tasks better.

That's why I think "signal density" is the right frame. Every line in CLAUDE.md should earn its place.

The community examples echo this. Developers who get good results often keep the file focused on a handful of rules and workflows, not hundreds of lines of prose [3]. In practice, that usually means you should remove:

• broad advice like "write clean code"
• duplicated docs
• temporary sprint context
• task-specific notes
• explanations of obvious folder names

If a fact is discoverable in seconds from the codebase, it probably does not belong in root memory.

How should you structure CLAUDE.md for code projects?

The best structure for a CLAUDE.md file is a small, predictable layout that separates project context, rules, and workflow. This mirrors how Claude Code itself organizes memory and helps the model retrieve the right kind of guidance quickly [2][3].

I like this pattern:

Section	Purpose	Keep it short?
Project	What the repo does, stack, architecture	Yes
Rules	Non-negotiable constraints and standards	Yes
Workflow	How Claude should approach tasks	Yes
References	Links to docs or module-specific files	Yes

That's it. Four sections. No manifesto.

If your repo is complex, don't keep expanding the root file forever. Split context by location. The Claude Code architecture paper describes directory-aware loading and local memory files with higher priority closer to the working directory [2]. That supports a better pattern: keep the root file minimal, then add local CLAUDE.md files for dangerous or nuanced areas like auth/, billing/, or infra/.

The Analytics Vidhya example makes the same practical point: use root memory for the global picture and local files for "danger zones" where subtle mistakes matter more [3]. That approach is much closer to real context engineering than writing one giant prompt blob.

What does a before-and-after CLAUDE.md rewrite look like?

A useful rewrite removes vague reminders and replaces them with durable constraints, explicit workflows, and pointers to deeper docs. Good CLAUDE.md files sound more like operating instructions than motivational advice [1][2].

Here's a real pattern I'd use.

Before

# CLAUDE.md

We use TypeScript and care about quality.
Please always test your code and avoid bugs.
This app handles payments, auth, analytics, admin, exports, emails, webhooks, and more.
Check the docs folder for details.
Be careful with sensitive code.

After

# CLAUDE.md

## Project
Multi-tenant SaaS for subscription billing and reporting.
Stack: TypeScript, Fastify, Postgres, Drizzle, Redis.
Critical domains: auth, billing, webhooks.

## Rules
- Run `pnpm test` for touched workspaces.
- For billing or webhook changes, run integration tests.
- Never change public API response shapes without updating contract tests.
- Do not log secrets, tokens, or raw webhook payloads in production code.

## Workflow
- For critical-domain edits, inspect existing tests first.
- Propose a brief plan before edits spanning multiple modules.
- Prefer existing service patterns over introducing new layers.

## References
- `docs/architecture.md`
- `apps/api/src/billing/CLAUDE.md`
- `apps/api/src/auth/CLAUDE.md`

That rewrite is sharper, safer, and cheaper.

---

How can you maintain CLAUDE.md without turning it into junk?

You should maintain CLAUDE.md like a config file, not a diary. Update it when project-wide rules change, when the architecture shifts, or when repeated mistakes reveal missing guidance, but not for every temporary task or one-off decision [1][2].

This is where tools like Rephrase can help upstream. If you're constantly rewriting ad hoc coding prompts, that's usually a sign your standing project context is weak. The prompt should vary per task. The CLAUDE.md should not.

My maintenance rule is simple: if you've had to repeat the same correction to Claude three times, promote it into durable context. If it only matters this week, keep it in chat or in the issue.

And if you want more practical prompting breakdowns for coding workflows, the Rephrase blog has more articles on prompt structure, context, and AI tooling.

A good CLAUDE.md doesn't try to control everything. It shapes defaults. That's the whole game.

---

References

Documentation & Research

1. Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? - The Prompt Report (link)
2. Dive into Claude Code: The Design Space of Today's and Future AI Agent Systems - arXiv cs.LG (link)

Community Examples 3. How to Structure a Claude Code Project that Thinks Like an Engineer - Analytics Vidhya (link) 4. Stop writing repetitive prompts. Use a CLAUDE.md file instead (Harness Engineering) - r/PromptEngineering (link)