Claude Code: the new way to write your CLAUDE.md (Anthropic cut 80% of its own)

An engineer on the Claude Code team just published the new rules of “context engineering.” The number that stings: Anthropic cut more than 80% of Claude Code’s system prompt for Claude 5 generation models, with no measurable loss on its coding evals.

Translation: if you’ve been piling rules into your CLAUDE.md for a year, you’re paying tokens for work the model already does on its own. And you’re slowing it down.

The essentials:

  • Claude’s context isn’t your prompt. It’s system prompt + skills + CLAUDE.md + memory + referenced files. All of it loads every session, and you pay for it every time.
  • Claude 5 models (Opus 5, Sonnet 5, Fable 5) have enough judgment to do without the guardrails written for their predecessors. Those guardrails have turned into noise, sometimes contradictory noise.
  • Six concrete shifts to make: give a goal instead of rules, design interfaces instead of examples, load context at the right time, never repeat yourself, let automatic memory do its job, reference code instead of descriptions.
  • The /doctor command (already built into Claude Code) audits your setup and offers to trim the fat. Tested for this article on version 2.1.220.

1. “Context engineering”: what exactly are we talking about

When you send Claude a message, your prompt is only a small part of what the model receives. The rest gets assembled automatically:

  • the product’s system prompt (Claude Code’s, which you don’t touch);
  • your skills, the procedures you wrote for recurring tasks;
  • your CLAUDE.md files, at the global level (~/.claude/CLAUDE.md) and at the project level;
  • the memory Claude has saved across sessions;
  • the files referenced with @ (specs, mockups, code snippets).

Context engineering is the art of putting all that together. And the difference from a classic prompt is fundamental: a prompt is written for one specific request, while this context applies to all your requests. You’re writing general instructions without knowing what you’ll ask tomorrow.

That’s exactly where old habits get expensive.

2. Why Anthropic cut 80% of its system prompt

The team’s conclusion is simple: they were over-constraining Claude Code. The system prompt, skills and CLAUDE.md regularly contradicted each other.

The example in the article says it all. In transcripts of their own sessions, they saw two incompatible instructions sitting side by side: on one hand “leave documentation when relevant,” on the other an all-caps “DO NOT ADD comments.” Claude eventually lands on its feet, but first it has to burn reasoning refereeing contradictory orders. Reasoning you pay for, and that makes the response longer.

Those guardrails had a reason to exist. When Claude Code launched, the priority was avoiding disaster scenarios: deleted files, comments everywhere. The team accepted a rule that was sometimes wrong over the risk of things going off the rails.

Recent models no longer need that crutch. More importantly, they have tools that CLAUDE.md was standing in for in the absence of anything better: automatic memory, artifacts, skills.

Key takeaway: if your CLAUDE.md is six months old, it probably contains rules written against a model that no longer exists.

3. The six “before → now” shifts

This is the heart of the method. For every line in your CLAUDE.md or your skills, ask yourself which of these shifts applies.

Shift 1 — Rules → judgment

Before, we wrote explicit prohibitions. Claude Code’s system prompt basically said: by default, write no comments, never multi-paragraph docstrings, one short line max.

Now, a single sentence replaces all of it: write code that looks like the surrounding code — same comment density, same naming conventions, same idioms.

The rule applies across the board. Describe the goal and the expected result, and let the model pick the path.

Shift 2 — Examples → well-designed interfaces

The number one rule of tool use used to be: give call examples. On recent models, those examples box the model into a narrow exploration space.

You’re better off polishing the design of the tool itself. Anthropic points to its todo-list tool: the mere fact that the status field is an enum of pending / in_progress / completed is enough to explain how to use it. The interface carries the instruction, no paragraph of examples needed.

Apply that to your scripts and file names: expressive parameters beat verbose docs.

Shift 3 — Load everything upfront → progressive loading

This is the shift with the biggest token payoff.

Claude Code’s system prompt shipped with detailed code review and verification procedures. Useful when they were needed, but they weren’t always needed, and they loaded every session. Anthropic moved them into skills that Claude calls only when it needs them.

The same principle applies to tools: some use “deferred loading” (defer_loading). The agent first has to look them up through a search tool before getting their full definition. The result: you can expose far more tools without them taking up context until they’re actually used.

And it holds for your own files too. The myth to drop: “my CLAUDE.md has to contain everything, or Claude won’t find it.” Wrong. Build a tree of files that load at the right time.

Shift 4 — Repeating yourself → a single description

