AI Engineering

Overview

This chapter covers:

• The one question that routes a symptom to the right documentation page
• The commands that show what Claude Code actually loaded, rather than what you wrote
• Narrowing a configuration problem in two steps, without deleting anything
• The location and syntax mistakes behind most “my hook never fires”
• Performance, hangs and search failures — and the one command whose output you must not share

Start by routing

Failures split into four groups, and each has its own page. Getting this wrong is how an afternoon disappears: hunting a settings problem in the install guide finds nothing, because nothing is there.

The question that sorts them: how far did it get?

And two commands to run before anything else, because they often answer it for you:

claude doctor    # from your shell — read-only,
                 # and works when claude won't start

/doctor          # inside a session — checks installation, settings,
                 # extensions and context, then offers fixes

/doctor also catches things you would never think to look for: invalid settings files, duplicate subagent names in one directory, and CLAUDE.md content Claude could have derived from the codebase anyway.

Configuration: see what loaded

The rule that saves the most time here: a configuration problem is almost never the content, and almost always the location. The file didn’t load, it loaded from somewhere else, or something overrode it.

So don’t reason about it. Look.

Run /context first, every time. It answers the only question that matters at this stage — is the thing there at all — and the answer forks the whole investigation:

flowchart TB
    C([/context]) --> Q{Is it listed?}
    Q -->|no| L[A location or syntax problem]
    Q -->|yes| W[A wording problem]
    L --> T[Check the traps below]
    W --> M[Be more specific, or enforce it]

If it loaded and Claude still ignores it, no amount of file-moving will help. Adherence drops when an instruction is vague, when two files disagree, or when the file has grown long enough that nothing in it gets much attention — Chapter 6’s territory. And if it must never happen, CLAUDE.md was the wrong tool: permissions and hooks give a guarantee, CLAUDE.md gives guidance.

Narrowing it, in two steps

Don’t start deleting files. Start subtracting whole layers.

claude --safe-mode

Runs with every customisation off — CLAUDE.md, skills, plugins, hooks, MCP servers, custom commands and agents — while authentication, model, built-in tools and permissions keep working. If the problem disappears, it’s one of yours; go back and check them individually. It is also the fastest test for “is a plugin eating my CPU”.

If the problem survives safe mode, subtract your configuration directory too:

cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude

Nothing from ~/.claude, nothing from the project. You’ll get the first-run theme picker — which is how you know it worked — and you’ll have to log in again.

Neither step escapes managed settings. Those come from MDM profiles, registry policy and managed-settings.json, all outside the configuration directory, and a clean session fetches server-managed settings again as soon as it has credentials. If a problem survives both steps, /status is the next call.

The traps

Most configuration surprises are one of a small number of mistakes, and they share a shape: the file is fine, it’s just not where something reads it.

Two more worth carrying. An array where a string belongs is a schema error, and Claude Code rejects the whole settings file — so one bad matcher can silently disable every hook you have. And a connected MCP server listing zero tools is a different failure from one that won’t connect: reconnect from /mcp, and if it stays at zero, claude --debug=mcp puts the server’s stderr in ~/.claude/debug/<session-id>.txt.

Performance, hangs and search

High CPU or memory — the ladder is /compact, restart between major tasks, put build directories in .gitignore, then --safe-mode to find out whether it’s yours. If it survives all four, /heapdump writes a snapshot and a diagnostics file to your Desktop.

The .heapsnapshot file contains every string in the process — your whole conversation, and your credentials. Never attach it to a public issue. The -diagnostics.json beside it carries the statistics with none of the content; that is the one to send.

Auto-compaction thrashing (Autocompact is thrashing: the context refilled to the limit…) means compaction worked and something immediately refilled the window, repeatedly. Claude Code gives up rather than burn calls on a loop. The fix is upstream: read the oversized file in ranges, /compact keep only the plan and the diff, move the work to a subagent, or /clear.

A hang is Ctrl+C, then close the terminal if that fails. Nothing is lost — claude --resume in the same directory picks the session back up.

Search finding nothing — @file mentions, agents and skills all going quiet together — usually means the bundled ripgrep won’t run on your system. Install your platform’s package, then:

{ "env": { "USE_BUILTIN_RIPGREP": "0" } }

claude doctor confirms it: the Search line should show your system binary’s path instead of OK (bundled).

On WSL, search across /mnt/c/ returns fewer results than it should, and claude doctor still reports Search as OK — there is no error to find. Move the project onto the Linux filesystem, or narrow your searches.

Errors

The error reference is a lookup table, not a read. What’s worth knowing in advance is the shape of the four families:

Three knobs behind the retry behaviour, useful on a bad network: CLAUDE_CODE_MAX_RETRIES (10, capped at 15), API_TIMEOUT_MS (10 minutes), and CLAUDE_CODE_RETRY_WATCHDOG=1, which retries 429 and 529 indefinitely.

And one error whose cause is never where you look. This organization has been disabled while your subscription is perfectly active means an ANTHROPIC_API_KEY in your environment is overriding it — often left behind by another tool. Under -p the key is always used when present. unset ANTHROPIC_API_KEY, then check your shell profile so it stays gone.

Install and login

Two checks cover most of it. which -a claude — more than one result is the problem, and the native install at ~/.local/bin/claude is the one to keep. And is ~/.local/bin on your PATH — the usual cause of command not found right after a successful install.

The VS Code extension bundles its own private copy of the CLI and puts nothing on your PATH. If that is all you installed, claude in a terminal is genuinely not there.

For login, the reset is /logout, close, restart. In WSL2, over SSH, or in a container, the browser opens on the wrong host and its redirect can’t reach the local callback — press c to copy the OAuth URL and open it yourself, or fall back to claude auth login.

On macOS, credentials go in the login Keychain; when it’s locked, Claude Code falls back to a file and claude doctor says so with a macOS Keychain is not writable warning. security unlock-keychain fixes it, then /logout and /login moves the credentials back.

Reporting it

/feedback from inside a session sends it to Anthropic directly. Otherwise: GitHub issues for bugs, with your OS, the command you ran and the full error — but account, billing and subscription problems go to support, not GitHub.

And the one that gets forgotten: Claude Code has its documentation built in. Asking it is often faster than searching.

Summary

• Route first. How far did it get — install, configuration, performance, or a specific message? Four groups, four pages.
• claude doctor from the shell, /doctor inside a session. Then /context.
• A configuration problem is a location problem far more often than a content one — so look at what loaded instead of reasoning about what you wrote.
• Narrow by subtraction: --safe-mode, then a clean CLAUDE_CONFIG_DIR. Managed settings survive both.
• The common traps: ~/.claude.json instead of settings.json, an array matcher, skills/name.md instead of name/SKILL.md, .mcp.json under .claude/. One bad matcher rejects the whole settings file.
• /heapdump’s .heapsnapshot contains your conversation and credentials. Send the -diagnostics.json instead.
• WSL search quietly returns fewer results, and claude doctor reports it as fine.
• This organization has been disabled on a live subscription is a stray ANTHROPIC_API_KEY.

Chapter 23 is the capstone: one repository configured end to end, and what to do after this handbook.