Jonathon's AI Wiki

The New Rules of Context Engineering for Claude 5 Models (Thariq Shihipar, Anthropic)

13 min read

Source: ai-research/anthropic-new-rules-context-engineering-claude-5-2026-07-24.md — Anthropic first-party blog post, claude.com/blog/the-new-rules-of-context-engineering-for-claude-5-generation-models, published 2026-07-24 by Thariq Shihipar, member of technical staff (same author as html-effectiveness and How I Plan, Build, and Run Loops).

Anthropic removed over 80% of Claude Code’s system prompt for Opus 5 and Fable 5 “with no measurable loss on our coding evaluations,” and published what they learned as six then/now inversions of context-engineering practice. The through-line is that guidance written to stop older models from failing now actively costs quality: the model spends effort reconciling conflicting instructions instead of using judgement. Shipped the same day as Opus 5, alongside a new /doctor command that rightsizes your skills and CLAUDE.md automatically.

Key Takeaways

  • The headline is a deletion, not an addition. >80% of the Claude Code system prompt removed for Claude 5-generation models, no measurable eval regression. The claim is about their system prompt on their coding evals — but it is the strongest first-party signal yet that verbose context is now a liability rather than insurance.
  • “Unhobbling.” Anthropic read transcripts of their own internal Claude Code usage and found conflicting instructions colliding inside single requests — “leave documentation as appropriate” from one layer against “DO NOT add comments” from another. Claude can usually infer intent, but “must think more carefully about these overlapping and conflicting messages before deciding what to do.” The constraints were once load-bearing; now they mostly tax.
  • Rules → judgement. The old system prompt said: “default to writing no comments. Never write multi-paragraph docstrings or multi-line comment blocks — one short line max.” The replacement is one line: “Write code that reads like the surrounding code: match its comment density, naming, and idiom.” A blanket rule is wrong for the subset of cases where the user wants docs, or where complex code genuinely needs them.
  • Examples → interface design. This is the most counterintuitive reversal. Giving tool-usage examples was “the number one rule”; now examples “actually constrain them to a certain exploration space.” Spend the effort on expressive parameters instead — a status enum of pending/in_progress/completed teaches the tool’s use by its shape, and “keep one item in_progress” defines the behavior without a worked example.
  • Upfront → progressive disclosure. Verification and code review moved out of the system prompt into selectively-callable skills. It applies to tools too: some are deferred-loading, where the agent must find full definitions via ToolSearch before use, so a large tool inventory costs nothing until needed. The explicit myth: that CLAUDE.md and SKILL.md should be a central repository of every practice “because Claude would not find it otherwise.” Build a tree of files loaded at the right time instead.
  • Repetition → simple tool descriptions. Older models weighted end-of-context instructions more heavily, so guidance got duplicated in both system prompt and tool description. Those repeats were deleted; instructions on using a tool now live in the tool description alone.
  • # hotkey → auto-memory. Anthropic used to encourage writing to CLAUDE.md via the # hotkey. “Instead, Claude now automatically saves memories that are relevant to the work and to you.” This supersedes guidance still carried in the CLAUDE.md primer — see the note added there.
  • Simple specs → rich references. A spec no longer has to be a markdown file. It can be an HTML artifact, a detailed test suite, or a function in another codebase to port. Rubrics are called out as a reference form that lets Claude verify your taste in a domain (e.g. what good API design looks like) by spinning up verifier agents via dynamic workflows.
  • Prefer code over prose for references. @-mentioned files are the mechanism; the guidance is to favor artifacts already in code “as it provides clear, high-fidelity instructions to Claude in a language it knows very well.” Concretely: an HTML mockup beats a written description or a screenshot of the same design.

What to actually put where

The post closes with per-surface guidance, which is the operational core:

SurfaceGuidance
System promptTied to product context — what product Claude is in and what it’s doing. In Claude Code you will likely never modify it; if you are building your own harness, spend a lot of time here.
CLAUDE.mdKeep it lightweight. Briefly say what the repo is for, then spend most of the tokens on gotchas (e.g. “types live in one monolithic file and nowhere else”). Avoid stating the obvious — anything Claude can learn by looking at the file system or repo. Push detail into skills and reference them.
SkillsLightweight guides, not constraints — “avoid making them overconstrained, except in highly important areas.” Split long skills across many files for progressive disclosure. Best when they encode opinions/knowledge specific to you, your team, or product.
References@ mention files. Prefer code-shaped references (specs, mockups, whole codebases) over prose.

