When something breaks, run these three commands first

Configuration problems almost always have one of three causes: the file didn't load, it loaded from somewhere else, or it was overridden by another configuration layer. The three-command routine rules these out one by one.

One-line answer

Steps

1. First: /doctor — when you don't know what's broken, start here.OfficialIt runs a one-shot install-and-config checkup: installation health, invalid settings files, unused extensions, same-directory subagent name collisions, and redundant CLAUDE.md content Claude could have inferred on its own (the trim check needs v2.1.206+; the current release 2.1.222 qualifies). When it finds problems it proposes fixes and applies them only after you confirm. If claude won't start at all, run claude doctor in the terminal — it prints a read-only diagnosis without opening a session. While you're at it, note your version: claude --version, or /status inside a session — many fixes come down to version gates.
2. Second: /context — confirm whether "it actually loaded".OfficialIt lists everything occupying the current session's context window, by category: system prompt, built-in/MCP tools, custom subagents and their sources, memory files, skills, conversation messages. Your CLAUDE.md missing from the Memory files list? Then Claude simply cannot see it — check the file's location (subdirectory CLAUDE.md files load on demand only when Claude reads a file in that directory, not at startup). Listed, but Claude doesn't follow it? Then it's a writing problem: instructions too vague, two files contradicting each other, or a file so long it dilutes attention — see CLAUDE.md ignored because it's too long.
3. Third: /mcp — check external servers.OfficialIt lists each configured server's connection status and project approval status. Three common traps: servers in a project-level .mcp.json need a one-time approval — dismiss the prompt and they stay disabled until you approve them in /mcp; server startup failures are often relative paths in command/args (resolved relative to the launch directory); shown as connected but with 0 tools — pick Reconnect first, and if that doesn't help, run claude --debug mcp to see the server's stderr.
4. Follow up by symptom: the targeted-command table.OfficialOnce the trio has narrowed down the category, dig deeper with the matching command:

   Symptom / suspicion	Run	What it tells you
   Hook not firing	/hooks, then claude --debug hooks	Which hooks are registered; not in the list = never read (hooks must live under the "hooks" key in settings.json — there is no standalone hooks file); in the list but not firing usually means a bad matcher (case-sensitive; use "Edit|Write" for multiple tools)
   A setting isn't taking effect	/status + /permissions	Which settings sources are in effect; common traps: the same key overridden by settings.local.json, or config mistakenly written to ~/.claude.json (it belongs in ~/.claude/settings.json — two different files)
   Memory/instruction problems	/memory + /skills	Where each scope's memory files live; a skill not appearing is often the file saved as .claude/skills/name.md (should be the name/SKILL.md directory structure)
   Suspect an extension is misbehaving (lag / odd behavior)	claude --safe-mode	Runs bare with all customization disabled (CLAUDE.md/skills/plugins/hooks/MCP); problem gone = an extension is the culprit — use the targeted commands above to pin it down
   Suspect the user-level config itself is broken	CLAUDE_CONFIG_DIR=/tmp/claude-clean claude	Points at an empty config directory, bypassing ~/.claude entirely; problem persists = the cause lies outside your config

5. Still stuck? Hand the problem to Claude.OfficialInside a session, /debug [describe the problem] turns on debug logging for this session and has Claude diagnose it from the logs and settings paths; for performance problems (high CPU/memory, freezes) see the official troubleshooting page — the usual fixes are /compact to shrink context and restarting the session (claude --resume keeps the conversation).

Copy-paste prompt

My Claude Code configuration doesn't seem to be taking effect. Symptom: <fill in, e.g. "rules in
CLAUDE.md are ignored" / "my PostToolUse hook doesn't fire" / "the MCP server connects but has no tools">.

Diagnose it following the official debugging order:
1. Have me run /doctor and /context first; I'll paste you the output;
2. From the output, decide which case this is: file not loaded, loaded from a
   different location, or overridden by another scope
   (managed > local > project > user);
3. If loading looks fine but behavior is wrong, check whether it's an
   instruction-writing problem (vague / conflicting / too long);
4. If hooks or MCP are involved, have me also run /hooks or /mcp;
5. Finish with concrete fix steps, noting what I should expect to see at each step.

Sources & last verified

• Officialdebug-your-config (/context, /doctor, /hooks, /mcp usage and the common-cause lookup table), fetched 2026-08-05.
• Officialtroubleshooting (symptom triage table / performance problems / safe mode), fetched 2026-08-05.
• Officialskills (checking the version with claude --version and /status), fetched 2026-08-05.
• Last verified: 2026-08-05 · volatility:high (the command list and /doctor's capabilities evolve across versions; as of version 2.1.222).