13. Git, GitHub y trabajo en equipo

Objetivo del tema

Usar Claude Code dentro de un flujo colaborativo y auditable: preparar ramas seguras, revisar cambios antes de confirmarlos, crear commits y pull requests útiles, responder revisiones, resolver conflictos con criterio, aislar sesiones paralelas mediante worktrees y automatizar tareas con GitHub sin entregar permisos innecesarios.

13.1 Tres capas del flujo colaborativo

Claude puede ejecutar comandos Git porque dispone de la misma CLI que tú, no porque Git haya dejado de tener reglas. Un cambio generado por un agente debe recorrer las mismas políticas de rama, revisión y CI que cualquier contribución humana.

13.2 Preparar identidad, remoto y herramientas

Antes de pedir cambios, verifica el entorno con operaciones de sólo lectura:

git status --short --branch
git remote -v
git log --oneline -5
git config user.name
git config user.email

gh --version
gh auth status

GitHub CLI (gh) permite crear PRs, leer checks e interactuar con issues desde Claude Code. Autentícala con gh auth login y concede sólo los alcances necesarios. No pegues tokens en el prompt ni los incluyas en comandos que puedan quedar en el historial.

13.3 Estado limpio, rama pequeña y alcance explícito

Actualiza referencias remotas sin modificar tu trabajo y crea una rama desde la base acordada:

git fetch origin
git switch main
git pull --ff-only
git switch -c feat/validacion-registro

--ff-only evita crear un merge inesperado durante el pull. Si el equipo usa rebase, trunk-based development u otra base, documenta esa política en CLAUDE.md. Una rama debería representar una unidad revisable, no toda una conversación.

Separar implementación de commit permite revisar antes de registrar. Para tareas de alto riesgo, separa también diagnóstico, edición y ejecución de comandos.

13.4 Revisar el trabajo antes del commit

Revisión progresiva del árbol de trabajo

Comando	Responde	Qué buscar
git status --short	¿Qué archivos cambiaron?	Archivos accidentales, secretos, caches y generados.
git diff --stat	¿Cuál es el tamaño?	Un cambio desproporcionado respecto del pedido.
git diff	¿Qué líneas cambiaron?	Contrato, errores, compatibilidad y código eliminado.
git diff --check	¿Hay errores de whitespace?	Marcadores, espacios finales y formato problemático.
Tests y lint	¿El comportamiento está verificado?	Salida completa, casos nuevos y warnings.

No dependas únicamente del resumen de Claude. Lee el diff real y abre los archivos importantes. Si el cambio mezcla una corrección con una refactorización, pide dividirlo antes del commit.

13.5 Commits atómicos y mensajes útiles

Cuando el diff sea correcto, puedes pedir que proponga un mensaje sin confirmar todavía:

Luego selecciona archivos explícitamente y revisa el área preparada:

git add src/registro.js tests/registro.test.js
git diff --cached
git commit -m "feat: valida correo en el registro"
git show --stat --oneline HEAD

Evita git add -A cuando el árbol contiene cambios ajenos. Un commit atómico puede revertirse y revisarse por sí solo. No incluyas “generado por IA” salvo que la política del equipo lo exija; sí conserva trazabilidad mediante issue, PR, pruebas y autores reales.

13.6 Crear un pull request verificable

Publica la rama y crea el PR con GitHub CLI:

git push -u origin feat/validacion-registro
gh pr create --draft \
  --title "Valida correo durante el registro" \
  --body-file .github/PULL_REQUEST_TEMPLATE.md

Si no existe plantilla, pide a Claude un cuerpo basado en el diff y luego revísalo. Debe explicar objetivo, decisiones, pruebas, riesgo, migración y capturas cuando corresponda. Nunca afirmes “todos los tests pasan” si sólo se ejecutó una suite parcial.

## Qué cambia
- Valida formato de correo antes de persistir el usuario.
- Conserva el código de error público acordado.

## Cómo se verificó
- `npm test -- registro`: 12 tests aprobados.
- Suite completa no ejecutada: requiere servicio externo.

## Riesgo y reversión
- Riesgo bajo; no modifica esquema ni dependencias.
- Revertir este commit restaura el comportamiento anterior.

13.7 Revisar un PR con Claude sin delegar la decisión

Para una revisión local, trae la rama o inicia un worktree desde el PR. Pide primero hallazgos, no ediciones:

gh pr view 142
gh pr checks 142
gh pr diff 142

# Worktree aislado creado por Claude Code
claude --worktree "#142"

Verifica cada observación contra el código y las pruebas. Un comentario automático no reemplaza al propietario del dominio. La función administrada Code Review publica comentarios inline mediante análisis multiagente, pero a agosto de 2026 continúa en research preview para Team y Enterprise y no aprueba ni bloquea PRs.

13.8 Responder comentarios y mantener el PR enfocado

Convierte cada comentario aceptado en una tarea comprobable. Claude debe leer el hilo y el código actual, porque la observación puede haber quedado obsoleta tras otro push:

Después de corregir, crea un commit adicional mientras la revisión está activa; evita reescribir historia si otras personas ya basaron comentarios en esos commits. Responde explicando qué cambió y cita la prueba:

git add src/registro.js tests/registro.test.js
git commit -m "fix: preserva correos normalizados"
git push
gh pr checks --watch

Resolver una conversación en GitHub es una decisión humana: una respuesta fluida de Claude no demuestra que el revisor esté de acuerdo.

13.9 Resolver conflictos con intención

Un conflicto no es un error sintáctico; representa dos historias incompatibles. Actualiza tu rama según la política del equipo:

git fetch origin
git rebase origin/main

# inspeccionar conflictos
git status
git diff --name-only --diff-filter=U

Pide a Claude que explique ambos lados antes de editar. Tras resolver cada archivo, ejecuta pruebas relevantes y continúa:

git add ruta/resuelta.js
git rebase --continue

# sólo si necesitas abandonar y volver al estado anterior
git rebase --abort

13.10 Trabajo paralelo con worktrees

Dos sesiones sobre la misma carpeta pueden pisarse. Un worktree aporta archivos y rama independientes compartiendo historial y remoto:

# aceptar primero la confianza ejecutando claude una vez en el repo
claude --worktree feature-auth
claude --worktree bugfix-142

git worktree list

Claude Code los crea por defecto bajo .claude/worktrees/; agrega esa ruta a .gitignore. Cada worktree requiere instalar dependencias o preparar su entorno. Los archivos ignorados como .env no aparecen automáticamente; usa .worktreeinclude sólo para los estrictamente necesarios y evalúa el riesgo de replicar secretos.

Elegir una forma de paralelismo

Mecanismo	Úsalo para	Aislamiento
Worktree	Sesiones independientes que editan archivos.	Archivos y rama separados.
Subagente	Investigación lateral que vuelve como resumen.	Contexto separado; worktree opcional.
claude agents	Despachar y supervisar varias tareas independientes.	Usa worktrees al editar; research preview.
Equipo de agentes	Trabajadores que coordinan tareas y mensajes.	No aísla archivos por sí solo; experimental.

13.11 Claude Code GitHub Actions

La acción oficial puede responder a menciones @claude o ejecutar un prompt ante eventos. La configuración rápida requiere acceso administrativo, GitHub CLI autenticada y una revisión consciente de permisos:

gh auth status
claude
/install-github-app

El asistente instala la GitHub App, configura el secreto y abre un PR con los workflows. Revisa ese PR como código de producción. El modo interactivo espera una mención; el modo automatizado incluye un prompt en el workflow. Un ejemplo mínimo vigente usa anthropics/claude-code-action@v1:

name: Claude Code
on:
  issue_comment:
    types: [created]

jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
      actions: read
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

GitHub interpretará la expresión de secreto; nunca reemplaces esa referencia por el valor real. Para organizaciones, prefiere OIDC y cuentas de servicio cuando estén disponibles, limita --max-turns, fija timeout y concurrencia, y restringe quién puede disparar ejecuciones. La acción comprueba por defecto que el actor sea humano y tenga acceso de escritura.

13.12 Seguridad, checklist y entrega

Antes de fusionar trabajo asistido por Claude

Control	Resultado esperado
Alcance	Issue, rama, commits y diff representan una sola intención.
Secretos	Ninguna credencial en archivos, prompts, logs o historial.
Evidencia	Pruebas y checks ejecutados; limitaciones declaradas.
Revisión	Hallazgos automáticos verificados y aprobación humana requerida.
Permisos	GitHub App, workflow y token con el alcance mínimo viable.
Paralelismo	Sesiones aisladas y cambios integrados deliberadamente.
Merge	Política del equipo respetada; rama protegida y CI en verde.

Consulta las guías oficiales de worktrees, GitHub Actions y Code Review para cambios de compatibilidad y disponibilidad.

Conclusión: Claude Code acelera implementación, documentación y revisión, pero Git y GitHub siguen definiendo la unidad de colaboración. Un flujo profesional comienza con estado conocido, termina con evidencia y conserva la decisión de merge en manos del equipo. En el próximo tema personalizaremos Claude Code mediante subagentes, comandos y permisos.