The Ultimate CLAUDE.md Design | 7 Principles That Work for AI and the Bloat Trap

1. The "Ultimate CLAUDE.md" Is Defined by Signal Density, Not Volume

CLAUDE.md is a special file that Claude Code automatically reads every time a conversation begins. It serves as a persistent foundation of prerequisite knowledge — holding project-specific rules in a form that cannot be inferred from the code itself.

This is where many people go wrong. They assume that writing more will make Claude behave more intelligently. In practice, the opposite is true. The Claude Code official best practices explicitly warn that "bloated CLAUDE.md files cause Claude to ignore your actual instructions."

In other words, the ultimate CLAUDE.md is not a long file — it is a file with high signal density. Remove lines that become noise; keep only the lines that work. The official recommended test is simple: ask of each line, "Would removing this cause Claude to make a mistake?" If not, delete it. Everything that follows builds on this single axis across 7 principles.

2. Principle 1: Keep It Under 200–300 Lines and Audit Every Line for Deletability

CLAUDE.md is loaded in every session. That means it consumes tokens every time, steadily compressing Claude's context window. As the official documentation emphasizes, the more the context fills up, the more Claude's performance degrades and it begins to "forget" instructions from earlier in the file. A long CLAUDE.md can itself be the cause of performance degradation.

A Zenn article on best practices for Claude Code recommends keeping the file to "under 300 lines" and "around 150–200 instructions" as a rough guideline. This upper limit reflects the practical ceiling of rules an LLM can handle reliably in a single pass.

The key to controlling line count lies not in being cautious about additions but in being bold about deletions. Every time you notice a new trap, you add a line — and the file inevitably grows. Make it a habit to review every line once a month and mechanically prune any line that does not satisfy "Would removing this cause Claude to make a mistake?" That one habit alone is enough to maintain density.

3. Principle 2: Leave Code Style to the Linter, and Write Only Project-Specific Knowledge

The most wasteful thing to put in CLAUDE.md is style conventions — indentation width, quote style, import ordering. These are far better enforced mechanically by a linter or formatter than by asking an AI. Requests to an AI are probabilistic; a formatter is deterministic.

So what should go in CLAUDE.md? The official documentation draws a clear contrast between what to include and what to exclude.

The single deciding question is: "Can Claude not infer this by reading the code?" Hand off everything that can be inferred to the linter and the code itself, and leave only project-specific knowledge in CLAUDE.md.

4. Principle 3: Write Non-Negotiable Constraints with IMPORTANT / YOU MUST

Not all rules in CLAUDE.md are read with equal weight. For constraints that must absolutely be followed, you can boost compliance by adding emphasis. The official documentation explicitly states that "adding emphasis keywords like IMPORTANT or YOU MUST can improve adherence."

For example, constraints where a violation would cause a real incident — such as "never load production .env" or "do not modify anything under legacy/" — should be written not just plainly, but with an emphasis keyword. In a real CLAUDE.md, this might look like the following short section:

## Mandatory Rules

- IMPORTANT: Never load production `.env` or anything under `secrets/`.
- YOU MUST: Always run schema changes through `npm run db:migrate`. Do not ALTER directly with handwritten SQL.
- `legacy/` is maintained by a separate team. Do not modify it without confirming with the owner first.

By writing these as a standalone emphasized line rather than burying them among ordinary rules, compliance remains high even as the context window fills up.

One caveat: CLAUDE.md is advisory, not a 100% guarantee. For processes that must run without exception every time, the right answer is to put them in a Hook rather than CLAUDE.md. As the official documentation notes, Hooks operate deterministically and guarantee that an action will occur. Think of emphasis keywords as a way to raise compliance rates, not an absolute guarantee.

5. Principle 4: The Highest ROI Is the "Gotchas" Section

The single most cost-effective line in a CLAUDE.md is one that documents a project-specific trap that cannot possibly be discovered by reading the code. The official list of things to include explicitly mentions "Common gotchas or non-obvious behaviors."

For example, the following kinds of information appear nowhere in the repository, and if the AI stumbles into them, an incident is almost guaranteed.

• This service works locally, but will always fail in CI without a specific env var
• This module looks usable but is managed by another team, and touching it will break things
• This function calls foo() for historical reasons, and must not be changed to bar()

A Gotchas section that collects this "highest signal density information" can dramatically reduce the AI's chances of stepping on a landmine in just a few lines. If you want to strengthen your CLAUDE.md, this is the best place to start. In a real CLAUDE.md, it would look like this fenced section:

## Gotchas

