Claude Code Pitfalls: Claude Code Won’t Do What You Told It: A Troubleshooting Catalog

Last Updated on June 3, 2026 by Editorial Team Author(s): Rick Hightower Originally published on Towards AI. Part 17: Why your config looks right but Claude ignores it, and the exact commands that diagnose it in seconds In this article: Most Claude Code failures are not mysteries. They are a small set of recurring patterns: files that load on demand instead of at startup, permission rules that quietly override your mode, descriptions that fail to trigger a subagent. This is a Claude Code troubleshooting catalog grouped into five categories, with the exact diagnostic commands for each. Read it once and you will spend dramatically less time chasing configuration ghosts. Claude Code TroubleshootingAfter the introduction, the article lays out a practical troubleshooting catalog for Claude Code. It begins with four “muscle memory” commands (/doctor, /context, /memory, and /debug) that resolve most issues quickly, then explains five recurring categories of failure: loading problems (often caused by on-demand CLAUDE.md loading rather than startup), permission surprises (ask/allow rules override mode settings), delegation not triggering (subagent/skill descriptions must be specific and trigger-based), integrations going quiet (use /mcp, /hooks, and correct project-scoped configuration; debug failures including auth, paths, and permissions), and environment quirks (UI/input changes, trust/worktree behavior, and performance issues traced to state). It closes with a diagnostic order to follow when you’re stuck, the scope/precedence rule behind “it should work” situations, and a “do this today” checklist to build the instinct for diagnosing problems in seconds. Read the full blog for free on Medium. Join thousands of data leaders on the AI newsletter. Join over 80,000 subscribers and keep up to date with the latest developments in AI. From research to projects and ideas. If you are building an AI startup, an AI-related product, or a service, we invite you to consider becoming a sponsor. Published via Towards AI