Debug Claude Code Automations

Debugging & Troubleshooting

Your automation isn't working. Claude produced garbage, ignored your instructions, or got stuck halfway through. This happens. Here's how to fix it.

The most common problems

Before diving into debugging techniques, here's what usually goes wrong:

1. Vague instructions — Claude interpreted something differently than you meant
2. Missing context — Claude doesn't know something you assumed it knew
3. File issues — The file isn't where Claude expects, or the format is different
4. Conflicting rules — Your CLAUDE.md says one thing, your instruction says another

80% of problems fall into these four buckets.

Step 1: Read what Claude actually did

When something goes wrong, look at Claude's output carefully. It usually explains what it did and why:

I found 3 CSV files in the input folder. Processing the first one...
The file has columns: Date, Name, Total
I didn't find a "revenue" column, so I used "Total" instead.

There's your problem — you said "revenue" but the file has "Total." The fix is either rename the column in your file or update your instruction to say "Total."

Step 2: Check the obvious stuff

Before debugging your instructions, verify the basics:

Is the file where you think it is?

ls -la ~/my-project/input/

Is the file readable?

head -5 ~/my-project/input/data.csv

Are you in the right folder?

pwd

Half the time the problem is just "the file is in Downloads, not in input/" or "I'm in the wrong directory."

Step 3: Simplify and isolate

If a multi-step workflow fails, don't debug the whole thing at once. Break it into pieces:

Instead of:

Read the files, clean them, merge them, calculate metrics, generate report

Try:

Read the files and tell me what columns they have

Then:

Clean the first file and save it as step1_output.csv

Then:

Read step1_output.csv and tell me if it looks right

Find exactly which step breaks. Fix that step. Then chain them back together.

Step 4: Be more specific

Vague instructions cause most problems. When Claude does the wrong thing, it's usually because your instruction left room for interpretation.

Bad: "Clean up this data"

What does "clean up" mean? Remove duplicates? Fix formatting? Fill in blanks?

Better: "Remove rows where email is empty. Deduplicate by email address. Standardize phone numbers to (XXX) XXX-XXXX format."

Bad: "Summarize the key points"

How many points? What's "key"? What format?

Better: "List the 5 most important findings. Each should be one sentence. Format as a numbered list."

When Claude does something unexpected, ask yourself: "Did I actually tell it what I wanted, or did I assume it would figure it out?"

Step 5: Add examples

If Claude keeps getting the format wrong, show it what you want:

Format each entry like this:

**Acme Corp** — $15,000
Contact: Jane Smith ([email protected])
Status: Active | Last contact: 2026-03-01
---

Examples beat descriptions. Instead of saying "format it nicely," show exactly what "nice" looks like.

Step 6: Check for conflicts

If you have a CLAUDE.md file, make sure your instruction doesn't contradict it:

CLAUDE.md says: "Always save outputs to /output/"

Your instruction says: "Save as report.md"

Claude might save to /output/report.md, or might save to the current directory. Be explicit: "Save as /output/report.md"

Common error patterns and fixes

"I couldn't find the file"

• Check the file path
• Make sure you're in the right directory
• Check for typos in the filename

"The column doesn't exist"

• Open the file and check actual column names
• Watch for spaces, capitalization, special characters
• "Amount" ≠ "amount" ≠ " Amount"

"I'm not sure what you mean by..."

• Your instruction was ambiguous
• Rewrite with more specific language
• Add an example of what you want

Claude produces nothing / empty output

• Check if there's any data matching your criteria
• "Filter to rows where status = 'closed'" produces nothing if all rows say "Closed" (capitalization)
• Try removing filters to see the full data, then add them back

Output is weirdly formatted

• Add explicit format instructions
• Include an example of desired output
• Specify: "Use markdown tables" or "One item per line"

The "show your work" technique

When really stuck, ask Claude to explain its process:

Read data.csv and explain:
1. What columns you see
2. How many rows total
3. What you think each column contains
4. Any issues you notice with the data

This reveals how Claude is interpreting your data. You might discover it's seeing something different than you expected.

When to start over

Sometimes your CLAUDE.md has accumulated so many tweaks and exceptions that it's become confusing. If you're spending more time debugging than working, consider:

1. Copy out the parts that definitely work
2. Delete the CLAUDE.md
3. Start fresh with a simpler version
4. Add complexity back gradually

A clean rewrite often works better than patching a tangled mess.

Prevention: test incrementally

When building new automations, test each step before adding the next:

1. Write step 1, run it, verify it works
2. Add step 2, run the whole thing, verify both work
3. Add step 3, run, verify
4. Continue

This way you catch problems immediately instead of debugging a 10-step workflow where you don't know which step broke.

Recap

Debugging Claude Code is mostly about being specific. Read what Claude did, check the obvious stuff, simplify to isolate the problem, and rewrite instructions to remove ambiguity. When in doubt, add examples.

Most problems are communication problems. Claude is capable — you just need to tell it exactly what you want.