# Claude 5.5 prompt audit: the bad lines weren't there

> Anthropic's 5.5 guides name four prompt habits that now backfire. /doctor prompt-audit found none in my repo - it found subagents for another workspace.

URL: https://bartlomiejkrupa.dev/articles/claude-5-5-prompt-audit/
Published: 2026-09-30
Tags: claude-code, claude-md, prompt-audit, sonnet-5-5, opus-5-5, context-engineering
Summary: Anthropic's 5.5 guides name four prompt habits that now backfire. /doctor prompt-audit found none in my repo - it found subagents for another workspace.

Anthropic's prompting guides for Claude Sonnet 5.5 and Opus 5.5 name four habits that now make results worse: discouraging tool use, asking for reasoning in the response, telling the model not to think, and injecting harness text after every tool result. I ran `/doctor prompt-audit` on this site's Claude Code config to find them. It found **zero** of the four, and **14 findings** of a different kind. The worst: three of my four subagents were still briefed on a workspace this repo has never been part of.

## The four habits the 5.5 guides retire

Each row below traces to a sentence in Anthropic's own guides. The models differ, so the table says which guide covers what.

Three terms first:

- **Harness** is the program that runs the model and feeds it tool results - Claude Code, or your own agent loop.
- **Effort** is the API setting that controls how much the model thinks. Both guides say lowering it cuts thinking more reliably than a prompt instruction does.
- **`between_tools`** is Sonnet 5.5's lowest thinking setting: no thinking up front, only short notes between tool calls.

| Habit | What goes wrong | Guide | Fix |
| --- | --- | --- | --- |
| "Only use tools when strictly necessary" / "minimize tool calls" | The model answers from training knowledge when a search would catch details that changed | Sonnet 5.5 | Remove the line; add one saying when to check current sources |
| "Include your reasoning in the response" | Can be declined as a `reasoning_extraction` refusal; server-side fallback won't retry it | Sonnet 5.5, Opus 5.5 | Remove; read reasoning from `display: "summarized"` thinking blocks |
| "Don't think" | Sonnet 5.5 with `between_tools`: more likely to write internal XML tags into visible output. Opus 5.5: thinking can't be turned off, so remove the rule "either way" | Sonnet 5.5, Opus 5.5 | Lower `effort` instead of asking in prose |
| Harness text after every tool result (a token countdown, per-step instructions) | Sonnet 5.5 can treat a genuine user message typed mid-task as a possible prompt injection | Sonnet 5.5 | Put user text in the user turn, after the last `tool_result`; no countdown in interactive sessions |

The last row is not a prompt line. The harness adds that text, and that's why a grep of your `CLAUDE.md` never finds it. The Opus 5.5 guide even points the other way for multiagent setups: there it recommends the harness append an elapsed-time line like `elapsed 340s / 1200s` so a team of agents paces itself. Whether harness text after tool results hurts depends on the model. The two lines most likely to sit in your own files have their own notes: [don't tell Sonnet 5.5 to minimize tool calls](/notes/dont-discourage-tool-calls) and [why "show your reasoning" gets refused](/notes/reasoning-extraction-refusal).

This is the third piece in a thread. [Why agents ignore your CLAUDE.md](/articles/why-agents-ignore-your-claude-md) argued from mechanism that more instructions don't buy more control. [A 129-rule CLAUDE.md replied like an empty one](/articles/claude-md-adherence-bench) measured it. This one checks what an official audit tool actually catches.

## What /doctor prompt-audit does

Claude Code 2.1.283 (September 25, 2026) added the command. The changelog describes it as auditing "your CLAUDE.md files, skills, agents and commands for prompting patterns written for older models". The same release says "stale paths, stale commands and contradicting instruction files now lead the report".

```text
/doctor prompt-audit
```

