Lesson 16: Troubleshoot — When Things Go Wrong

Day 16 of 50 · ~8 min read · Phase 2: Core Workflows

Why This Lesson Exists

Claude Code is powerful, but it's not magic. Sometimes Claude gets confused. It forgets context. It makes wrong assumptions about your codebase. It overwrites changes you didn't want changed.

This lesson explores three common failure modes and how to recognize and fix them. These aren't edge cases — you'll hit at least one of these in real work. The goal is to help you diagnose quickly and get back on track.

Scenario 1: Context Overload

What Happens

You're working on a large refactoring. Claude is doing well: it reads files, makes edits, runs tests. But after 30 minutes and 50 messages, Claude suddenly seems lost.

It refers to code it read 20 minutes ago but gets details wrong
It forgets that you already made a change and tries to make it again
It asks "should I rename this function?" when you already explained 10 messages ago that you want it renamed everywhere
Tests start failing because Claude isn't catching all the places that need updating

What It Looks Like

You: "Now update the API handlers to use the new logger"
Claude: "I'll search for where the logger is imported..."
[Claude reads 3 handler files]
Claude: "I found the logger imports. Should I add logging to each handler?"
You: "Yes, add it everywhere we make HTTP requests"
Claude: "Got it, let me search for HTTP requests..."
[Claude reads 2 files]
Claude: "I found the requests in handlers/users.js and handlers/posts.js. 
        Should I also check the database layer for HTTP calls?"
You: "No, just the handlers. We talked about this 10 minutes ago"
Claude: "You're right, my apologies. Let me focus on just the handlers."
[Claude edits handlers/users.js]
Claude: "Done! I've added logging to the HTTP requests"
You: "Tests are failing. Did you update the response object handling?"
Claude: "What do you mean? I just added logging"
You: "The response object changed because of the logger middleware. 
      Several places need updates"

The problem: Claude's context is full. It's forgotten the architectural context it understood 20 messages ago. It's now making decisions based on incomplete memory.

Diagnose It

Is Claude asking questions it already has answers to?
Is Claude forgetting about changes it made earlier in the conversation?
Is Claude asking for clarifications on things you explained?
Are tests failing in ways that suggest Claude missed dependencies?

The Fix

Stop the current conversation. Don't push through. Do this:

Commit what's done: Ask Claude to stage and commit the current changes (or roll them back if they're broken).
```
"Let's commit what we have so far. 
 git status and git commit -m 'partial refactoring: [description]'"
```
Start fresh: Close the conversation. Start a new one.
```
claude
```

Provide context: In the new session, reference what you've done:

"I've already refactored the authentication module 
 (see commit abc123). Now I need to update the API handlers 
 to use the new logger. Here's what changed: [brief summary]"

Continue the task: Pick up where you left off with fresh context.

Why this works: A new conversation starts with an empty context window. You lose the irrelevant historical chatter but keep the important changes (committed to git). Claude can now focus on the remaining work.

The Lesson

Context window isn't infinite. Breaking large tasks into logical phases isn't laziness — it's architecture. A 2-hour refactoring split into 4 phases of 30 minutes each is smarter than one long slog where Claude forgets what it's doing.

Scenario 2: Overwriting Unrelated Changes

What Happens

You're working in a branch. You ask Claude to refactor a module. Claude reads the file, makes edits, and writes a new version.

But here's the problem: you'd made a small fix to that same file before asking Claude to refactor it. That fix was never committed — just sitting in your working directory.

Claude's Write tool doesn't know about your uncommitted change. It replaces the entire file with its refactored version.

Your small fix is gone.

What It Looks Like

You: "I fixed a bug in utils.js where the date parser was wrong.
     Now I want to refactor that same file to extract helper functions"
Claude: [reads utils.js with your bug fix]
Claude: [makes edits using the Write tool]
Claude: "Done! I've extracted the helper functions"
You: "Great, let me check git status..."
You: git diff utils.js
[Your bug fix is gone. Only Claude's refactoring is there]

Diagnose It

Did Claude use Write instead of Edit?
Did you have uncommitted changes before asking Claude to edit?
Does git diff show that lines you wrote are gone?

The Fix

Immediate: You might be able to recover from your terminal history or editor undo.

Prevention: This is totally avoidable:

Always commit before asking Claude to refactor a file.

git add utils.js
git commit -m "Fix: date parser bug in utils.js"

Or explicitly tell Claude about uncommitted changes:

"I've made a bug fix in utils.js (not committed yet). 
 After you refactor, make sure the fix is still there. 
 Here's what I changed: [show the fix]"

Review before accepting: If Claude uses Write on a file you've edited, carefully compare the before/after to make sure your changes are preserved.

The Lesson

Version control is your safety net. Uncommitted changes are vulnerable. Git doesn't just help you ship code — it protects your work. Always commit before asking Claude to make big changes to a file.

Scenario 3: Wrong Assumptions About Your Codebase

What Happens

You ask Claude to do something straightforward. Claude makes an assumption about how your project is organized, and that assumption is wrong.

For example:

You ask Claude to "find all database queries" but your database is accessed through an ORM, and Claude looks for raw SQL
You ask Claude to "add error handling" but it doesn't know that your project uses a custom error class and Observability system
You ask Claude to "add a config option" but it doesn't realize your config is generated from environment variables, not edited directly

Claude makes changes that are technically correct but don't fit your project's patterns.

What It Looks Like

You: "Add a configuration option for max retries"
Claude: [creates a new config file with a max_retries parameter]
You: "That's not how we do config. We use environment variables"
Claude: "Oh! Let me redo this..."
Claude: [creates an env var, but misses updating 3 places where config is loaded]
You: [Tests fail because not all the config loading is updated]

Diagnose It

Did Claude's solution not match existing patterns in your codebase?
Did Claude miss that you have a custom framework or convention?
Did your PR review uncover patterns Claude didn't follow?
Are you saying "we don't do it that way" frequently?

The Fix

In the moment:

Point to an example: "No, we don't do it that way. Look at config/database.js to see how we handle config."
Explain the pattern: "We use environment variables, parsed in config/index.js, and injected at startup."
Ask Claude to redo it: "Please redo that using the same pattern."

For the future:

Create a CLAUDE.md file in your project root. Here's what goes in it:

# Project Conventions

## Configuration
- Use environment variables for config (see .env.example)
- Config is loaded and validated in src/config.ts
- Never create new config files

## Error Handling
- Use the custom ErrorHandler class from src/errors.ts
- Log all errors using src/logger.ts
- Never use console.error or console.log directly

## Database Access
- Use the ORM query builder in src/db/index.ts
- Never write raw SQL
- Database migrations are in db/migrations/

## Testing
- Tests are in __tests__/ directories next to the code
- Use Jest fixtures in __tests__/fixtures/

Reference it in your prompt: "Remember to follow the conventions in CLAUDE.md, especially around configuration and error handling."

The Lesson

Conventions are context. When Claude doesn't know your project's patterns, it invents reasonable ones. Save time by documenting them upfront. A CLAUDE.md file is one of the highest-ROI things you can create.

Key Takeaway

These three scenarios are totally manageable once you see them coming.

The real skill isn't preventing all problems — it's recognizing when Claude is lost and knowing how to course-correct. Sometimes that's starting a fresh conversation. Sometimes it's pointing Claude to an example in your codebase. Sometimes it's committing work and clarifying assumptions before you continue.

Watch for these signs:

Claude asking the same question twice
Claude forgetting about changes from earlier in the conversation
Claude's solution not matching existing patterns
Tests failing in ways that suggest incomplete understanding

When you see them:

Diagnose what's wrong (context overload? wrong assumption? missing context?)
Use the fix for that scenario
Continue forward

You're now equipped to work with Claude Code at scale. The rest is practice.

What's Next

You've completed Phase 2: Core Workflows (Lessons 9–16).

You understand:

How to edit code safely (Lesson 9)
How context works (Lesson 10)
How to prompt effectively (Lesson 11)
How to handle multi-file changes (Lesson 12)
How to use version control as a partner (Lesson 13)
How to apply all this to real projects (Lesson 14)
How to verify your understanding (Lesson 15)
How to diagnose and fix common problems (Lesson 16)

Phase 3 dives deeper: advanced prompt patterns, working with teams, handling large codebases, using CLAUDE.md to encode conventions, and more.

But you've earned a rest. You've learned a lot. Take time to practice these Phase 2 skills on real projects. Get comfortable with the agentic loop. Build trust in Claude Code as a pair-programming partner.

Then you'll be ready for Phase 3.

← Back to Curriculum · Phase 3 (Lessons 17–24) Coming Next