debug — Claude Code and Cline rule: a debugging routine when stuck
The debug rule sets the order for troubleshooting: gather evidence and context, explain the cause, then edit code. It applies when an error persists or a fix is incomplete.
no license ★ 1,054 updated 2025-07-17
.cursor/rules/debug.mdcWhat debug does
The rule covers errors that did not go away on the first pass and fixes that came out incomplete. Otherwise it stays out of the way; its own description limits it to the moment the agent is stuck.
Work begins with evidence. Error messages, logs and the visible symptoms get collected, plus context pulled from project files, while architecture and the current task come from @memory.mdc. The agent then says what it observed and why that points at this cause rather than a neighbouring one. Short on facts, it gathers more and may ask you to clarify.
Editing comes last. The routine calls for <ANALYZE CODE> over the affected area, a search for similar cases already solved in @error-documentation.mdc, then the fix through <SYSTEMATIC CODE PROTOCOL> and <TESTING>. Those blocks sit in implement.mdc from the same repo, so a project without that file leaves part of the routine without its steps.
What it helps with
- untangle a test that keeps failing instead of patching blindly
- collect logs, symptoms and file context before touching code
- tell an architecture misalignment from an ordinary bug
- reuse a similar fix already recorded in the project
- show the reasoning before the agent edits anything
Example prompts for the agent
- The build keeps failing in
cart_test.py; run the debug routine and gather observations first. - Don't patch yet. Walk through the cause step by step and present your reasoning.
- Check
@error-documentation.mdcfor a similar issue before you propose a fix.
How to install debug
Manually: put the files in place
.cursor/rules/debug.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.claude/rules/debug.mdThe paths frontmatter field limits the files: move globs from the source into paths
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.github/instructions/debug.instructions.mdThe applyTo field sets which files it applies to: move globs from the source into applyTo
Manually: put the files in place
.devin/rules/debug.mdManually: put the files in place
.clinerules/debug.mdStep by step, with commands for each platform: Cursor rules: .mdc files, four modes and what replaced .cursorrules
Questions about debug
How do I install debug in Claude Code?
Copy the rule file to .claude/rules/debug.md in the project root. Claude picks it up from there.
What does debug do?
It sets a routine for stuck errors and incomplete fixes: gather observations, explain the cause, look for similar solved cases, then change code.
Does it need other rule files?
Yes. Its steps point to implement.mdc for <ANALYZE CODE>, <SYSTEMATIC CODE PROTOCOL> and <TESTING>, to @error-documentation.mdc for past cases, and to @memory.mdc for architecture and the working task.