Rules that once had to be hard-coded can now be deleted

Take one real rule. Here's what Claude Code's early system prompt said about comments:

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.

This rule was necessary at the time. When Claude Code first launched, the top priority was keeping it from causing damage — like deleting files. So the guidance had to be written extremely firm, even when it wasn't always right. The comments rule was exactly that kind of not-always-right rule: some users have their own documentation habits, and some genuinely complex code deserves multi-line comment blocks. But the models back then wouldn't hold back without it — they'd write comments that were wrong nine times out of ten. Even knowing the rule would misfire on some people, it was the only option.

The new generation of models has good enough judgment that this misfiring is no longer necessary. The system prompt now covers the same ground in a single line:

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

Those old guardrails existed to head off the worst-case outcome. Once the worst case stops happening, the guardrail should come down, letting the model lean on surrounding context and its own judgment instead.

Three conflicting instructions, landing in a single request

There's a more practical reason for cutting rules, too. Reading through their own team's Claude Code conversation logs, they found that a single request often surfaced several instructions fighting each other at once.

All three lines get stitched into the same context and sent in together. These three lines are Anthropic's own illustrative example, not an actual quote. Image: Thariq / X

Claude can usually guess what you actually want. But it has to reconcile these conflicting lines before it can decide what to do. You might think tacking one more constraint onto a skill is free — in reality, every one you add can collide with another one somewhere else, and reconciling them takes real effort.

That's also why cutting 80% didn't cost any score: what got removed wasn't just filler text, but the conflicts that text created.

Six outdated habits, and what replaced them

Thariq listed six practices that have been passed down for years and no longer hold up, and gave a replacement for each:

The first pair is covered above; the other three each get their own section. Let's clear the two lighter ones first.

Repeat yourself → simple tool descriptions

Earlier Claude models sometimes needed the same thing said several times before it stuck, and they paid more attention to instructions near the end of the context than near the beginning. So the system prompt used to explain how to use a tool once, and the tool's own description explained it again. Those duplicated explanations are gone now — how to use a tool lives only in that tool's description.

Memory in CLAUDE.md → auto-memory

The old workflow was to hit the # shortcut and have whatever you wanted remembered get written into CLAUDE.md automatically. Now Claude saves memories about this work and about you on its own — you don't have to stuff them into a file by hand.

Skip the examples — design the tool itself

Teaching a model to use a tool used to have one iron rule: give it plenty of examples. Now they've found that, for this newest generation of models, examples do the opposite — they box the model into a narrow slice of the possibility space. Show it a handful of use cases, and it'll keep circling back to those same handful.

The same TodoWrite tool's description, before on the left and after on the right. The sentence on the right trails off into an ellipsis, meaning the current description continues past what's shown here. Image: Thariq / X

What replaces examples is interface design: making the tool, script, or file itself self-explanatory. The key is in the parameters — the values a parameter can take should communicate the usage on their own.

TodoWrite is the example. Its status field takes only three values: pending, in_progress, completed. Just having that enum there tells the model how to use it: a task has exactly these three states, no more, no fewer. The requirement doesn't need an example either — one line, "keep only one task in in_progress at a time," says it all.

That's a shift from a year ago. Anthropic's 2025 piece on context engineering said "providing examples, or few-shot prompting, remains a widely recommended and endorsed best practice" — and back then, the only thing they warned against was stuffing a prompt with a long tail of edge cases. One model generation later, examples themselves went from a recommendation to a liability.

You don't need it all upfront — load it when it's needed

Claude Code was originally built just for coding, so its system prompt was packed with detailed instructions on how to do code review and how to do verification. Most of the time none of that was needed, but when it was, it was critical — so it just sat there taking up space regardless.

The current fix is to make it appear on demand: code review and verification have each been moved into their own separate skill, which Claude pulls up only when it needs to. This approach is called progressive disclosure: load whichever piece is actually needed, and nothing else.

