Debug a repository

A repository is the folder of code behind your project. Use Claude Code in that folder to turn one repeatable bug into an explained cause, a small fix, and checks that show whether it worked.

Before you start

• Claude Code installed in your terminal, with claude --version returning a version number, and a working sign-in. Access requires an eligible Claude subscription, a Claude Console account, or a supported organization setup.
• The project folder on your computer, plus its documented setup completed so you can run the affected feature or test locally.
• A saved copy of your current files, including work you have not committed. Use a separate local development copy if someone else is editing the same files.
• One failing action or command, its actual result, and the result you expected. Use test data and remove private values from any logs you paste.

Want to do it yourself?

Difficulty

8 out of 10

Estimated completion time

1–3 hours; intermittent bugs can take longer

Skills you’ll need: Navigate a repository, reproduce an error, read a diff, and run project checks. You need enough code knowledge to judge the fix.

I’ll do it myselfI’d rather get help

How this helps your brand

Finding the cause of a defect helps protect the experience customers depend on. The same evidence-based workflow can repair a website interaction, an internal app, or a script without guessing at unrelated changes.

1. 1

   Step 1: Make the issue repeatable

   Repeat the problem in your local project before asking for a fix. Write down the starting state, exact action, expected result, and actual result. For a command that fails, keep the command and full relevant error text, including the file names and line numbers in the stack trace.

   For example: “With one item in the cart, change the quantity from 1 to 2. The item costs 12, so the subtotal should become 24. It stays at 12 until I reload.” This is an example report; replace it with something you actually observed.

   Open a terminal in the project folder. You can run cd "[project folder path]", replacing the bracketed part with your folder path. Then run claude --permission-mode plan and complete sign-in if prompted. This starts an investigation in Plan mode. Ask Claude to read the project instructions, locate the setup and test commands, and identify the files involved in your report.

   • Include the page or command, the test input, and whether it fails every time or only sometimes.
   • Name the last working version or recent change if you know it; say “unknown” if you do not.
   • Record existing local edits before Claude changes anything so you can distinguish your work from its fix.

   Tip: If the problem will not repeat, stop short of choosing a fix. Give Claude the conditions from the failed attempt and ask what additional log or test would distinguish the likely causes.

   Illustrated exampleA bug report you can repeat

   Safe sample · cart page

   1. Load a sample cart with one item.
   2. Set its quantity to the text value "2".
   3. Select Add one once.

   Last known working: quantity changed from 2 to 3.

   Expected quantity

   3

   Actual quantity

   21

   Repeat with the same input: the same wrong result appears.

2. 2

   Step 2: Trace the failure before approving edits

   Paste the prompt below into Claude Code and fill in its bracketed fields. Ask it to follow the reported action through the relevant code, naming the files and functions it reads. For the cart example, that might mean following the quantity input, the cart state, and the calculation that displays the subtotal.

   Have Claude explain the earliest point where the value or behavior becomes wrong, what evidence supports that explanation, and what still needs checking. A file name alone is not a diagnosis. Ask for a focused test or repeatable manual check that would fail before the proposed fix and pass afterward.

   Review the proposed files and check commands. Plan mode is for investigation; shell-command permissions depend on your settings, so it is not a guarantee that every command is harmless. If a check needs unavailable credentials, dependencies, or a service, have Claude identify that missing requirement and mark the check as not run.

   Once the cause and scope make sense, approve the plan with “Yes, manually approve edits”. Then ask Claude to reproduce the failure with the agreed check and make the smallest suitable fix. Review permission requests as they appear. Do not accept unrelated cleanup or removal of a failing assertion just to get a passing result.

   Tip: Keep investigation focused on one symptom. If Claude cannot support its diagnosis, ask which observation would confirm or disprove it before authorizing a change.

   Illustrated exampleFind the first value that goes wrong

   1. 1
      Quantity fieldEmits text: "2"
   2. 2
      Click handlerPasses the value through unchanged.
   3. 3
      Cart updateFirst wrong value: "21"
   4. 4
      Cart displayShows the state it received.

   cart.tsSample cause

   quantity + 1

   With text input, + joins characters: "2" + 1 becomes "21".

   Explain the cause before editing

   Check other callers of the same cart update. Do they pass text too?

3. 3

   Step 3: Prove the fix and review the files

   Ask Claude to run the original failing check again and show the command and result. Then test one nearby case. For the cart example, check both increasing the quantity and changing it back to 1. Run the relevant existing project checks too, using the commands found in the project rather than assuming every repository uses the same test runner.

   Repeat the original action yourself in the local app when the bug affects what people see or click. Read the changed-file comparison, often called a diff, in your editor. Each change should contribute to the fix or its test. Ask Claude to explain anything you cannot connect to the reported problem.

   If the fix makes things worse, press Esc to interrupt Claude. For changes made through its file editing tools, /rewind opens a menu where you can choose the point before the fix and restore the code. Rewind does not undo shell-command changes or external effects, and it is not a complete backup. Use your saved copy for changes it cannot restore, taking care to preserve any unrelated work.

   Finish with a short record of the cause, changed files, original and nearby checks, and anything not run. Save a new working copy once the checks pass. A plausible explanation or a test that never ran is not proof that the bug is fixed.

   Illustrated exampleProve the fix with two cases

   Sample change · convert valid quantity text to a number

   Run the original failure and a nearby case

   Case	Before	After fix
   Original failureText "2" + one	Before: "21"	After: 3 · pass
   Nearby caseNumber 2 + one	Before: 3	After: 3 · pass

   Review the diff. Keep only the quantity fix and its checks. Record the cause: text was joined instead of added.

Help me debug one issue in this repository. Start by investigating and proposing a plan; wait for my approval before changing source files.

Failing page or command: [exact page or command]
Starting state and steps: [test data and actions in order]
Expected result: [what should happen]
Actual result: [what happens, including relevant error text with private values removed]
Frequency: [every time, sometimes, or conditions]
Recent changes or last working version: [details or unknown]
Existing local work to preserve: [files or description]

Read the project instructions and documented setup and test commands. Trace the failing path through the relevant files and functions. Explain the earliest incorrect behavior, the evidence for your diagnosis, and any uncertainty. Propose the smallest fix and a check that demonstrates the failure before the change. If you cannot reproduce it, ask for the missing evidence instead of guessing.

After I approve the plan, reproduce the failure, implement the focused fix, and verify the original case plus one nearby case and relevant existing checks. Preserve unrelated work and keep failing assertions meaningful. Report the cause, every changed file, exact check commands and results, and any check not run with its reason. Do not commit, push, or deploy.