Skip to main content
rule CX Codex

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

Install into Cursor · Manually: put the files in place All methods and platforms ↓
.cursor/rules/debug.mdc
Open on GitHub

What 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.mdc for a similar issue before you propose a fix.

How to install debug

Manually: put the files in place

.cursor/rules/debug.mdc

Frontmatter: description, globs, alwaysApply

Step 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.

Similar IDE rules

All IDE rules for Agent setup: memory, context, orchestration →

From the same set11

The whole set →
directory-structure directory-structure defines a standard top-level repository layout for your AI coding assistant, mapping source files, tests, and configuration. CX Codex +1 ★ 1,054repo stars architecture-understanding The architecture-understanding rule has the agent read docs/architecture.md and check code changes against its architecture. Use it when a project documents its design in a Mermaid diagram. CX Codex +1 ★ 1,054repo stars cursor-rules-location cursor-rules-location keeps repository rule files organized by rejecting any .mdc files created outside the .cursor/rules directory. CX Codex +1 ★ 1,054repo stars develop-mcp-server The develop-mcp-server rule structures MCP server work from planning to validation, with setup guidance for Node.js and Python projects. CX Codex +1 ★ 1,054repo stars plan Makes the agent read your docs, task notes and source before planning, ask clarifying questions, and only then propose a solution. CX Codex +1 ★ 1,054repo stars implement implement enforces a strict coding protocol with dependency checks, step-by-step edits, simulation passes, and automated test coverage before finalizing changes. CX Codex +1 ★ 1,054repo stars memory This rule organizes project memory across docs/, tasks/, and .cursor/rules/. It helps an agent retain plans, context, errors, and project decisions between tasks. CX Codex +1 ★ 1,054repo stars memory Keeps project memory in a fixed set of files the agent reads before work: requirements, architecture, stack, task plan, current state. CX Codex +1 ★ 1,054repo stars

Project sponsors

Companies that keep this analytics open