Using Claude Code in my daily work, every time I added instructions to CLAUDE.md (the per-project instruction file), I carried the same nagging question: how detailed should these instructions actually be? On July 24, 2026, Anthropic published an article that answers this question head-on: “The new rules of context engineering for Claude 5 generation models,” on its official blog. The author is Thariq Shihipar, a member of the company’s technical staff, and the full text was also posted the next day (July 25, Japan time) on his own X account (@trq212). This article organizes and introduces its content. All figures shown below are quoted from that post (@trq212) (illustrations by Anthropic).
Conclusion — six best practices have become myths
The central report of the article is this single sentence.
We removed over 80% of Claude Code’s system prompt for models like Claude Opus 5 and Claude Fable 5 with no measurable loss on our coding evaluations.
(More than 80% of Claude Code's system prompt was deleted for models such as Claude Opus 5 and Claude Fable 5, with no measurable performance loss on coding evaluations)
On that basis, the article presents six best practices that were effective for older model generations but have now become myths, each paired with its new counterpart.
Figure 1: The six best practices of older model generations (left, struck through) and the new guidance for the Claude 5 generation (right)
| Then | Now |
|---|---|
| Give Claude rules | Let Claude use judgement |
| Give Claude examples | Design interfaces |
| Put it all upfront | Use progressive disclosure |
| Repeat yourself | Simple tool descriptions, in one place |
| Memory in CLAUDE.md files | Auto-memory |
| Simple specs | Rich references |
Below, we work through the article starting from the underlying problem.
Premise — a prompt and a context are different things
The article first distinguishes between the “prompt” a user types and the “context” the model actually receives. When you send a message to Claude, the prompt is only a small part of the whole context; most of it is assembled from the system prompt, skills, CLAUDE.md files, memory, and other sources. Designing this assembly is what the article calls context engineering.
The essential difference from a prompt is generality. A prompt can be written specifically for the task at hand, but context is used across many requests, so it must be written without knowing what the user will ask. The optimal answer to this question—how to write general-purpose guidance—shifted substantially with the change of model generations. That is the article’s subject.
Unhobbling Claude — excessive constraints breed contradictions
When Anthropic read transcripts of its own internal Claude Code usage, it found cases where the system prompt, skills, and user requests clashed, leaving contradictory instructions coexisting within a single request. The example the article gives is “leave documentation as appropriate” coexisting with “DO NOT add comments.”
Figure 2: An example of potentially conflicting instructions coexisting in one context. Claude must read everything and reconcile it before deciding what to do (the wording in the figure is illustrative)
Claude can generally interpret the user’s intent and reach the right answer, but overlapping and contradictory instructions force it to spend extra thought reconciling them. Such strong constraints were once necessary to avoid worst-case scenarios like accidentally deleting files. With the current generation, however, the article reports that many of them can be deleted, leaving the decisions to surrounding context and the model’s own judgement.
The article also points to a change in the available tooling as another reason constraints can be reduced. Claude Code once relied on CLAUDE.md as its store of memory, information, and guidance; it now has memory, artifacts, and skills, giving it more ways to load and share context across sessions.
The six shifts
1. Give Claude rules → Let Claude use judgement
When Claude Code first rolled out, the team deliberately wrote strong instructions that were not always true, in order to reliably avoid worst cases. This is the actual example from the old system prompt that the article shows.
In code: default to writing no comments. Never write multi-paragraph docstrings or multi-line comment blocks — one short line max.
(In code, write no comments by default; never write multi-paragraph docstrings or multi-line comment blocks — one short line at most)
For a certain subset of prompts, this instruction is simply wrong. Users may have their own preferences about documentation, and specific parts of very complex code may genuinely need multi-line comment blocks. Even so, with older models, many of the comments written without this guardrail would have been inappropriate, so the tradeoff was accepted—so the article explains. In the new system prompt, the same passage has been replaced with a single sentence.
Write code that reads like the surrounding code: match its comment density, naming, and idiom.
(Write code that reads like the code around it, matching its comment density, naming, and idiom)
An enumeration of prohibitions has turned into a statement of judgement criteria.
2. Give Claude examples → Design interfaces
Teach tool usage through examples—this was once the number one rule of tool use. With the newest generation, however, the team found that giving examples actually constrains the models to a certain exploration space.
What is recommended instead is rethinking the design of the tools, scripts, and files themselves: what parameters does Claude have, and how can they be more expressive? Using a task-management tool (TodoWrite) as its example, the article explains that merely defining the status parameter as an enumeration of pending, in_progress, and completed hints at how to use it, and a single sentence about keeping only one item in_progress defines the requested behavior.
Figure 3: The TodoWrite tool description before and after revision. Roughly 9,100 characters of usage examples were replaced by an enumeration type and a short constraint
3. Put it all upfront → Use progressive disclosure
The old system prompt always included detailed procedures for code review and verification—not always needed, but crucial when they were. Today’s Claude Code has become very competent at progressive disclosure—loading the right context at the right times—so verification and code review procedures were moved into their own skills that it can selectively call.
Progressive disclosure is not just for skills. Some tools are “deferred loading”: the agent must search for their full definitions with a tool called ToolSearch before using them. This makes it possible to have many tools that consume no context until they are needed.
The same thinking applies to your own CLAUDE.md and skill files. The idea that you should make them a central repository of every practice you might run into—because Claude would not find it otherwise—is a myth; instead, the article recommends a tree of files that can be loaded at the right time.
4. Repeat yourself → Simple tool descriptions, in one place
Earlier Claude models could sometimes need repeated instructions, or be more likely to follow instructions at the end of the context window than at the start. As a result, references to the same tool sometimes appeared both in the main system prompt and in the tool description. With the current generation, the team found these duplicates could be deleted, consolidating instructions for using a tool into the tool description alone.
5. Memory in CLAUDE.md files → Auto-memory
Users were once encouraged to save notes to Claude’s memory with the # hotkey, which wrote to their CLAUDE.md automatically. This has been replaced by a mechanism (auto-memory) in which Claude automatically saves memories relevant to the work and to the user.
6. Simple specs → Rich references
In plan mode, Claude Code has relied heavily on storing plans as markdown files and referring back to them when needed. For longer projects, keeping specs in the codebase was a similar staple practice. The current generation, however, can handle increasingly complex references, and the article lists these options:
- Instead of simple markdown files, reference HTML artifacts created with the new artifacts feature
- Give specs in the form of code—a detailed test suite, or a function in a different codebase to be ported, can also serve as a spec
- Give rubrics as references—criteria such as “what does a good API design look like,” which Claude can verify by spinning up verifier agents equipped with those rubrics
Applying this to your own context
The latter half of the article reorganizes all of this into guidance per layer of the context.
Figure 4: The layers of the assembled context. Beneath the prompt sit references, the system prompt, CLAUDE.md files, skills, and memory
- System prompt: A layer tightly tied to the product context; it tells Claude what product it is operating in and what it is doing. Claude Code users will likely never modify it, but if you are building your own agent harness, this is where you should spend the most time
- CLAUDE.md: Keep it lightweight and describe briefly what the repo is for, but spend most of the tokens on gotchas inside the codebase (for example, a repo-specific convention such as keeping type definitions in one monolithic file and nowhere else). Avoid stating the obvious—things Claude should know by looking at your file system or repo. Split details like verification procedures into a separate skill and only reference it from CLAUDE.md
- Skills: Think of them as lightweight guides that let Claude find information when needed. Avoid making them overconstrained, except in highly important areas. For long skills, divide them into many files and lean on progressive disclosure; they work best when they encode opinions, knowledge, or best practices particular to you, your team, or your product
- References: @-mention files to hand Claude in-depth information about the current plan. This might be spec files, mockups, or even entire codebases, but files in the form of code are generally preferable, because they give Claude clear, high-fidelity instructions in a language it knows very well. For example, the article states that an HTML mockup of a design will generally produce better results than a written description of the design or a screenshot
The article closes by encouraging readers to simplify their system prompts, skills, and CLAUDE.md files just as the team did, and introduces a command that helps do this automatically: claude doctor (/doctor inside Claude Code).
Summary
- For the Claude 5 generation (Opus 5, Fable 5, and so on), more than 80% of Claude Code’s system prompt was deleted, reportedly with no measurable loss on coding evaluations
- The underlying issue is overconstraint: when instructions overlap and contradict each other across the system prompt, skills, and user requests, the model spends extra thought reconciling them
- Six best practices that worked for older generations (enumerating rules, providing usage examples, front-loading all information, repeating instructions, memory in CLAUDE.md, markdown specs) have become myths, replaced by delegation to judgement, interface design, progressive disclosure, consolidation into tool descriptions, auto-memory, and rich references
- The practical takeaways for users boil down to: keep CLAUDE.md light and focused on gotchas; split details into skills for progressive disclosure; and hand over specs in the form of code, such as test suites or HTML mockups
- A command is provided to help simplify existing configurations:
claude doctor(/doctor)
References
- The new rules of context engineering for Claude 5 generation models — Claude Blog (July 24, 2026, by Thariq Shihipar) — the primary source for this article
- @trq212 on X (July 25, 2026) — the author’s own post of the article’s full text; all figures shown are quoted from this post (illustrations by Anthropic)