Why this matters here

This wiki’s existing guidance is mostly already aligned with the new advice, which is a useful independent check rather than a coincidence: the CLAUDE.md primer already says trim it, keep only load-bearing context, and “resist the urge” to front-load a comprehensive file; Steering Claude Code already caps CLAUDE.md at ~200 lines with an owner and code-review discipline. What is genuinely new is (a) the magnitude — 80% deletion with no eval loss, (b) the examples-are-now-harmful inversion, which no prior wiki article anticipated, and (c) the #-hotkey supersession.^[the “already aligned” comparison is this wiki’s own cross-check against its prior articles, not a claim in the post]

The deferred-loading/ToolSearch mechanism the post describes is not hypothetical — it is the same primitive this vault’s own sessions run on, and it is the reason a large tool inventory can sit behind a search interface rather than in the prompt.

Try It

  1. Run /doctor in Claude Code. Anthropic says the post’s best practices are encoded in it and that it will rightsize your skills and CLAUDE.md files automatically. Start here before hand-editing anything.
  2. Grep your own CLAUDE.md for blanket rules — never, always, DO NOT, must — and ask, for each, whether it is guarding a real failure or pre-empting a decision the model can now make from context. Delete the latter.
  3. Hunt for conflicts across layers. The failure Anthropic found was contradictory instructions arriving from system prompt + skills + user request at once. Read a CLAUDE.md, its skills, and a typical request together, not separately.
  4. Convert a long CLAUDE.md section into a skill and reference it — the post’s worked example is a verification skill pulled out of CLAUDE.md.
  5. Strip tool-usage examples and strengthen parameter design instead — expressive enums and constrained types over worked examples.
  6. Upgrade one spec to a rich reference. Swap a prose description for an HTML mockup, a test suite, or a pointer to a function to port.
  7. Stop reaching for #. Auto-memory now covers the case it was invented for.

Reception and a practitioner walkthrough (2026-08-05 addition)

Source: raw/Claude_Code_Just_Changed_Forever_6_NEW_Rules_by_Anthropic_Engineers.md — Jay / Robo Nuggets, youtu.be/gQeRjkb_Hlc, transcript fetched 2026-08-05. Secondary; the creator promotes a paid community and a free skill.

The article reached ~4.3 million views within days of publication — worth recording because it makes this one of the most widely-read pieces of Anthropic context-engineering guidance, and because the derived practices below are now circulating well beyond the original post.