Older models sometimes needed an instruction repeated, and paid more attention to what sat at the end of their context window. Hence duplicated instructions: once in the system prompt, once in the tool description.

Anthropic removed the duplicates. A tool’s usage instructions live in the tool description, and nowhere else.

Shift 5 — Manual memory → automatic memory

The old habit: the # shortcut to write into your CLAUDE.md on the fly. Today, Claude saves what’s relevant to your work and to you on its own. Stop manually feeding a file that grows every session.

Shift 6 — Simple specs → rich references

In plan mode, Claude Code leaned heavily on markdown files. That was best practice: store specs in the repo so Claude could refer to them on long projects.

The model now handles much richer references. A spec can be a test suite. A mockup can be an HTML artifact instead of a description. A function from another project can serve as a reference to port. And a grading grid (rubric) lets Claude check its work against your own standard — for example, “what a good API looks like here.”

Simple rule: always prefer code over description. An HTML mockup will get better results than a paragraph, or even a screenshot.

4. Step by step: audit your setup with /doctor

Good news: you don’t have to do this audit by hand. Anthropic built these best practices into a command.

In a Claude Code session, type:

/doctor

(Outside a session, claude doctor on the command line runs a more limited installation check. The command is available in the terminal; it doesn’t show up in the desktop app.)

It works in two stages, and that matters: the command first scans in read-only mode, shows you a report, then asks for your approval before changing anything. You stay in control of what gets deleted.

What it checks:

# Check What it detects
1 Installation health version, duplicate or leftover installs
2 Config files broken settings, conflicting agent definitions
3 Dead weight skills, MCP servers and plugins you never use
4 Redundancies rules repeated elsewhere in your setup
5 Trimming the CLAUDE.md context the session can figure out on its own
6 Lazy loading always-loaded instructions that would work better as a skill
7 Blocking scripts hooks that run on every tool call
8 Context weight what eats your budget before you even type anything
9 Permissions auto mode by default, to avoid repeated approvals

Item 3 is the one that surprises the most people. In Duncan Rogoff’s demo (Learn Claude Code), the report shows 113 personal skills, or roughly 10,000 tokens of context consumed every session — just to list them. Of those 113, 25 had never been used even once. The command relies on usage counters and the transcripts of the last 50 sessions to figure that out: it’s not an estimate.

10,000 tokens per session means your budget is gone before your first word.

5. Rewriting your CLAUDE.md: before / after

The guiding principle: your CLAUDE.md loads in every session. The leaner, the better. Think of it as a table of contents or an index, not an encyclopedia.

What should go — anything Claude can figure out by looking at your repo:

  • your folder structure;
  • your tech stack (it reads your package.json);
  • standard build commands;
  • the obvious conventions of your language.

What should stay — and where you should spend your tokens: the gotchas in your codebase. The things nobody would guess.

Typical example: “all types live in a single monolithic file, nowhere else.” No amount of folder inspection reveals that. That’s exactly the kind of information that earns its spot.

Instead, a tree

Rather than a 400-line file:

CLAUDE.md              ← 30 lignes : à quoi sert le dépôt + les pièges
  ├─ skills/verification/SKILL.md   ← comment on vérifie une PR ici
  ├─ skills/deploy/SKILL.md         ← la procédure de déploiement
  └─ skills/api-design/SKILL.md     ← nos conventions d'API

The CLAUDE.md simply says: here are the available skills, here’s what each one does. Claude goes and fetches the details when it needs them. The rest of the time, it costs nothing.

Same logic inside a skill that’s too long: split it into several files instead of cramming.

For your skills

Three rules:

  1. Think “guide,” not “rulebook.” A skill exists so Claude can find information when it needs it. Avoid over-constraining, except in truly critical areas.
  2. Encode what’s specific to you. A skill is valuable when it holds your opinions, your know-how, the practices of your team or your product. Not when it re-explains what the model already knows.
  3. Delete the ones you don’t use. Every unused skill costs you context every session, just to show up in the list.

6. What to remember before you dive in

The message fits in one word: simplify.

Three habits to change starting today:

  • Stop piling on. Every rule you add is a token paid every session, and a risk of contradicting another rule. The question is no longer “what can I add” but “what can I remove.”
  • Describe the goal, not the procedure. Tell Claude what you want to accomplish and let it find the best path.
  • Load at the right time. A lightweight table of contents pointing to specialized files beats a single do-everything file every time.

And if you only do one thing: run /doctor, read the report, and see how many tokens go up in smoke before your first question.

Sources: