Skip to content
BSWEN
Blog

Why Does Claude Code Keep Breaking My Code Changes?

Cowrie
Cowrie
Dev @ Bswen

Problem

Claude Code kept breaking my code. I’d ask for a simple refactor, and it would make changes beyond what I requested. I’d ask it to fix a bug in one file, and it would “improve” code in three others. Sometimes it would invent function signatures that didn’t exist, confident it was correct.

The frustration came from a few specific patterns:

  • Unilateral decision-making: Claude would “fix” things that weren’t broken
  • Context loss: In multi-file changes, it would forget what it had just done
  • Confident incorrectness: High confidence when making wrong assumptions
  • Skipped validation: Not running tests or checks that would catch errors

I needed to understand why this happened and how to prevent it.

What Happened?

Let me walk through a typical scenario that kept recurring.

I asked Claude to refactor a user authentication module:

Refactor the UserService to use dependency injection.

Claude made the changes. I reviewed the diff, committed, and pushed. Then tests failed in CI. Claude had:

  1. Changed a public method signature that broke 12 callers
  2. Removed error handling I needed
  3. Renamed a database field without updating the schema migration

When I confronted it, Claude apologized and “fixed” it—introducing two new bugs.

This wasn’t an isolated incident. Every large refactoring session followed the same pattern. I’d spend more time debugging Claude’s changes than I would have spent doing it manually.

Why Claude Breaks Code

I started researching and experimenting. The causes became clear.

Context Window Limitations

Claude can only “see” a portion of my codebase at once. When working across multiple files, it forgets earlier changes or misses dependencies between components.

In my UserService refactor, Claude modified the service but didn’t see the 12 files that imported it. The context window filled with the service code itself, leaving no room for callers.

Overeager Optimization

Claude’s training encourages helpful behavior. This paradoxically leads to “helpful” changes I didn’t request. It sees patterns and wants to “fix” them, even when those patterns are intentional.

Me: Refactor UserService to use dependency injection
Claude: [Also renames methods, reorganizes imports, removes "unused" code]

None of these extra changes were requested. Claude was being “helpful.”

Hallucinated APIs

Claude sometimes invents method signatures or library APIs that don’t exist, especially with:

  • Less common libraries
  • Custom internal code
  • Framework-specific conventions

When it’s confident about a wrong assumption, it generates code that looks right but fails at runtime.

Instruction Drift

In long conversations, Claude gradually drifts from my original instructions. If I don’t reinforce constraints periodically, the original request loses influence.

How I Solved It

I implemented a set of practices that dramatically reduced code-breaking incidents.

1. Test-Driven Development

I now write tests BEFORE asking Claude to make changes. This provides immediate feedback when something breaks.

+-------------------+     +-------------------+     +-------------------+
|  RED: Write       |     |  GREEN: Ask       |     |  REFACTOR: Ask    |
|  failing test     | --> |  Claude to        | --> |  Claude to        |
|  first            |     |  pass test       |     |  improve code     |
+-------------------+     +-------------------+     +-------------------+
        |                         |                         |
        v                         v                         v
   Test fails                Test passes              Tests stay green
   (expected)                (minimal code)           (code improved)

With TDD, if Claude breaks code, tests fail immediately. Errors don’t compound.

2. Explicit Constraints

I specify what Claude should NOT do:

Refactor UserService to use dependency injection with these constraints:
1. Do NOT change any public method signatures
2. Keep the current error handling pattern
3. Maintain backward compatibility with existing callers
4. Only modify src/services/UserService.ts
5. Do not touch database files or migrations

This reduced unilateral changes significantly.

3. Skills and MCP Servers

Claude works better with structured tools. I configured:

  • Skills: Pre-defined workflows that constrain behavior
  • MCP Servers: Provide real-time context from my codebase
  • Code review agents: Automatic review after changes

Example workflow:

+-------------+     +-------------+     +-------------+     +-------------+
|  planner    | --> |  tdd-guide  | --> |  Claude     | --> |  code-      |
|  agent      |     |  agent      |     |  implements |     |  reviewer   |
+-------------+     +-------------+     +-------------+     +-------------+
      |                   |                   |                   |
      v                   v                   v                   v
 Implementation    Tests exist        Minimal code       Catches issues
 plan created     before coding      to pass tests      before commit

4. Incremental Changes

I break large tasks into small, verifiable steps:

  1. Ask Claude to make one specific change
  2. Run tests immediately
  3. Review the diff before accepting
  4. Repeat

Instead of “refactor the entire authentication system,” I now say:

  • “Add a test for password validation”
  • “Implement the minimum code to pass that test”
  • “Refactor the password validation to use the new pattern”

5. Project Context Before Starting

Before any session, I provide essential context:

Project: E-commerce platform with Spring Boot backend
Architecture: Microservices, event-driven
Key patterns:
  - Repository pattern for data access
  - Event sourcing for orders
  - Saga pattern for distributed transactions


Files to avoid modifying:
  - src/main/resources/db/migration/* (managed by Flyway)
  - src/test/integration/* (requires Docker, run locally only)


Current focus: UserService refactoring

This prevents Claude from accidentally breaking established patterns.

Common Mistakes I Made

Looking back, I see patterns in my failures.

Mistake 1: Large Refactors Without Tests

BAD:  "Refactor the entire authentication system"
GOOD: "Add a test for password validation, then implement it"

Mistake 2: Accepting Changes Without Review

I now always run git diff before accepting any changes. Claude’s diff view helps, but I need to see the actual code changes.

Mistake 3: No Incremental Validation

Don’t let Claude make 10 changes before running tests. Run tests after each change.

Terminal window
# BAD: Make many changes, then test
claude-code "Refactor X, Y, Z"
npm test


# GOOD: Change, test, change, test
claude-code "Refactor X"
npm test
claude-code "Refactor Y"
npm test

Mistake 4: Vague Instructions

BAD:  "Make this code better"
GOOD: "Extract the database connection logic into a separate utility
       function while maintaining the same public interface"

Mistake 5: Ignoring Claude’s Limitations

Claude can’t read my mind. It doesn’t know:

  • What I consider “better”
  • Which files are off-limits
  • What patterns I want to preserve
  • What tests need to pass

Before and After

Here’s how my requests changed:

Before (code-breaking request):

Refactor the user service to use dependency injection.

After (structured request):

Refactor the UserService class to use dependency injection.


Constraints:
1. Do NOT change any public method signatures
2. Keep the current error handling pattern
3. Maintain backward compatibility with existing callers
4. Only modify src/services/UserService.ts


Tests must pass after implementation.


Reference files:
- src/services/UserService.ts (target)
- tests/services/UserService.test.ts (tests)


Write tests FIRST if they don't exist.

The structured request takes longer to write but saves hours of debugging.

Summary

In this post, I explained why Claude Code breaks code and how to prevent it. The key insight is that Claude isn’t a magic code writer—it’s a powerful tool that requires proper usage patterns.

The practices that work:

  1. Test-Driven Development — Catch errors immediately
  2. Explicit Constraints — Tell Claude what NOT to do
  3. Skills and MCP Servers — Provide structured workflows
  4. Incremental Changes — Small steps with verification
  5. Project Context — Help Claude understand your codebase

Since implementing these practices, Claude went from a source of frustration to a reliable coding partner. The “breaking code” problem didn’t disappear entirely, but it became rare and predictable rather than constant and surprising.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!

Comments

Tags: