Debugging Claude

Sometimes Claude doesn’t do what you expect. Here’s how to diagnose and fix issues.

Common Issues

Claude Forgets Context

Symptoms:

Asks questions you already answered
Contradicts earlier decisions
Loses track of the task

Causes:

Context window full
Too much irrelevant information
Long conversation

Fixes:

> /compact
# or
> /clear
> Here's what we were working on: [brief summary]

Claude Makes Wrong Assumptions

Symptoms:

Implements something different than requested
Uses wrong patterns or libraries
Ignores constraints

Fixes:

# Be more explicit
> Stop. Let me clarify:
> - Use PostgreSQL, not SQLite
> - Follow the pattern in existing_file.py
> - Do NOT modify the auth module

# Or use plan mode (Alt+M to cycle to plan mode)
> [task]
# Answer clarifying questions

Claude Produces Low-Quality Code

Symptoms:

Missing error handling
No tests
Inconsistent style

Fixes:

# Add requirements upfront
> implement [feature]
> requirements:
> - include error handling for edge cases
> - add pytest tests
> - follow existing patterns in the codebase

# Or review and iterate
> this code is missing error handling
> add try/except for network calls and database operations

Claude Can’t Find Files

Symptoms:

Says files don’t exist when they do
Wrong paths

Fixes:

# Be explicit about paths
> the file is at app/services/user.py (relative to project root)

# Or help it search
> search for files containing "UserService"

Claude Goes in Circles

Symptoms:

Keeps trying the same approach
Doesn’t learn from failures

Fixes:

> Stop. This approach isn't working.
> Let's try a different strategy: [describe alternative]

# Or start fresh
> /clear
> [reframe the problem differently]

Diagnostic Techniques

1. Ask Claude What It Knows

> what do you understand about the current task?
> what constraints are you working with?
> why did you choose that approach?

2. Check Context State

> /context

3. Verify File Reading

> show me what you see in app/main.py
> is this the current version?

4. Test Understanding

> before you implement, explain your plan
> what files will you modify?
> what's the sequence of changes?

When to Start Over

Start a fresh session when:

Context is over 50% full
Claude seems confused despite corrections
You’re changing to a completely different task
The conversation has become unproductive

exit
claude "fresh start: [clear task description]"

Getting Help

If Claude consistently fails at a task:

Simplify - Break into smaller tasks
Provide examples - Show what you want
Check CLAUDE.md - Is context correct?
Try different model - Opus for complex tasks