Patterns, Anti-Patterns & Troubleshooting

Most Claude Code frustration is not random. It clusters into a small set of recurring failure patterns, and once you can name the pattern you already know the fix. The skill this lesson teaches is diagnosis: read the symptom, trace it to the root cause, apply the specific remedy — and stop reaching for the two reflexes that usually make things worse, restarting from scratch and arguing with Claude in conversation.

There is a structure under almost every failure. Claude Code is an agent driving a context window (a finite token budget that holds your conversation, files, and tool output) under a permission system, kept honest by git and checkpoints, and configured by CLAUDE.md, settings, and hooks. When something goes wrong, it is usually one of these four substrates straining:

The rest of the lesson is a tour of the specific patterns inside each, paired with the exact command or config change that fixes it.

The single most common failure is context pollution — the window fills with material that competes with the task at hand, and answer quality drops. Two patterns dominate.

The kitchen-sink session. You start a session to fix a bug, then — without clearing — pivot to a refactor, then ask about deploy config, then debug a test. Each unrelated task dumps files, logs, and tool output into the same window. By the fourth task Claude is reasoning over a soup of irrelevant context and starts conflating things. The fix is mechanical:

/clear   ← run this between unrelated tasks

/clear empties the context window for a clean slate (your prior conversation is still reachable via /resume). One coherent task per session keeps quality high. This is the antidote to the kitchen-sink anti-pattern.

The correction spiral. You ask for something, the result is wrong, so you correct it. Still wrong, correct again. Three corrections later you are deep in a thread where every turn references the previous mistake, and Claude is now anchored on the bad path. Piling on more corrections rarely recovers it — each one adds noise. The fix is to stop and restart the task with one better prompt:

/clear
# then a single, complete prompt that states the goal, the constraints,
# and what "done" looks like — instead of five patches to a bad first try

A clean window plus a well-specified single prompt almost always beats a long correction chain. If a task has gone three rounds without converging, that is your signal to reset rather than push.

Two failures look like Claude "disobeying" but have very different root causes — and different fixes.

Symptom: Claude ignores a CLAUDE.md rule. You wrote the rule, Claude read the file, and it still does the wrong thing. The usual root cause is that CLAUDE.md is too long. CLAUDE.md is delivered as context, not as a system prompt, so compliance is advisory — and a bloated file buries the important rule in noise until it gets lost. Two fixes, in order of strength:

• Prune it. Target under ~200 lines. Every line should answer "would Claude make a mistake without this?" If Claude already does something correctly, delete the rule about it. Tighter files get followed better.
• Convert it to a hook. If the behavior must be guaranteed (run the linter on save, block a forbidden pattern), move it out of advisory CLAUDE.md and into a hook — a shell command wired to a lifecycle event in settings.json. Hooks are deterministic; CLAUDE.md is a suggestion.

Symptom: a boundary you stated is lost after compaction. Early in a session you said "never push to main," and hours later — after a /compact — Claude pushes anyway. Root cause: spoken boundaries live in the context window, and compaction can summarize them away, silently, with no error. The fix is to encode the guarantee where it can't be dropped — a deny rule in settings.json:

{
  "permissions": {
    "deny": [
      "Bash(git push *)",
      "Bash(rm -rf *)"
    ]
  }
}

A deny rule is re-evaluated on every tool call and overrides the active permission mode, so it cannot be compacted away. The principle: advice goes in conversation/CLAUDE.md; hard guarantees go in deny rules.

