One of the most frustrating experiences with an AI coding agent is a configuration that looks perfect while the agent quietly ignores it. The reassuring part is that most of these failures are not mysterious. They fall into a small set of recurring patterns: files that load on demand instead of at startup, permission rules that silently override settings, and descriptions that never trigger the subagent that was expected. What follows is a practical troubleshooting catalog for Claude Code, grouped into five categories, so less time is spent chasing configuration ghosts.
Start with the “muscle memory” commands
Before any deep diagnosis, a handful of built-in commands resolve most problems quickly. The documentation and reference commands confirm how a feature is supposed to behave, the memory command shows what context is actually loaded, and the debug command surfaces what the agent is doing under the hood. Running these first short-circuits a large share of issues. Knowing when each tier of setup is even necessary is covered in this overview of Claude Code mastery tiers.
1. Context that loads on demand
A common surprise is assuming project context is present when it is not, because some files load on demand rather than at startup. Before concluding that the content itself is wrong, confirm when and how the project context is actually loaded.
2. Permission surprises
Permission rules can silently override mode settings. A forgotten “ask” or allow/deny rule will quietly countermand behavior configured elsewhere, so the agent pauses, refuses, or proceeds in unintended ways. When a mode is not taking effect, the permission rules are the first place to check.
3. Delegation that never triggers
When a subagent or skill never fires, the cause is almost always its description. Descriptions need to be specific and trigger-based, written around the conditions that should invoke them rather than offered as vague summaries. A subagent with a generic description simply will not match the situations it is meant to handle.
4. Integrations that go quiet
When an MCP server or a hook seems inert, it pays to verify it directly: check the connections and hooks, and confirm they are configured at the correct project scope. Many “silent integration” failures come down to authentication, file paths, or permissions, so those three are worth debugging explicitly before assuming the integration is broken.
5. Environment quirks
Finally, some issues are environmental: changes in the interface or input handling, trust and worktree behavior, and state-related performance problems. These do not originate in the configuration at all, and recognizing them as environment quirks prevents endless edits to settings that were never the cause.
The habit that pays off
Most of these failures are diagnosable in seconds once the categories are familiar and the right commands are close at hand. The underlying logic is about scope and priority — understanding which setting wins when several apply — and that habit turns a frustrating stall into a quick, repeatable check.
