Skip to content
Mastering Claude

Home / A structured installation

A structured installation8 minApplication

Your instructions age with the models

An instruction written to work around a flaw in an older model stays in the file when the model changes and becomes noise the model keeps reading, and /doctor prompt-audit spots these instructions so you can reread them one by one.

A CLAUDE.md rule, a skill description or a custom command often starts from a flaw observed on a given model. The model changes generation, the rule stays in place, and nobody rereads it as long as it does not cause an error.

A documented example

The official guide to migrating to Claude Opus 5.5 gives one. Teams had added an instruction to get progress updates during long tasks, along the lines of "after every three tool calls, summarise your progress". Since Claude Opus 4.7, the model gives more regular progress updates on its own, and the guide advises trying to remove this scaffolding. The instruction is not wrong: it has become unnecessary, and the model keeps reading it every session. On Claude Opus 5.5, these progress updates arrive in thinking blocks, as the lesson on moving to Opus 5.5 details.

What a CLAUDE.md sentence does not set

Thinking effort follows the same logic. In Claude Code, its level is set with /effort, with the --effort option at launch, with the CLAUDE_CODE_EFFORT_LEVEL variable or with the effortLevel key in the settings. A CLAUDE.md sentence that asks the model to think harder steers the model within the chosen level, it does not change that level. The expressions think or think hard pass as ordinary text, ultrathink being the recognised keyword, as the lesson on quick terminal moves details.

A setting ages like an instruction. An effortLevel key placed at the top level of the user settings keeps applying to Claude Opus 5, to Claude Fable 5.1 and to earlier models, but does not count for Claude Opus 5.5, which starts at medium until a level has been chosen for it with /effort, with the --effort option, with the CLAUDE_CODE_EFFORT_LEVEL variable or with the effortLevel key specific to that model in modelSettings. The same effortLevel key placed at the top level of the project settings or the managed settings does apply to all models without exception.

The command that spots these instructions

Since Claude Code version 2.1.283, released on 25 September 2026, /doctor prompt-audit, also available as /checkup prompt-audit, rereads the CLAUDE.md, CLAUDE.local.md and AGENTS.md files, as well as the rules, skills, commands, subagents and output styles stored under .claude/ and ~/.claude/. It looks for instructions written for older models, references to files or commands that do not exist, and files that contradict each other. The commands page says it accepts a path as an argument.

/doctor prompt-audit
/doctor prompt-audit .claude

The report lists its findings and proposes changes, and nothing changes in your files until you ask to apply them. The version's changelog states that outdated paths and commands, and files that contradict each other, come first in the report, and that the thinking keywords documented by Claude Code are preserved. A finding flags a risk of obsolescence, not a proven error: each instruction is reread against the current documentation of the model being called before it is removed or kept. The AGENTS.md file falls under the same audit.

Figure 1

A progress update instruction, before and after review

Written for a model earlier than Claude Opus 4.7
## Long tasks
After every three tool calls,
summarise your progress in two lines.
After a trial without the instruction
## Long tasks
(progress update instruction removed after a
trial: the model gives them on its own)
On the left, a CLAUDE.md section written for a model earlier than Claude Opus 4.7; on the right, the same section after a trial without the instruction.
Calibrate it yourself

A team runs /doctor prompt-audit in its repository, on Claude Code version 2.1.283. The report flags a rule in the CLAUDE.md file that asks for a progress summary after every three tool calls, links it to an instruction written for older models and proposes deleting it. The team reads the report and closes the session.

Write in one sentence what this situation establishes, and in one sentence what it does not establish.

What to remember
  • An instruction born from a model's flaw survives the change of model and keeps being read every session, even once it has become unnecessary.
  • The migration guide advises trying to remove the instructions that forced progress updates, since the model gives them on its own from Claude Opus 4.7.
  • In Claude Code, the effort level is set outside CLAUDE.md, and an instruction sentence steers the model without moving that level.
  • A top-level effortLevel key in the user settings has no effect on Claude Opus 5.5.
  • The audit proposes changes and applies none without an explicit request.
Do this now

Run /doctor prompt-audit in your project, pick a single finding that targets an instruction written for an older model, find in the documentation of the model you call the behaviour that instruction assumed, then decide to keep it or remove it before asking for anything to be applied.

Check the source

Every datable claim in this lesson links here to the public text behind it. A source that does not open proves nothing.