Symptom: a session throws a 400 error on resume and won't recover. You /resume a session and immediately hit a persistent HTTP 400 — and it keeps happening. The usual culprit is image accumulation. Pasted images and screenshots are stored at full resolution inside the session's JSONL transcript; enough of them eventually push the request past a hard limit, producing permanent 400s on resume (this is the behavior behind issue #34025). Chrome MCP screenshots are an especially heavy offender for token drain (#27869). The fix:

• Start fresh with /clear rather than fighting the broken transcript, and
• Manage screenshots going forward — don't let visual artifacts pile up in one long session; /clear or /compact a session that has accumulated images before it breaks.

Symptom: an /add-dir file is missing from @ autocomplete. You added a directory with /add-dir (or --add-dir), but when you type @ to reference a file inside it, the file doesn't appear in the completion list. This is a known bug (#5605), not a configuration error on your end. The fix is simple: type the full path manually after @ instead of relying on Tab completion. (Related quirk: Tab completion doesn't expand ~, so spell out home paths too.)

Two install-layer failures account for most "it's not working" reports.

Symptom: Claude is billing/acting on the wrong account — a Console API key is overriding your subscription. If ANTHROPIC_API_KEY is set, it takes precedence over your subscription OAuth login. So if you logged in with your Pro/Max plan but a stray ANTHROPIC_API_KEY lives in your shell profile, Claude Code quietly uses the Console key instead. The fix is to unset it so auth falls back to your subscription:

unset ANTHROPIC_API_KEY     # current shell
# and remove it from ~/.zshrc / ~/.bashrc if it's written there

As a rule, don't write ANTHROPIC_API_KEY to your shell profile — it exposes the key to every child process and causes exactly this precedence surprise.

Symptom: Claude Code isn't updating to the latest version. Native installs auto-update in the background, but Homebrew, WinGet, and Linux package managers do NOT — they only move when you tell them to. If claude --version is stuck, run the manual upgrade for your installer:

Run claude doctor to see the last update attempt and confirm which install method you're on.

These are the highest-blast-radius traps — the ones where the wrong assumption costs you real work or real safety.

bypassPermissions is for isolated containers only. --dangerously-skip-permissions (= bypassPermissions mode) disables every permission check — with one narrow circuit breaker: per the official permission-modes docs, removals targeting the filesystem root (/) or your home directory (~), like rm -rf / or rm -rf ~, still prompt as a safeguard against accidental model error. Everything else runs without asking. It exists for sandboxed containers and disposable VMs — ideally without network access — where there is nothing valuable to wreck. Running it in a real working directory means Claude can edit anything, run anything, and delete almost anything without asking. The flag name is the warning.

Checkpoints do NOT cover bash file changes — git does. Claude Code snapshots every file edit it makes through its own edit tools, so Esc Esc / /rewind can restore those. But changes made by bash commands — rm, mv, git reset --hard — are not checkpointed. If Claude (or a script it ran) deletes a file via the shell, rewind won't bring it back. The real safety net for shell-level changes is git: commit often so you always have a restore point that doesn't depend on the checkpoint system. (Checkpoints are also local to the session and separate from git, and cover file changes only — not database or API side effects.)

/btw can't investigate — it's context-only. /btw <question> answers a side question from the existing context without bloating your history — but it has no tool access. It can't read new files, run commands, or search the codebase. If your side question actually needs investigation ("is this function called anywhere?"), /btw will answer from memory and may be wrong. Use a subagent instead: it runs in isolated context with tools, does the real investigation, and reports a summary back without polluting your main thread.

When a symptom doesn't map cleanly to a known pattern, reach for the built-in diagnostics. Each answers a different question.

A practical order of operations:

1. Start with claude doctor (or /doctor, then f to fix) — it catches the majority of install/auth/update problems and can repair them.
2. If behavior is wrong, not broken, relaunch with --debug scoped to the relevant category (api, hooks, ...) and read the trace; add --debug-file to capture it.
3. For memory/performance issues, /heapdump.

claude doctor                    # quick health + last update attempt
claude --debug "api,hooks"       # trace API + hook activity
claude --debug "!statsig" --debug-file /tmp/cc.log   # everything except statsig, to a file

One transient message deserves a special note: in auto mode, "cannot determine safety" is not a verdict or a failure — it's a transient hiccup in the background safety classifier. Don't change your config over it; just retry.