What the walkthrough adds beyond restating the six shifts:

  • CLAUDE.md as a router, with sub-routers. The creator’s workspace holds ~57,000 files; rather than one thick CLAUDE.md, it is a thin router pointing at per-domain files (content, community, product, personal, business), each of which is itself a router naming the relevant skills and markdown for that domain (e.g. a content.md that routes ideation vs. production). This is progressive disclosure applied recursively — the same move this wiki’s own vault schema made when it split operations into operations/*.md.
  • The token argument for a thin CLAUDE.md. A verbose CLAUDE.md is injected at the first prompt of every session, so its cost is paid per session forever. Framed as the practical reason the router pattern matters for anyone hitting usage limits, not just an aesthetic preference.
  • /doctor is not enough on its own. The creator’s read is that the shipped /doctor (install health, dead-weight skills/MCP servers, CLAUDE.md trimming, slow hooks) is “a bit more basic” and does not check the six shifts. Their free /doctor-plus skill wraps /doctor and adds a per-shift audit; the worked example flags a 2,090-line skill as a router candidate. Note that Claude Code v2.1.221 shipped an official prompt-audit subcommand on the claude-api skill for auditing prompts and tool descriptions for older-model patterns — see Week 32. That is the first-party answer to the same need and should be tried before a community wrapper.
  • A /calibrate end-of-session skill. Reviews the just-finished conversation and writes the learnings back into skills, CLAUDE.md rules, memory files, and workflows — the manual counterpart to the auto-memory shift, for people who want the write-back to be deliberate.
  • HTML artifacts as the “richer references” case. The concrete example is a brand book as HTML rather than markdown: the agent parses it as text either way, but the human can see the palette. Consistent with the shift from simple specs to richer references.
  • The “surprise me” pattern for the judgment shift. A skill whose entire description is a mandate for taste and range rather than a rule list, used to escape default AI-slop front-end aesthetics — the creative-work reading of “let Claude use judgment.”

Two calibration notes: the video reports the ~80%-system-prompt-reduction figure as “no measurable loss on their coding evaluations” (consistent with the primary source), and it renders the author’s name inconsistently across the transcript (“Tariq”/“Tarek”/“Thrivec” — auto-caption garble for Thariq Shihipar).

The thesis gets a first-party number, and a field cost (2026-08-19 addition)

Two updates land on opposite sides of the same argument.

Progressive disclosure, measured. Claude Code v2.1.234 reports: “Reduced the context cost of loading the built-in claude-api skill from ~200k+ tokens to ~25k by loading reference docs on demand.” That is an 8× reduction on a shipping first-party skill, achieved by deferring reference material rather than deleting it — the largest concrete number the wiki has attached to this article’s central claim. Two things make it more than a nice statistic:

  • The anti-pattern was Anthropic’s own. A built-in skill was spending ~200k tokens before any work began. The guidance and the shipped artifact had diverged, and the fix was to apply the article’s own advice.
  • Nothing was lost. The reference docs still exist and still load — just on demand. This is the same move the vault made splitting its schema into operations/ files, and the one Agent Skills prescribes for skill authorship.

The rules→judgement inversion has a measurable field cost. This article records that the blanket “default to writing no comments… one short line max” was replaced with “write code that reads like the surrounding code.” The community consequence is now documented: raw/reddit-1vs7cdt.md (162 pts / 82 comments) reports Opus 5 adding comments compulsively even against an explicit CLAUDE.md prohibition, acknowledging the error, continuing anyway, and in one case inserting comments that broke a bash script’s syntax.

This is not evidence the inversion was wrong — a blanket rule genuinely was wrong for the cases where docs are wanted. It is evidence of what the trade actually costs: a removed default converts a project-level prohibition from “reinforcement” into “argument.” A CLAUDE.md line that used to agree with the system prompt now contends with a judgment call, and judgment calls are exactly what does not persist across turns. The practical read for anyone applying this article’s guidance: when you remove a rule in favor of judgement, the instructions that depended on that rule need to move up the authority ladder — to a scoped rule, an output style, or a hook — not stay where they were. See Steering Claude Code for the ladder and Troubleshooting Claude for the mitigation sequence.

A standing objection, recorded not endorsed. raw/reddit-1vry6gk.md argues that progressive disclosure still uses model attention as part of the retrieval index — every installed skill’s name and description sits in the system prompt so Claude can decide what to load — and that this does not scale to 50, 500, or thousands of organizational rules. The proposed alternative is to keep the corpus external, index it, and use Claude Code hooks (which can see the file being edited, the tool being called, the workflow position) as the retrieval signal instead of a description match. The author discloses building a competing tool, the post scored 4 with no replies, and it carries no measurement — so it is filed as a well-formed objection, not a finding. Note that the claude-api reduction above narrows it without answering it: deferring a skill’s body shrinks the payload, not the catalog entry.

Open Questions

  • The 80% figure is scoped to Anthropic’s own system prompt and coding evals. No before/after prompt sizes, eval names, or numbers are published, and there is no guidance on how much of the reduction is safe to imitate on a non-coding harness.
  • “Examples constrain the exploration space” is asserted, not evidenced. No measurement is given, and it directly inverts long-standing few-shot practice — worth watching for a follow-up with data before stripping examples from a production agent wholesale.
  • /doctor behavior is undocumented here. What it inspects, what it rewrites, whether changes are diffed for approval, and whether it is safe on a heavily customized CLAUDE.md are all unstated in the post.
  • The “Fable field guide” is referenced for deeper prompting guidance but not linked in the captured text; it likely maps to Prompting Claude Fable 5 but that mapping is unverified.
  • Applicability to older models is not addressed. The advice is explicitly for “Claude 5 generation” models; whether removing guardrails degrades Sonnet/Haiku-tier or older deployments is not discussed.

Graph View

Backlinks