- `payments/` is maintained by a separate team. Do not touch the billing logic; if a change is needed, check with the owner.
- Without the `OAUTH_REDIRECT_URI` env var, the app works locally but will always fail in CI. See `.env.example`.
- `legacyExport()` calls the synchronous version for historical reasons. Changing it to `asyncExport()` will break the production batch job.

Having even one concrete example like these 3 lines — rather than the abstract instruction "write your gotchas" — makes it immediately clear what to preserve.

6. Principle 5: Use @import and Placement Scope to Prevent Bloat

To maintain density while preserving information, keep the CLAUDE.md body itself thin and extract details into external files. Claude Code supports loading via @path/to/import syntax, so heavy information like schemas, API specifications, and domain rules can live in separate files, with the main file pointing only to their location and a brief description.

Furthermore, procedures and specialized knowledge that are only needed occasionally should be turned into Skills rather than kept resident in CLAUDE.md — a practice recommended by the official documentation. Skills are only loaded when needed, so they do not inflate every conversation.

Placement location is also a tool for scope management. The main placement options are as follows:

1. ~/.claude/CLAUDE.md: For personal settings shared across all projects
2. ./CLAUDE.md: Committed to git and shared with the team
3. ./CLAUDE.local.md: Added to .gitignore for personal notes
4. Parent / child directories: For per-layer rules in a monorepo

By splitting files by role, each one stays short and effective.

7. Principle 6: Design Differently for Individual, Team, and Monorepo

The optimal structure changes with project scale. Rather than applying the same template everywhere, adapt the design to fit the context.

For solo development, put language preferences and commonly used commands in the global ~/.claude/CLAUDE.md, and restrict each repository's CLAUDE.md to project-specific items only. This eliminates duplication.

For team development, always commit CLAUDE.md to git and share it. As the official documentation puts it, "the file compounds in value over time" as every team member continues contributing to the same file. The quality of AI output also becomes more consistent — whoever makes a request gets code that meets the same standard.

For a monorepo, place shared global rules at the root and package-specific rules in each package directory. The root CLAUDE.md and the CLAUDE.md in the active working directory are automatically merged and loaded, so you can operate with responsibilities divided across files rather than in a single monolithic document.

8. Principle 7: Prune Monthly and Verify by Whether Behavior Actually Changed

CLAUDE.md is not a write-once artifact. The official documentation says: "Treat your CLAUDE.md like code — review it when things go wrong, prune it regularly, and test changes by whether Claude's actual behavior changes." The assumption is that it is a living document you grow over time.

A good operational routine looks like this:

1. Use /init to auto-generate a draft from the project structure
2. When the AI repeats the same mistake, add a one-line fix for it
3. Conversely, delete any line where the instruction can be removed and things still work correctly, or convert it to a Hook
4. Once a month, go through every line and prune against the "can this be deleted?" standard

The key is how you verify. After adding or removing rules, observe whether Claude's actual behavior changed. If it didn't, that line isn't doing anything. By measuring effectiveness in terms of behavior, the file keeps getting stronger without growing.

Quick Reference for All 7 Principles — Scan and Apply

Here is each of the 7 principles condensed to a single line for easy reference during real work. If the AI summary at the top is the "overview," this table is the "application checklist." When in doubt, check the "one-line summary" for direction and use "delete / offload to" to decide where something belongs.

9. The Bloat Trap: 5 Anti-Patterns That Kill the Ultimate CLAUDE.md

Finally, here are the classic mistakes that weaken an otherwise good CLAUDE.md. The official documentation also warns against "the over-specified CLAUDE.md" as a representative failure pattern. When it grows too long, important rules get buried under noise and the AI ignores half of them.

The 5 anti-patterns to avoid:

1. Dumping /init's auto-generated output as-is without reviewing or refining it, letting bloat accumulate
2. Writing obvious advice that the AI would do anyway, like "write clean code"
3. Stuffing in all your style conventions — indentation, quotes, etc. — that should be delegated to a linter
4. Including frequently changing information or file-level structural explanations that go stale quickly
5. Mixing in long explanations, tutorials, or rules that contradict each other

There is one remedy: prune without mercy. If Claude behaves correctly without an instruction, delete that line or convert it to a Hook. Remember: the ultimate CLAUDE.md is not "the file where you wrote everything" — it is "the file where only the effective lines remain."

Clauder Navi Editorial Team

Sources

• Best practices for Claude Code (Claude Code Official Documentation)
• CLAUDE.md (Memory) | Claude Code Official Documentation
• Claude Code: Best Practices for Operating CLAUDE.md — 7 Principles for Success (Zenn / imohuke)