Resolver conflictos de Git con Claude Code de forma segura

Resolver un conflicto de Git no consiste solo en borrar <<<<<<<, ======= y >>>>>>>. Esos marcadores son la parte visible. Lo difícil es conservar la intención de dos ramas que cambiaron la misma zona del sistema: una puede haber reforzado autorización, mientras la otra añadió una pantalla, una llamada de API y pruebas.

Claude Code ayuda mucho porque puede leer archivos en conflicto, revisar código cercano, ejecutar comandos de Git, ajustar pruebas y explicar el diff final. Aun así, no conviene delegar el juicio completo. Si le pides simplemente “arregla los conflictos”, puede generar código que compila, pero pierde una regla de negocio o duplica una validación.

El flujo práctico es: una persona define prioridad y límites, Claude Code hace el trabajo mecánico, y la persona revisa diff, pruebas y comportamiento. Es el enfoque que uso en proyectos de ClaudeCodeLab para convertir una tarea tensa en un proceso repetible.

Mapa del flujo

cambios desde main o release
        |
        v
Git informa archivos sin fusionar
        |
        v
Claude Code resuelve con una política escrita
        |
        v
revisión humana de diff, pruebas y comportamiento
        |
        v
commit del estado resuelto

Para la ejecución no interactiva, consulta la documentación oficial de Claude Code CLI reference, donde aparece el patrón claude -p "query". Para automatizar revisiones, usa Claude Code hooks reference y Claude Code settings. En Git, Git rerere permite reutilizar resoluciones registradas.

Revisa el estado antes de editar

Antes de llamar a Claude Code, confirma que no estás mezclando cambios locales ajenos al conflicto.

git status --short
git branch --show-current
git diff --name-only --diff-filter=U

El último comando muestra solo archivos no resueltos. Léelo tú también. Si aparece un archivo inesperado, detente y entiende por qué está en conflicto antes de pedir cambios.

Incluye cuatro datos en el prompt:

Pregunta	Ejemplo de política
Qué lado tiene prioridad	Mantener arreglos de seguridad de main y la nueva UI de feature
Qué se puede editar	Solo archivos sin resolver y pruebas directamente relacionadas
Cómo tratar archivos generados	Regenerar lockfiles y código generado, no fusionarlos a mano
Cuándo termina	Sin marcadores, git diff --check limpio, pruebas pasando y resumen

Esta pequeña tabla evita que Claude Code adivine. Le da una base que luego puedes auditar.

Caso 1: fusionar main en una rama feature

El caso más común es una rama feature que se quedó atrás y necesita incorporar main antes del pull request.

git fetch origin
git merge origin/main

cat > /tmp/claude-conflict-plan.md <<'PROMPT'
Resuelve los conflictos actuales de Git merge.

Contexto:
- La rama actual es una rama feature.
- Mantén los arreglos de seguridad y cambios de tipos de origin/main.
- Mantén la nueva pantalla, la llamada de API y las pruebas de feature.
- Trabaja solo sobre archivos de git diff --name-only --diff-filter=U.

Tareas:
1. Explica brevemente por qué entra en conflicto cada archivo.
2. Elimina conflict markers e integra ambas intenciones.
3. Actualiza solo pruebas directamente relacionadas si hace falta.
4. Ejecuta git diff --check.
5. Resume decisiones y comandos ejecutados.

No hagas:
- Refactors no relacionados.
- Descartar un lado sin explicarlo.
- Editar package-lock.json a mano.
PROMPT

claude -p "$(cat /tmp/claude-conflict-plan.md)"
git diff --check
npm test

La clave no es la redacción exacta, sino escribir prioridad, alcance, política de archivos generados y condición de finalización. Así el resultado es revisable.

Una vez, main agregó una regla de autorización más estricta y la feature agregó una rama de UI. Un prompt vago que decía “conserva ambos cambios” dejó visible la UI, pero la API seguía devolviendo 403. Desde entonces especifico que las reglas de seguridad y autorización deben sobrevivir y que se revise la coherencia entre UI y API.

Caso 2: resolver rebase paso a paso

Los conflictos durante git rebase son más delicados que un merge normal porque Git pausa en cada commit. Además, ours y theirs pueden resultar contraintuitivos durante un rebase, así que no conviene usar git checkout --ours sin mirar el diff.

git rebase origin/main

cat > /tmp/claude-rebase-step.md <<'PROMPT'
Resuelve solo el conflicto actual de este rebase.

Primero:
- Confirma con git status que estamos en rebase.
- Lista archivos no resueltos con git diff --name-only --diff-filter=U.
- Infiera la intención del commit actual desde git log reciente.
- Integra la intención del commit con el comportamiento actual de main.