The same approach applies to tools. Claude Code now has far more tools wired up than before, and some of them are lazy-loaded: normally, only their name sits in the context, and the model has to call ToolSearch to pull the full definition before it can use one. Without a search, a tool costs one line for its name; its full, often thousand-word description never loads — and it's precisely because it doesn't load that they can afford to wire up more tools in the first place.

Your own CLAUDE.md and skill files should be organized the same way. Thariq called out a common mistake: many people cram every practice they might ever need into a single file, on the theory that if it's not written down, Claude won't find it. The right move is to split it into a file tree that loads on demand.

A spec doesn't have to be a document — it can be code, or a test suite

First, what "spec" means here: it's what you write for Claude describing "what I want this to look like." People have traditionally written it as a markdown document — Claude Code's plan mode has always leaned heavily on files like that — and storing a spec in the codebase for a long-running project to reference is the same idea. Both still work, but you can go further now: Claude can handle far more complex references.

He's more direct about why code-based references work better in A Field Guide to Fable — another piece by the same author, Anthropic's official usage manual for Fable 5. Some things you can't describe: maybe you lack the vocabulary, or maybe describing them precisely would just take too long. In that case, the best move is to hand over a reference, and the best reference of all is source code. Back in this piece, his example is: for the same design, giving Claude an HTML draft usually works far better than a written description or a screenshot.

You can use @ to bring files in as references… In general, favor things in code, because it gives Claude clear, high-fidelity instructions in a language it knows extremely well. — Thariq Shihipar, "The new rules of context engineering for Claude 5 generation models" (the ellipsis marks a separate passage in the original)

Context is built from six layers — what goes in each one

Put the previous points together and you get a layered placement guide. First, here's how what Claude actually reads in a single request gets assembled:

The line you typed sits at the top; below it, in order, come references (files brought in with @, specs, design drafts, codebases, artifacts), the system prompt, CLAUDE.md, skills, and memory. Image: Thariq / X

Of these six layers, the top one — the line you just typed — is yours in the moment, and the bottom one, memory, is stored by Claude on its own; neither needs your arranging. The four layers in between are the ones you actually have to set up:

Want to trim things down? Start by running a checkup command

Anthropic built this whole approach into a command for trimming your skills and CLAUDE.md. The original's description of it: "We've baked these best practices into claude doctor — run it in Claude Code with the /doctor command."

The two entry points aren't quite the same. Testing this on Claude Code 2.1.220: the command-line claude doctor's help text says it "checks whether your Claude Code installation is healthy, reads settings files in the current directory, and doesn't prompt for trust" — and adds at the end that for a full checkup that can actually fix problems, you should run /doctor inside a session. So if you want help trimming your skills and CLAUDE.md, run the slash command inside a session, not the CLI one.

These six replacements rest on one premise: "this new generation of models has better judgment," and the original names Opus 5 and Fable 5 specifically. If your workflow runs on an older model, or on a different provider's model, whatever those guardrails were originally blocking might still be a problem — test in a small scope before you start deleting. The original doesn't elaborate on this point.

When Claude Code first launched, job one was keeping it from causing damage, so the rules were written extremely rigid — even knowing some people would get caught in the crossfire. The comments rule was one of those: some people keep their own documentation habits, and genuinely complex code deserves multi-line comments — but back then, without the rule, the model would churn out a pile of wrong comments, so it got a blanket ban instead.

The new line hands the reference point over to the surrounding code: comment density, naming, and idiom all follow the neighbors. Since the reference changes with the project, the rule never needs rewriting.

There's a more practical reason for cutting rules, too. Digging through their own team's Claude Code conversation logs, they found several conflicting instructions often showed up in the same request at once.

Thariq listed six practices, passed down for years, that no longer hold up — and gave a replacement for each.

Put it all together and you get a placement guide. Of the six layers, the top one — the line you just typed — is yours in the moment, and the bottom one, memory, is stored by Claude on its own. What actually needs your arranging sits in between.

If you want to start, run a checkup first: type /doctor in a Claude Code session, and it'll apply this standard to suggest trims for your skills and CLAUDE.md. Tested on version 2.1.220: the command-line claude doctor only checks whether the install is healthy — the full checkup has to run inside a session.