`/checkup prompt-audit` is the same command. The audit targets whatever model your session runs on - Opus 5.5 on Claude Code 2.1.285, in my case - and returns two things: a report with `file:line`, pattern, reason and confidence per finding, and a proposed diff (a line-by-line patch you can take piece by piece). Nothing gets applied unless you ask. Because a model does the reading, a maintainer weighing it up in [issue #1500](https://github.com/fmanimashaun/claude-skills/issues/1500) concluded "it cannot be a CI gate: it needs the CLI and a model call".

## The before report

Scope: `CLAUDE.md`, `AGENTS.md` and their imports, 4 subagents and 14 project skills. It also scanned the 66 installed skills under `~/.claude` in report-only mode. The full raw report, before and after, is in [this gist](https://gist.github.com/bartek-890/b6f0d1ad2d2603072a4857c7004fbb0a).

| Group | Findings |
| --- | --- |
| Dated prompt text (older-model habits) | 4 |
| Config rot (stale paths, commands, contradictions) | 10 |
| Tool descriptions / request code | not applicable |
| **Total** | **14** (10 with a proposed fix, 4 flag-only) |
| The four 5.5 habits above | **0** (project, `~/.claude`, 66 installed skills) |

The high-confidence findings were all rot:

- **Three subagents described another workspace.** `code-reviewer`, `explorer` and `researcher` (the fourth, `content-reviewer`, was written for this site) were copied from a multi-repo setup, and each still named its repos: `b24`, `react_panel`, `b24depot`, `product_ops`. None of those exist here. The reviewer was told to check PHP 8.4 conventions and GraphQL contracts on an Astro site.
- **The reviewer diffed against a branch that doesn't exist.** It ran `git diff master...HEAD`, but this repo's default branch is `main`.
- **Two skills called commands that were never installed.** `grill-me` consisted of a single line, "Run a `/grilling` session", and no `grilling` skill exists. `decision-mapping` referenced `/grilling`, `/domain-modeling`, `/prototype` and `/to-prd`, also absent. Both arrived through `skills-lock.json` without the sibling skills they call.

Medium-confidence findings covered the older-model habits the audit guide lists: line caps like "Keep the whole response under ~60 lines", a 240-character paragraph cap, and an all-caps "You NEVER edit files" in an agent whose tool list already can't write. One cross-file contradiction also turned up: the `storytelling` skill claimed `humanize-copy` rewrites in place, while `humanize-copy` itself defaults to a sibling file.

## The fix

Ten findings came with a proposed hunk, and I took all ten. The largest one:

```diff
-description: Reviews a diff or files in a fresh, clean context. Use after completing an implementation, before commit/MR, to review changes in any repo (b24, react_panel, b24depot, product_ops) or cross-repo work. Read-only.
+description: Reviews a diff or files in a fresh, clean context. Use after completing an implementation, before commit/PR. Read-only.
-1. ... otherwise run `git diff master...HEAD` ...
+1. ... otherwise run `git diff main...HEAD` ...
-Keep the whole response under ~60 lines.
+The main session reads this, so report findings only - no restated diff, no preamble.
```

Four findings stayed flag-only by design, for example `AGENTS.md` importing `CLAUDE.md`, which loads the same text twice if both files are read. The audit leaves a duplicate alone when the copies agree.

## The after report

| Finding | Status |
| --- | --- |
| 3 subagents briefed on another workspace | fixed |
| `git diff master...HEAD` | fixed (`main`) |
| 4 uninstalled slash commands | fixed (removed, or repointed to skills that exist here) |
| Line and character caps, all-caps rule | fixed |
| `storytelling` / `humanize-copy` contradiction | fixed |
| `content-reviewer` "~50 lines" cap | **missed by the before run**, caught by the re-scan, fixed |
| 4 flag-only items | unchanged |

`content-reviewer` carried the same line-cap pattern as the other three agents, and the first pass walked past it. Run the audit twice before you trust a clean report - [the rule, in one note](/notes/run-prompt-audit-twice).

I ran the same audit on the [leanharness](/articles/claude-code-harness-starter) template, the minimal harness from the earlier benchmark. It had zero of the four 5.5 habits too, and one real leak: the Non-negotiable scope rule named `src/billing.js`, a file that exists only in the benchmark's fixture, in the `CLAUDE.md` every user installs. It is now a placeholder the benchmark fills in, so the measured install stays byte-identical. The [template's audit record](https://github.com/bartek-890/leanharness/blob/main/docs/prompt-audit.md) lists what was fixed and what stays on purpose.

Three of the fixed skills - `grill-me`, `decision-mapping` and `edit-article` - are copied in from upstream repos and pinned by `skills-lock.json`. Their hashes no longer match upstream, so the next skills update will quietly put the old text back. For those three, the durable fix belongs upstream or in a fork.

## What this changes about "more instructions, more control"

The 5.5 guides make the familiar case: lines written to push an older model harder now push the new one the wrong way. On this repo, nobody had written those four lines. The instructions doing damage were plain, calm and **wrong**, and nothing announced it:

- A reviewer told to judge PHP conventions raises no error. It reviews an Astro diff against PHP rules and reports back.
- A skill that says "run `/grilling`" never fails loudly. The model improvises something grilling-shaped.

Instruction count feels like control because each new rule looks like coverage. Each one is also a claim about your repo that can go stale, and nothing re-checks it unless you run something that does. The audit's ordering says the same thing: stale paths, stale commands and contradictions lead the report, ahead of the prompt-style patterns.

## Run it yourself

1. Update Claude Code to 2.1.283 or later, then run `/doctor prompt-audit` in the repo.
2. Save the raw report before you change anything. It's your only before snapshot.
3. Take the high-confidence hunks first. They're the ones the repository itself contradicts.
4. Run it again after the fixes. Mine caught a line the first pass missed.

Then read [Why agents ignore your CLAUDE.md](/articles/why-agents-ignore-your-claude-md) for why the file you're left with should stay short, and [how effort and thinking settings work](/articles/claude-effort-thinking-fast-mode) for the lever that replaces "don't think".

Sources:
- Prompting Claude Sonnet 5.5: https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-sonnet-5-5
- Prompting Claude Opus 5.5: https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5-5
- Claude Code changelog - 2.1.283: https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md
- Evaluate /doctor prompt-audit against the skills, agents and commands we ship (#1500): https://github.com/fmanimashaun/claude-skills/issues/1500
- Raw /doctor prompt-audit report for bartlomiejkrupa.dev, before and after: https://gist.github.com/bartek-890/b6f0d1ad2d2603072a4857c7004fbb0a
- leanharness - prompt audit of the template: https://github.com/bartek-890/leanharness/blob/main/docs/prompt-audit.md