How I use Claude Code to handle merge conflicts — a complete workflow

Merge conflicts are the worst part of collaborative development. You're in the middle of a deployment, two branches have diverged, and now you're manually editing conflict markers in 47 files.

I've been using Claude Code to handle merge conflicts systematically, and it's changed how my team approaches branching strategy entirely.

Here's my complete workflow.

The problem with manual conflict resolution

When you resolve conflicts manually, you're making judgment calls under pressure:

• Which version of the logic is correct?
• Did both branches add important changes that need merging?
• Is this a semantic conflict (code compiles but behavior is wrong) that the diff doesn't show?
• Will the resolution break tests?

Manual resolution is error-prone because you're reading diffs without executing them. Claude Code can read both branches, understand the intent of each change, and propose resolutions that preserve the logic from both sides.

My conflict resolution workflow

Step 1: Start with context

Before touching any conflict markers, I give Claude Code the full picture:

We have a merge conflict. Here's the situation:
- main branch: added rate limiting to the payment endpoint
- feature/refactor: restructured the payment module into separate files
- Both changes are needed. Help me resolve the conflicts.

Run: git diff --name-only --diff-filter=U

This gets a list of all conflicted files upfront.

Step 2: Resolve file by file with intent

Open src/payments/processor.js and show me both conflict versions side by side.
Then propose a resolution that:
1. Keeps the rate limiting logic from main
2. Uses the new file structure from the feature branch
3. Doesn't duplicate the initialization code

Claude Code reads both versions and proposes a merge that preserves intent from both sides — not just picking one arbitrarily.

Step 3: Verify semantic correctness

After resolving each file:

Now run the test suite for the payments module.
If any tests fail, show me which tests and what they're testing.
Don't fix test failures automatically — explain what each failure means first.

This catches semantic conflicts that the merge tool can't detect.

Step 4: Validate the full resolution

Run: git diff HEAD --stat
Show me every file that changed and a one-line summary of what changed in each.
Flag anything that looks like it might have merged incorrectly.

A real example: the config conflict

We had a conflict in our database config that bit us twice before I started using this workflow.

main branch added:

// Added connection pooling
const pool = new Pool({
  max: 20,
  idleTimeoutMillis: 30000,
  connectionTimeoutMillis: 2000,
});

feature branch changed:

// Refactored to use environment-based config
const pool = new Pool({
  max: parseInt(process.env.DB_POOL_SIZE || '10'),
  idleTimeoutMillis: parseInt(process.env.DB_IDLE_TIMEOUT || '30000'),
});

Manual resolution: most developers pick one. The correct resolution merges both — environment-based config with the connection timeout from main:

const pool = new Pool({
  max: parseInt(process.env.DB_POOL_SIZE || '20'),
  idleTimeoutMillis: parseInt(process.env.DB_IDLE_TIMEOUT || '30000'),
  connectionTimeoutMillis: parseInt(process.env.DB_CONNECTION_TIMEOUT || '2000'),
});

Claude Code spotted this immediately when I described both branches' intent.

Handling the rate limit problem

Here's where merge conflict sessions get expensive: you're often resolving 20-50 conflicts across dozens of files. These sessions are long, context-heavy, and burn through tokens fast.

I've been using SimplyLouie as my API backend for long conflict-resolution sessions — it's a Claude API endpoint at $2/month that doesn't rate-limit mid-session when you're in the middle of resolving a critical conflict before a deployment.

The worst time to hit a rate limit is when you're 30 files into a merge conflict with a deployment window closing.

Pro tips for complex merges

For long-running feature branches:

Before I start resolving, show me a summary of what each branch was trying to accomplish.
Read the commit messages on both branches for the last 2 weeks.
This context will help you understand the intent behind each conflict.

For semantic conflicts (hardest to catch):

After resolving all conflicts, run the full test suite.
For any failure, trace back to which conflict resolution might have caused it.
Don't just fix the test — find the root cause in the merge.

For config/environment conflicts:

When resolving config files, always prefer the more flexible version (env vars over hardcoded values)
unless there's a specific reason the value should be locked.

The workflow in one prompt

For simple merges, I use this single starting prompt:

I have merge conflicts. Run these steps:
1. git diff --name-only --diff-filter=U  (list conflicted files)
2. For each file, show me both versions
3. Propose a resolution that preserves intent from both branches
4. Apply the resolution
5. Run tests after each file
6. At the end, run git diff HEAD --stat and summarize everything that changed

Start with the most complex file first.

Results

Since adopting this workflow:

• Merge-caused regressions: down 80%
• Time spent on complex merges: down 60%
• Semantic conflicts caught before deployment: 3 in the last month that would have been production bugs

The key insight is that merge conflict resolution is a reasoning problem, not just a text-editing problem. Claude Code can hold the intent of both branches in context and make intelligent decisions about which logic to preserve.

---

I use SimplyLouie for long Claude Code sessions — it's a $2/month API endpoint that keeps working when the official rate limits kick in during critical workflows like this one.