Restricciones:
- No ejecutes git rebase --continue.
- Detente después de resolver y hacer git add.
- No edites archivos no relacionados.
- Si una decisión es ambigua, explica opciones en lugar de adivinar.
PROMPT

claude -p "$(cat /tmp/claude-rebase-step.md)"
git diff --check
npm test
git rebase --continue

Puedes automatizar más, pero para principiantes es mejor revisar cada paso. Un rebase reescribe la historia de la rama; si una resolución mala avanza varios commits, cuesta más encontrar dónde cambió el significado.

Caso 3: lockfiles y código generado

package-lock.json, pnpm-lock.yaml, código generado por OpenAPI o Prisma y snapshots grandes no deberían fusionarse línea a línea. Primero resuelve el archivo fuente, luego regenera.

cat > /tmp/claude-lockfile-policy.md <<'PROMPT'
Resuelve conflictos de lockfile o archivos generados.

Política:
- Resuelve primero archivos mantenidos por humanos, como package.json o schema.
- No fusiones package-lock.json manualmente.
- Cuando las dependencias estén decididas, regenera con npm install.
- Para código generado, resuelve primero la fuente y luego regenera.
- Explica por qué el diff regenerado es esperado.

Puedes ejecutar:
- npm install
- npm test
- npm run lint
PROMPT

claude -p "$(cat /tmp/claude-lockfile-policy.md)"
npm install
npm test
git add package.json package-lock.json

El error típico es mantener ambas dependencias en package.json, pero aceptar solo un lado del lockfile. Puede funcionar en local y fallar en CI. La regla debe ser explícita: fuente primero, salida generada después.

Caso 4: analizar la causa

Resolver el conflicto es solo la mitad. Si siempre chocan rutas, mapas de permisos, schemas o dependencias, el equipo tiene un problema de propiedad o de tamaño de PR.

cat > /tmp/claude-conflict-retro.md <<'PROMPT'
Analiza por qué ocurrió este Git conflict.

Investiga:
- Lista archivos con git diff --name-only --diff-filter=U.
- Usa git log --oneline --all -- <file> para mirar ambas ramas.
- Clasifica si fue propiedad compartida, PR demasiado grande, ruido generado o falta de regla.

Salida:
- Resumen de causa en tres líneas.
- Reglas para agregar a CLAUDE.md.
- Si ayuda más dividir PR, coordinar ownership o añadir pruebas.
PROMPT

claude -p "$(cat /tmp/claude-conflict-retro.md)"

Si src/routes.ts entra en conflicto cada semana, quizá haya que dividir el registro de rutas por feature. Si package.json choca siempre, conviene separar cambios de dependencias. Claude Code puede detectar el patrón mirando historial y archivos cercanos.

Verificación y reglas del equipo

Después de editar, ejecuta al menos:

git diff --check
git diff --name-only --diff-filter=U
npm test

Agrega typecheck, lint o E2E cuando el conflicto toque contratos, rutas, pagos o autorización. Para automatizar checks, revisa la guía de hooks de Claude Code.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash(git merge*)|Bash(git rebase*)",
        "hooks": [
          {
            "type": "command",
            "command": "git diff --check && npm test"
          }
        ]
      }
    ]
  }
}

También conviene documentar la política en CLAUDE.md. Es la memoria de proyecto que Claude Code usa para entender reglas locales. Mira CLAUDE.md best practices y la guía de colaboración en equipo.

## Git conflict policy
- Conservar por defecto seguridad, autorización y prevención de pérdida de datos.
- Revisar UI, API, schema y tests en conjunto.
- Regenerar lockfiles y código generado en vez de editarlos a mano.
- Durante rebase, una persona revisa el diff antes de git rebase --continue.
- Si la decisión no es clara, presentar opciones y no descartar un lado.

Errores comunes y resultado

No memorices ours y theirs como etiquetas permanentes; durante rebase pueden sorprender. No asumas que “mantener ambos” siempre es correcto: dos validaciones o dos redirects pueden duplicar comportamiento. Y no termines solo porque las pruebas pasaron; autenticación, pagos, migraciones y borrado de datos necesitan revisión humana.

En una prueba de Masa con un proyecto TypeScript y unos 15 archivos en conflicto, un prompt vago arregló la sintaxis pero olvidó actualizar una prueba relacionada. Con la política de este artículo, Claude Code produjo un diff más pequeño, explicó decisiones y redujo el tiempo de review.

Empieza con una rama pequeña: lista archivos sin resolver, entrega una política clara, ejecuta pruebas y revisa el diff. Cuando el proceso sea estable, mueve las reglas repetidas a hooks y CLAUDE.md para que el equipo tenga una práctica consistente.