Boris Cherny, the engineer behind Claude Code, told Y Combinator to delete your CLAUDE.md, skills, and hooks when upgrading to Opus 5. He's 73% right. But deleting everything treats a quality problem as a quantity problem.

The 73% Stat

A deterministic analysis of 30,000 public repositories with agent instruction files found that only 27% of the content actually instructs. The rest is scaffolding: headings, restated context, examples, and prose that arranges the file without telling the model to do anything. An ETH Zürich study confirms this: descriptive overviews don't improve results and add over 20% to inference cost.

Why Opus 5 Behaves Differently

Three mechanisms compound to make your old instructions misfire:

  1. Wider instruction retrieval: Opus 5 reaches for instructions over a wider range, so vague rules that used to sit dormant now fire on tasks they were never written for. A vague rule names nothing concrete to bind to, so the model fills the gap with its own judgment.

  2. Baked-in LLM-as-a-judge: Opus 5 evaluates and re-checks its own output by default. Your old "verify / double-check" lines stack on that, causing over-verification.

  3. Long-horizon tasks: Opus 5 runs long-horizon tasks (auto mode). The longer the trace, the more the model's own generated steps crowd out your instructions, and the weakest go first.

Combine these and a CLAUDE.md that worked on 4.x can feel broken on 5. Delete the file and the noise disappears, which is why "just delete" feels like it works.

The Blunt Tool of Deletion

Boris's method is ablation: delete the file, then add a line back only when a failure keeps recurring. That works for Anthropic, which has near-unlimited budget and time. For you, it's a rediscover-by-failure loop that ships production failures to learn what a static read hands you for free.

Deletion can't see which rules are load-bearing. A rule that names the exact construct gets followed with roughly a 10.9x odds ratio over a category. Conflicts resolve silently: Opus 5 follows the latest instruction and drops the other, so the losing rule reads as flakiness. The add-back loop only catches the third defect—bloat—and quietly puts the vague and conflicting rules back.

There's also a category error: skills and hooks are not instructions. A hook is a deterministic gate. It refuses an action outright, not by asking the model to weigh a sentence. A deny-rule or compliance check doesn't get less necessary because the model got more capable. Enforcement never rode on the model's judgment. Cut the prose, keep the gate.

What to Do Instead

Read the file, don't shrink it. Opus 5 is more punishing when it meets faulty instructions. Fix the rules that misfire, write the rest so a literal reader cannot misread them, and repeat.

Fix What You're Seeing

  • Long answers: Instruct for brevity per surface. One line for chat replies, one for step-by-step narration, one for files it writes to disk. Effort changes thinking depth, not output length.
  • Scope creep: State scope in one line. Let it make routine calls itself, checking in only when two readings lead to materially different work. Use a write-path allowlist to refuse edits outside the task's files.
  • Over-obeying a limiter: A hedge like "only report high-severity issues" gets followed literally and under-reports. Ask for everything and filter in a second pass.
  • Compulsive self-checking: Delete lines like "double-check your answer" or "use a subagent to verify." Opus 5 verifies its own work without being told; those instructions cause over-verification.
  • Old 4.x instructions misfiring: Target the classes Opus 5 inverted: verification prompts, "be conservative" hedges, "do not think" rules, effort defaults. Test each and keep what still binds.
  • Thrashing on conflicting rules: In a contradiction, Opus 5 follows the latest rule. Position decides which. Find the contradiction and remove it.
  • Vague rule misfiring: Name its construct or scope it to a path so it stops loading on every turn.
  • Over-eager subagents: Cap it. Delegate only large, genuinely independent tracks. Never spin up a subagent to verify your own work.
  • Confident wrong assumptions: Steer it to state assumptions and flag gaps. Re-run the goal at the finish against a held-out check it never saw. Let it refuse and escalate when it cannot confirm.
  • Effort carried over from 4.8: Opus 5 defaults to high and adds an xhigh tier. If you set effort for 4.8, it stays live. Re-run an effort sweep: low and medium hold quality for most work; xhigh only on demanding agentic runs.

Write Rules It Can Follow

The more interpretation you leave, the more Opus 5 fills the gap with its own judgment. Be specific, be imperative, put one instruction per line. In a controlled experiment, naming the exact construct is what separates "Format with ruff" from "keep the code clean." The latter binds nothing.

The 89.9% Problem

In the same corpus, 89.9% of agent configs carry at least one instruction that never names what it means. A rule like "keep the code clean" reads fine to a person and binds nothing in the model. It's nearly everyone. Those figures are Q2 2026; the Q3 report is in the making.

Action Plan

  1. Run a static analysis on your CLAUDE.md to identify vague or conflicting rules. Tools exist; or read it line by line and ask: "Does this name a concrete construct?"
  2. Delete only the bloat: headings, restated context, examples. Keep the 27% that instructs.
  3. Keep your hooks and deny-rules. They enforce, they don't steer.
  4. Re-test after upgrading. Watch for over-verification, under-reporting, and scope creep.

Do not delete your CLAUDE.md wholesale. That's a sledgehammer. Use a scalpel.