Cursor: debug errors with the agent (2026)

When something breaks locally or in CI, the impulse is to open Agent and say «fix it». That often yields patches that hide the symptom or touch ten files. This flow treats the agent as a debugging partner: evidence first (reproduction and full log), then ordered theories, then a minimal change you can review line by line. It assumes you already open the repo calmly (cursor-repo-existente) and, if your team has norms, they live in `.cursor/rules` (cursor-reglas-proyecto). About 25 minutes on a `fix/` branch, not on main.

1. Steps 1

   Reproduce the error and freeze the scenario

   Before opening Agent, run in the **integrated terminal** the same command that failed (test, dev script, build). Copy the full output — not only the last line. Note three fields: **command**, **current branch** (`git branch --show-current`) and **done-when** («`npm test -- auth` green» or «POST /login returns 400 with body X»). For UI bugs, reproduce once and copy the error from the browser console or the server line in Cursor’s terminal.

   Create the branch now: `git checkout -b fix/describe-the-symptom`. Do not edit code yet.

   What you should see: Terminal showing the error again, a log block on the clipboard and the status bar on `fix/…`.

2. Steps 2

   Paste the real log and pin context with @

   Open **Chat** in **Agent** mode (or the Agent panel in your Cursor version). In the first message paste the **full stack trace or log** — do not trim the «noise» in the middle if file paths live there. Add the done-when criterion from step 1.

   Pin files the log mentions with `@`, e.g. `@src/auth/login.ts` and `@src/auth/login.test.ts`. If you are unsure which file, use **Ask** first: «from this stack, which file should I open first? Paths only, do not edit» then return to Agent.

   End the message with an explicit constraint: **«Do not modify files in this message. Only analyze the log.»**

   What you should see: A long message with the pasted error, 1–3 @ files in the chat bar and a reply citing real lines or functions from the repo.

3. Steps 3

   Ask for ordered hypotheses before touching code

   In the same thread (or next message), ask:

   «List 3–5 root-cause hypotheses, most to least likely. For each: file and function, what log evidence supports it, and what you would check in 2 minutes without refactoring. Do not write code or propose a diff yet.»

   Read the list like a human: does it name paths that exist in your tree? Is hypothesis #1 checkable with a `console.log` or a mental breakpoint? If something sounds generic («async issue»), ask to narrow: «which exact stack line points there?»

   Optional: if you have Always Apply rules with the test command, the agent should mention them without you repeating the README (cursor-reglas-proyecto).

   What you should see: A numbered reply with hypotheses, repo paths and verification steps — no «Apply» panel and no modified files.

4. Steps 4

   Pick one hypothesis and scope the fix job

   Reply with one decision line: «We try hypothesis 2 first.» Then paste a scope block (same style as cursor-como-ide-con-ia):

   - **Outcome:** [your done-when from step 1] - **Allowed files:** at most 2–3 paths - **Do not touch:** CI, `.env`, dependencies, refactors, other modules - **Minimal change:** only what the chosen hypothesis needs - If you need more files, **stop and ask**

   Ask for a **3–5 line plan** before applying changes: «Write the plan first; wait for my OK.»

   What you should see: A short plan in chat (which file, what change, which test to run) and your explicit OK before the first diff appears.

5. Steps 5

   Red test first (if none exists yet)

   If the bug had no test, ask for **only** a test that fails on the current symptom:

   «Add a test in `@…` that fails with the broken behavior. Do not fix production yet.»

   Run the test command yourself in the terminal. It should fail for the right reason, not a bad import in the new test. If the test passes without a fix, it does not capture the bug — fix the test before continuing.

   If a red test already existed at the start, confirm it still fails after any test-only change. The red → green cycle is your safety net.

   What you should see: Terminal with the test red and an assertion message describing the bug, not a syntax error in the new test.

6. Steps 6

   Apply a small fix and review the diff

   With the red test confirmed, authorize the minimal fix for the chosen hypothesis. When the agent proposes changes, open the editor **diff view** (same as reviewing a PR): each hunk, extra files in the modified list, new unused imports.

   Reject hunks you do not understand or that touch files outside scope. If the diff crosses ~40 lines for a localized bug, ask to split: fix first, cleanup never on the same debug branch.

   Accept only what you can explain in one sentence to a teammate.

   What you should see: Diff of one or two production files plus the test; no surprise folders in Source Control.

7. Steps 7

   Verify in your terminal and close or iterate

   Run the **same command** from step 1 again. It should pass (or meet the manual criterion). If it fails, paste the **new** full output into Agent — do not say «still broken» without a log — and return to hypotheses with «hypothesis 2 was wrong; updated log below».

   If it passes: `git diff` once more, commit on the branch with a message that names the symptom (`fix: login 500 when email empty`). Optional: open a small PR; the diff is the deliverable, not the chat.

   If no hypothesis fits after two iterations, stop the agent and escalate to a human or deep Ask in the module — do not let it refactor blind.

   What you should see: Green terminal with the original command, clean `git status` after commit or a working tree you fully understand.