Why Cutting 80% of Claude’s System Prompt Improves Performance and How to Slim Your CLAUDE.md

1. What was removed

The old Claude Code system prompt contained a long rule such as:

In code: default to writing no comments. Never write multi-paragraph
docstrings or multi-line comment blocks — one short line max. Don't create
planning, decision, or analysis documents unless the user asks for them —
work from conversation context, not intermediate files.

In plain language: never write comments, never use multi‑line docstrings, and only generate planning or analysis documents when explicitly asked.

The new prompt replaces that whole paragraph with a single sentence:

Write code that reads like the surrounding code: match its comment density,
 naming, and idiom.

Now the model is instructed to make its output match the surrounding code’s style rather than obeying rigid constraints.

2. Why removing rules didn’t hurt performance

Anthropic examined internal Claude Code conversation logs and found that the same request often contained contradictory instructions—system prompts saying “leave documentation where needed”, Skills saying “don’t add comments”, and the user sometimes adding a third demand.

Claude can usually infer the user’s intent, but it must first spend reasoning cycles to decide which rule to follow, burning compute that could be used for the actual task.

The change is called unhobbling —loosening the model from the many constraints that were originally added as guardrails for older generations. Claude 5’s improved judgment makes those guardrails unnecessary.

Claude Code also now has many more built‑in tools (memory, artifacts, Skills). Previously CLAUDE.md was the sole source of context; the heavy‑weight system prompt is no longer needed.

3. Six old practices that have flipped

Give Claude fixed rules → Let Claude decide – unless you have a clear, reproducible failure, avoid absolute prohibitions like “never X”.

Provide usage examples in the tool description → Design clear tool interfaces – parameter names, enum values, and types become the documentation.

Inject everything up‑front → Progressive disclosure (load on demand) – split specifications into a file tree and read only when needed.

Repeat important statements three times → Keep usage only in the tool description – remove redundant repetitions from system prompts.

Write long‑term memory into CLAUDE.md → Rely on automatic memory – keep CLAUDE.md lightweight.

Describe specifications in markdown → Provide high‑fidelity reference material – code, tests, or HTML mock‑ups are preferred over prose.

The first three items are the most counter‑intuitive and are explained in detail.

Examples that can limit the model

Previously the first rule for a tool was to give a few‑shot example. The official example for Claude Code’s Todo tool is the status enum ( pending / in_progress / completed) plus a constraint “keep only one in_progress ”. This tightly fixes the model’s behavior; the new approach prefers no example and lets the model reason from the tool’s schema.

When designing a tool, the question shifts from “should we add a few‑shot?” to “are the parameters expressive enough for the model to speak?”.

Progressive disclosure for Skills and tools

Rare but critical instructions (e.g., code review, verification) are moved from the system prompt into a separate Skill that is loaded only when needed. Tools can also be lazy‑loaded: the model first sees only the tool name, then uses ToolSearch to fetch the full definition.

In the current session, tools like Task, WebSearch, and MCP initially expose only their names; their schemas are retrieved on demand, saving tokens when the tool is not used.

4. Four layers of context, each with its own place

System Prompt : defines product identity and runtime environment; rarely changed by Claude Code users.

CLAUDE.md : a single sentence describing the repository’s purpose; all token budget is spent on “gotchas” that cannot be inferred from the file layout.

Skills : lightweight guides that the model can locate when needed; avoid turning them into hard constraints unless the domain is critical. Long Skills should be split into multiple files.

References : use @ to pull in external material, preferring code‑based artifacts because the model understands code best.

Real‑world case : The author merged four separate Skills into one routing file ( SKILL.md ) and moved detailed specifications into a references/ folder. The merged Skill now loads less content per conversation and eliminates conflicting instructions.

5. Hands‑on: run /doctor then prune yourself

Anthropic packaged the best‑practice checklist into the claude doctor tool. In Claude Code, run: /doctor The tool flags structural issues; the user still needs to apply several manual steps:

Read through CLAUDE.md and delete any “just‑look‑at‑the‑repo” information (directory structure, obvious naming conventions).

Search for absolute prohibitions ( don't, must not, never) and ask “Do I have a real failure case for this?” If not, delete it.

When the same rule appears in System Prompt, CLAUDE.md, and a Skill more than twice, keep only one instance and move tool usage into the tool description.

Split Skills longer than two screens into a SKILL.md router plus a references/ folder.

Before writing a new specification, ask whether you can provide an HTML mock‑up, a test case, or a reusable function.

Conclusion

The underlying logic of this change is that more context does not equal more safety. Conflicting rules force the model to spend reasoning cycles on arbitration instead of solving the user’s problem. With a stronger model, the benefits of deleting and structuring context now outweigh adding another rule.

Start by opening your longest CLAUDE.md and questioning each rule: has the model actually failed because of it, or are you just afraid it might?

Related Links

The original blog post and the author’s X post are:

The new rules of context engineering: https://claude.com/blog/the-new-rules-of-context-engineering-for-claude-5-generation-models
Thariq’s X post: https://x.com/trq212/status/2080710971228918066

Additional reading:

Claude Code team interview by Simon Willison: https://simonwillison.net/2026/Jul/21/cat-and-thariq/
Building verification loops with Skills: https://claude.com/blog/building-verification-loops-in-claude-code-with-skills