Context Engineering for Claude 5: The New Rules for CLAUDE.md, Skills, and Tools
Context engineering for Claude 5 models means deleting more than you add. Anthropic says it removed over 80% of Claude Code's system prompt for models like Opus 5 and Fable 5 with no measurable loss on its coding evaluations. Replace rules with judgement, examples with well-designed tools, and always-loaded instructions with skills, references, and auto memory.
Context engineering for Claude 5 models is mostly subtraction. Anthropic says it removed over 80% of Claude Code's system prompt for models like Claude Opus 5 and Claude Fable 5 with no measurable loss on its coding evaluations, and its post on the new rules of context engineering, published July 24, 2026, tells you to do the same to your own CLAUDE.md files, skills, and tools. The verdict: stop writing rules, examples, and always-loaded reference material, and give Claude judgement, well-designed tools, and context that loads only when the task needs it.
This page covers the standing context Claude carries into every request. For the in-session tools (/rewind, /compact, /clear, and subagents), see our Claude Code context management guide. For model-specific prompting, see prompting Claude Opus 5 and prompting Claude Fable 5.
Key Takeaways
- Delete before you add. Anthropic says it removed over 80% of Claude Code's system prompt for its newest models with no measurable eval loss.
- Give judgement, not rules. Hard rules that conflict with skills and user requests make Claude deliberate over the contradiction instead of the task.
- Design tool interfaces instead of writing examples. An enum of allowed states teaches a tool better than a page of worked examples.
- Load detail on demand. Move procedures into skills, split long skills into files, and defer rarely used tools behind tool search.
- Keep CLAUDE.md to gotchas. Target under 200 lines per file and cut anything Claude can read from the repo.
- Let auto memory hold what you used to save by hand. Claude records your corrections and preferences itself.
- Audit with
/doctor prompt-audit, notclaude doctor: the current docs give the terminal command only installation and settings diagnostics.
What Changed: Anthropic Cut Most of Claude Code's System Prompt
The change is a capability shift. Older Claude models needed strong, repeated guardrails to avoid worst-case behavior, so Claude Code's system prompt, CLAUDE.md files, and skills piled up hard rules. Reading transcripts of its own usage, Anthropic found those layers contradicting each other in a single request, for example one source asking for documentation and another forbidding comments. Claude 5 models can usually infer intent from the surrounding context, so the rules now cost more than they protect.
The comment rule shows the swap. The old system prompt told Claude to default to writing no comments and to keep any comment to one short line. That was wrong whenever a user had their own preference or a complex function needed a real explanation. The new system prompt asks Claude to "Write code that reads like the surrounding code" and to match its comment density, naming, and idiom.
The same reasoning applies to your own files. Context engineering, in the phrase from Anthropic's engineering guide, means finding "the smallest possible set of high-signal tokens" for the outcome you want. On Claude 5 models, that set is smaller than most teams' current setup.
The Six Rules, Then and Now
Anthropic lists six practices that have become myths on Claude 5 models. Each row below is a rule to retire and its replacement.
| Then | Now | Why it changed |
|---|---|---|
| Give Claude rules | Let Claude use judgement | Rules that were right for most prompts were wrong for the rest; newer models judge from context. |
| Give Claude examples | Design interfaces | Examples narrow how the newest models explore; expressive parameters steer without boxing them in. |
| Put it all upfront | Use progressive disclosure | Claude Code loads skills and deferred tools when needed, so rare guidance need not sit in every request. |
| Repeat yourself | Simple tool descriptions | Earlier models needed repetition; instructions for a tool now belong only in its description. |
| Memory in CLAUDE.md files | Auto memory | Claude saves relevant memories itself instead of relying on you to write them down. |
| Simple specs | Rich references | Claude handles HTML artifacts, code, test suites, and rubrics as references. |
Treat the table as a migration checklist. If your CLAUDE.md or a skill still does something in the left column, it is a candidate for deletion or a rewrite.
CLAUDE.md for Claude 5: Gotchas Only
Your CLAUDE.md should say briefly what the repo is for and spend the rest on gotchas Claude cannot discover by reading the code. Anthropic's example is a codebase that keeps all types in one monolithic file and nowhere else: a convention Claude would not guess. Leave out anything obvious from the file system, such as the directory layout or the framework you use.
Claude Code's memory docs set the size target: under 200 lines per CLAUDE.md file, because longer files consume more context and reduce adherence. Block-level HTML comments in CLAUDE.md files are stripped before the content reaches Claude, so you can leave notes for human maintainers at no token cost. The best practices guide gives the test for every line: ask whether removing it would cause Claude to make mistakes, and cut it if not.
Push procedures out of CLAUDE.md. If you have several instructions on how to verify work, Anthropic's advice is to write a verification skill and reference it from CLAUDE.md, so the detail loads only when Claude verifies something.
Skills as Progressive Disclosure
A skill should be a lightweight guide Claude opens when it needs it, not a rulebook. Anthropic moved Claude Code's own verification and code review guidance out of the system prompt and into skills that Claude calls selectively. Write skills that encode the opinions and practices specific to you, your team, or your product, and avoid over-constraining them except in areas where a mistake is costly.
Split long skills into files. The skills docs recommend keeping SKILL.md under 500 lines and moving detailed reference material into separate files that Claude loads when needed. Three limits make this matter:
| Limit | What it means for you |
|---|---|
| The skill listing budget scales at 1% of the model's context window | With many skills, Claude Code drops descriptions of the skills you invoke least, so keep each description short and keyword-first |
The combined description and when_to_use text is truncated at 1,536 characters in the listing | Put the main use case in the first sentence |
| After compaction, invoked skill bodies come back capped at 5,000 tokens per skill and 25,000 tokens in total | Put the most important instructions at the top of SKILL.md |
The listing figures come from the skills docs and the compaction caps from Claude Code's context window docs. To see which skills cost the most context, run /skill-doctor, which the commands reference lists as requiring Claude Code v2.1.252 or later and feature-flag fetching.
Tools: Design Interfaces, Not Examples
On Claude 5 models, the shape of a tool teaches more than examples of its use. The Claude Code team found that giving the newest models tool-use examples constrains them to a narrow exploration space. Its rewritten TodoWrite tool replaces long lists of when-to-use guidance and worked examples with a one-line description, a status enumeration of pending, in_progress, and completed, and a single rule that only one task is in progress at a time. The enum tells Claude how the tool works; the one rule states the behavior Anthropic wants.
Put each tool's instructions in its description and nowhere else. Earlier models sometimes needed instructions repeated in the system prompt, or followed text at the end of the context more than text at the start. Anthropic deleted those duplicates.
Defer the tools Claude rarely needs. Claude Code marks some tools as deferred, so Claude must find their full definitions with ToolSearch before using them, which lets Claude Code offer more tools without spending context on them. If you build your own agent, the API's tool search tool does the same with defer_loading: true. Anthropic's docs say a typical multi-server setup can spend about 55k tokens on tool definitions before any work, that tool search typically cuts this by over 85 percent, and that Claude's tool selection degrades past 30 to 50 available tools.
Two cache rules apply when you change tools. The prompt caching docs say modifying tool definitions invalidates the entire cache, so trim your tools once rather than editing them per request. A tool with defer_loading: true cannot also carry cache_control, so put your cache breakpoint on a tool that loads up front.
One tension to know: the API's tool definition guide still asks for detailed descriptions of at least three to four sentences per tool. Both are compatible if you read the post's rule as being about examples and repetition, not description length: describe what the tool does and when to use it, then let the parameters carry the rest.
Memory: Auto Memory, CLAUDE.md, and AGENTS.md
Stop using CLAUDE.md as a notebook. Anthropic says it used to encourage the # hotkey for writing memories into CLAUDE.md, and that Claude now saves memories relevant to the work and to you automatically. The split is now clean: CLAUDE.md holds instructions you write, and auto memory holds what Claude learns.
| CLAUDE.md | Auto memory | |
|---|---|---|
| Written by | You | Claude |
| What it holds | Instructions, conventions, gotchas | Your preferences, corrections, and project context Claude cannot derive from the code |
| What loads at session start | The whole file (up to 4 MiB) | The first 200 lines or 25KB of the MEMORY.md index, with topic files read on demand |
Auto memory is on by default in local sessions. According to the memory docs, it skips anything Claude can derive from the codebase and anything your CLAUDE.md files already say, so it does not duplicate your instructions. Set CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 to turn it off.
If your repository already has an AGENTS.md for other coding agents, Claude Code can read it as your project instructions. By default, Claude reads AGENTS.md instead of CLAUDE.md, and only when there is no CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md in your working directory or above it. Reading AGENTS.md directly requires Claude Code v2.1.277 or later. The same gotchas-only rule applies to that file. For the modes and the history, see our AGENTS.md support coverage.
References: Artifacts, Code, and Rubrics
When Claude needs depth on the current task, hand it a reference instead of a longer instruction file. You @-mention files to include them, and Anthropic says Claude now handles richer references than plain markdown plans: HTML artifacts, test suites, a function in another codebase to port, or an entire codebase.
Prefer references written in code. Anthropic's example is design work: an HTML mockup generally produces better results than a written description of the design or a screenshot. A detailed test suite works the same way as a spec.
Use rubrics for taste. A rubric for what good API design looks like lets Claude check its own work by spinning up verifier agents against it. If you already keep a set of reviewer subagents, our subagent patterns guide covers how to define one around a rubric.
Audit Your Setup With /doctor
Run /doctor prompt-audit first. The memory docs say it checks your instruction files for instructions written for older models, references to files or commands that don't exist, and files that contradict each other. You get a list of proposed edits, and nothing in your files changes until you ask. It covers CLAUDE.md, CLAUDE.local.md, and AGENTS.md files plus the rules, skills, commands, subagents, and output styles under .claude/ and ~/.claude/, and it requires Claude Code v2.1.283 or later.
Then run /doctor for the setup checkup. For a checked-in CLAUDE.md, it proposes cuts for content Claude can derive from the codebase, such as directory layouts, dependency lists, and architecture overviews, and keeps pitfalls, rationale, and conventions that differ from tool defaults. That trim check requires Claude Code v2.1.206 or later.
One naming difference: Anthropic's post says the new practices are built into claude doctor. The current CLI reference describes claude doctor as read-only installation and settings diagnostics run from the terminal, and the skills docs give the instruction audit and CLAUDE.md trims to /doctor inside a session. Use the in-session commands.
A practical order for one afternoon:
- Run
/doctor prompt-auditand apply the edits you agree with. - Run
/doctorand accept the CLAUDE.md trims. - Run
/skill-doctorand turn off skills you never invoke. - Move any multi-step procedure left in CLAUDE.md into a skill, and split skills longer than a screen or two into reference files.
- Rewrite your own tools' descriptions without worked examples, and defer the rarely used ones.
Sources
- Anthropic, "The new rules of context engineering for Claude 5 generation models" (Thariq Shihipar, July 24, 2026): https://claude.dev/blog/the-new-rules-of-context-engineering-for-claude-5-generation-models/
- Anthropic, "Effective context engineering for AI agents": https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
- Claude Code docs, "How Claude remembers your project" (CLAUDE.md size, auto memory, AGENTS.md,
/doctor prompt-audit,/doctortrims): https://code.claude.com/docs/en/memory - Claude Code docs, "Best practices for Claude Code": https://code.claude.com/docs/en/best-practices
- Claude Code docs, "Skills" (supporting files, listing budget,
/doctorcheckup,claude doctor): https://code.claude.com/docs/en/skills - Claude Code docs, "CLI reference" (
claude doctor): https://code.claude.com/docs/en/cli-reference - Claude Code docs, "Explore the context window" (what survives compaction): https://code.claude.com/docs/en/context-window
- Claude Code docs, "Commands" (
/skill-doctor): https://code.claude.com/docs/en/commands - Claude API docs, "Tool search tool": https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool
- Claude API docs, "Prompt caching": https://platform.claude.com/docs/en/build-with-claude/prompt-caching
- Claude API docs, "Define tools": https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools
- Claude API docs, "Prompting best practices": https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices
Read next
More practices and workflows- Claude Code
Master Claude Code's 1M Context Window: Rewind, Compact, Clear, and Subagents
Claude Code's 1M token context window opens longer autonomous sessions but introduces 'context rot' -- degraded performance as the window fills. Master four turn-end tools: /rewind to drop bad branches, /compact to summarize and continue, /clear to start fresh with a distilled brief, and subagents to wall off noisy work in their own context.
- Claude
Prompting Claude Opus 5: Trim the Verbosity, Delete the Verification
Claude Opus 5 needs opposite prompting from its predecessors: you prompt for conciseness because effort no longer controls visible length, and you delete verification and double-check instructions because the model already does both. Constrain scope on narrow tasks, cap subagent spawning for cost, and keep thinking enabled at low effort rather than disabling it.
- Claude
Prompting Claude Fable 5: What to Change and What to Delete
Prompt Claude Fable 5 with less, not more: brief instructions now beat enumerated rule lists, and old skills written for prior models can degrade output. Use effort as your main cost control, expect longer turns, ground progress claims in tool results, and configure fallback to Opus 4.8 for safeguard refusals.
- Claude Code
Claude Code Subagent Patterns: 10 Reusable Agent Definitions
A Claude Code subagent is a delegated worker with its own context window, defined as a markdown file with YAML frontmatter in .claude/agents/. Subagents can edit files when you grant Edit or Write, nest three layers deep by default, and run 20 at a time. These 10 definitions cover the highest-value delegations.
- Claude Code
Claude Code Adds Configurable AGENTS.md Support
Claude Code 2.1.277 adds AGENTS.md support through a built-in mod. By default Claude Code reads AGENTS.md when a project has no CLAUDE.md or CLAUDE.local.md, and /config changes the behavior. Since 2.1.281 it also works on Amazon Bedrock, Google Vertex AI, Microsoft Foundry, LLM gateways, and with telemetry disabled.
Frequently Asked Questions
What is context engineering for Claude 5 models?
Context engineering is assembling everything Claude reads besides your prompt: the system prompt, CLAUDE.md files, skills, memory, tool definitions, and references. For Claude 5 models the direction is less standing instruction and more judgement, with detailed guidance stored in skills and files that load only when a task needs them.
How long should CLAUDE.md be for Claude 5 models?
Keep each file under 200 lines, the target in Claude Code's memory docs, and spend those lines on gotchas Claude cannot see in the repo. Cut directory layouts, dependency lists, and architecture overviews; the /doctor checkup in Claude Code proposes exactly those cuts for a checked-in CLAUDE.md.
Is claude doctor the same as /doctor?
No. Anthropic's blog post credits claude doctor with rightsizing skills and CLAUDE.md files, but the current docs split the jobs: claude doctor in a terminal runs read-only installation and settings diagnostics, /doctor inside a session trims CLAUDE.md, and /doctor prompt-audit flags instructions written for older models.
Should I still put examples in prompts for Claude 5 models?
For output format and tone, yes: Anthropic's prompting docs still recommend a few well-chosen examples. For tool use, the Claude Code team found that examples constrain the newest models to a narrow exploration space, so design expressive parameters, such as an enum of allowed states, instead of listing worked examples.
Do I still need to write memories into CLAUDE.md myself?
No. Claude Code's auto memory saves your preferences, corrections, and project context on its own. Auto memory is on by default in local sessions. Claude loads the first 200 lines or 25KB of its MEMORY.md index at the start of each session and reads the topic files on demand.