Git Workflows con Claude Code

Descripción

Git y Claude Code son una combinación natural. Ambos viven en la terminal, ambos trabajan con archivos de código, y ambos siguen workflows estructurados. La diferencia es que ahora no necesitas escribir cada git add, git commit -m "...", y git push manualmente — Claude Code puede gestionar todo el flujo de Git por ti, desde crear branches hasta abrir Pull Requests.

Pero "Claude Code sabe Git" no significa "déjale hacer lo que quiera con tu historial". Esta cápsula cubre cómo integrar Git con Claude Code de forma controlada: qué operaciones delegar, qué patterns seguir, cómo garantizar commits semánticos, y cómo mantener un historial limpio cuando un agente de IA está contribuyendo código.

La habilidad no es que Claude ejecute comandos de Git — es que tú diseñes un workflow donde Git y Claude Code se potencian mutuamente.

Claude Code y Git: qué puede hacer

Claude Code tiene acceso completo a Git a través de la terminal. No usa una API especial — ejecuta los mismos comandos que tú ejecutarías. Esto significa que puede hacer todo lo que Git permite:

Operaciones básicas

Operaciones avanzadas

Lo que Claude Code aporta que Git no tiene

La diferencia clave: Claude Code entiende el contexto de los cambios. Git sabe que cambiaste la línea 42 de auth.py. Claude Code sabe que cambiaste la validación de tokens porque la anterior no manejaba tokens expirados.

Git solo:
  git commit -m "update auth.py"    ← ¿qué cambió? ¿por qué?

Claude Code + Git:
  git commit -m "fix(auth): handle expired JWT tokens
  
  Previously, expired tokens returned a generic 401 error.
  Now returns a specific 'token_expired' error code with
  the expiration timestamp, allowing clients to refresh
  automatically."

Workflow Pattern 1: Feature Branch

El pattern más común. Claude Code crea una branch, implementa el feature, hace commits progresivos, y abre un PR.

Ejemplo básico

Tú: Crea un endpoint /api/health que devuelva el estado del 
    servidor. Trabaja en una branch separada y haz un commit 
    cuando termines.

Claude Code ejecuta:

git checkout -b feature/health-endpoint

# ... implementa el endpoint ...

git add src/routes/health.py
git commit -m "feat(api): add /health endpoint

Returns server status including uptime, version, and
database connection status. Responds with 200 for healthy
and 503 for degraded state."

Ejemplo intermedio

Tú: Implementa el sistema de notificaciones por email. 
    Crea una branch, haz commits separados para cada paso 
    lógico, y abre un PR cuando termines.

Claude Code ejecuta:

git checkout -b feature/email-notifications

# Paso 1: modelo y schema
git add src/models/notification.py src/schemas/notification.py
git commit -m "feat(notifications): add Notification model and schema

SQLAlchemy model with fields: id, user_id, type, subject,
body, sent_at, read_at. Pydantic schema for validation."

# Paso 2: servicio de envío
git add src/services/email_service.py
git commit -m "feat(notifications): add email sending service

Uses SMTP with async support. Includes retry logic (3 attempts)
and template rendering with Jinja2."

# Paso 3: endpoint API
git add src/routes/notifications.py
git commit -m "feat(api): add notification endpoints

POST /notifications/send - send notification
GET /notifications - list user notifications
PATCH /notifications/:id/read - mark as read"

# Paso 4: tests
git add tests/test_notifications.py
git commit -m "test(notifications): add unit and integration tests

Covers email sending, retry logic, template rendering,
and all API endpoints. Uses mock SMTP for unit tests."

# Abrir PR
gh pr create \
  --title "feat: email notification system" \
  --body "## Summary
- New Notification model with SQLAlchemy
- Email service with async SMTP and retry logic  
- REST endpoints for sending and managing notifications
- Full test coverage

## Testing
- Run: pytest tests/test_notifications.py
- Manual: POST to /notifications/send with valid payload"

Cuándo usar este pattern

• Features nuevos que requieren múltiples archivos
• Cambios que necesitan code review antes de merge
• Trabajo que puede tomar varias sesiones de Claude Code
• Proyectos con CI/CD que ejecuta tests en PRs

Workflow Pattern 2: Commit-as-you-go

Claude Code hace un commit después de cada cambio significativo. El historial refleja el progreso paso a paso.

Ejemplo básico

Tú: Refactoriza el módulo de autenticación. Después de cada 
    cambio lógico, haz un commit explicando qué hiciste y por qué.

Claude Code trabaja incrementalmente:

git commit -m "refactor(auth): extract token validation to separate module

Moves JWT validation logic from auth_middleware.py to
token_validator.py. Reduces middleware complexity and
makes validation reusable across routes."

# ... siguiente cambio ...

git commit -m "refactor(auth): replace hardcoded expiry with config

Token expiration was hardcoded to 3600s. Now reads from
AUTH_TOKEN_EXPIRY env var with 3600s default."

# ... siguiente cambio ...

git commit -m "refactor(auth): add refresh token rotation

Implements refresh token rotation: each refresh generates
a new refresh token and invalidates the previous one.
Prevents refresh token replay attacks."

Cuándo usar este pattern

• Refactorizaciones donde quieres un historial granular
• Sesiones largas donde cada paso debe ser reversible
• Cuando trabajas sin PR (commits directos a una branch de desarrollo)
• Para aprender: cada commit documenta qué hizo Claude y por qué

Workflow Pattern 3: Review Before Commit

Claude Code muestra los cambios, tú los revisas, y luego Claude hace el commit. El patrón más seguro para código crítico.

Ejemplo básico

Tú: Corrige el bug en el cálculo de precios. Muéstrame el diff 
    antes de hacer commit — quiero revisarlo.

Claude Code:

He identificado el bug y aplicado la corrección. Aquí está el diff:

--- a/src/services/pricing.py
+++ b/src/services/pricing.py
@@ -45,7 +45,7 @@ def calculate_total(items, discount):
-    total = sum(item.price for item in items)
-    return total - discount
+    subtotal = sum(item.price * item.quantity for item in items)
+    discount_amount = subtotal * (discount / 100)
+    return max(subtotal - discount_amount, 0)

El bug era doble:
1. No multiplicaba precio × cantidad
2. Aplicaba el descuento como valor absoluto en lugar de porcentaje

¿Quieres que haga el commit?

Tú: Sí, hazlo.

git add src/services/pricing.py
git commit -m "fix(pricing): correct total calculation with quantity and percentage discount

Two bugs fixed:
1. Price calculation now multiplies by item quantity
2. Discount applied as percentage instead of absolute value
3. Added floor of 0 to prevent negative totals"

Cuándo usar este pattern

• Código en producción o código crítico
• Cuando no estás 100% seguro de lo que Claude va a cambiar
• Para builds de confianza: revisas primero, confías más después
• Áreas del codebase que no dominas completamente

Conventional Commits con Claude Code

Conventional commits son un estándar para mensajes de commit que facilitan la generación de changelogs, versionado semántico, y comprensión del historial.

El formato

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Tipos que Claude Code usa

Cómo pedirle a Claude Code que use conventional commits

En tu CLAUDE.md:

# Git conventions

- Usa conventional commits: type(scope): description
- Types: feat, fix, docs, style, refactor, test, chore, perf, ci
- Scope: el módulo o área afectada (auth, api, db, ui, etc.)
- Description: imperativo, lowercase, sin punto final
- Body: explica el "por qué", no el "qué" (el diff ya muestra el qué)
- Max 72 caracteres en la primera línea

Con esta instrucción en CLAUDE.md, Claude Code generará commits consistentes automáticamente.

Pull Requests con Claude Code

Claude Code puede crear Pull Requests completos usando gh CLI (GitHub CLI). No solo ejecuta el comando — genera descripciones detalladas basadas en los cambios reales.

Ejemplo básico

Tú: Abre un PR para esta branch.

gh pr create \
  --title "feat: add email notification system" \
  --body "## Summary
Adds a complete email notification system with async SMTP support.

## Changes
- New \`Notification\` model (SQLAlchemy)
- Email service with retry logic and Jinja2 templates
- REST endpoints: send, list, mark as read
- Full test coverage (unit + integration)

## Testing
\`\`\`bash
pytest tests/test_notifications.py -v
\`\`\`

## Screenshots
N/A (backend only)"

Ejemplo avanzado: PR con contexto completo

Tú: Abre un PR con descripción detallada. Incluye qué cambió, 
    por qué, cómo probarlo, y cualquier breaking change.

Claude Code analiza todos los commits en la branch, los diffs, y genera:

gh pr create \
  --title "refactor: migrate auth from sessions to JWT" \
  --body "## Summary
Migrates the authentication system from server-side sessions to 
stateless JWT tokens. This eliminates the Redis session store 
dependency and enables horizontal scaling.

## Motivation
The current session-based auth requires a shared Redis instance 
across all server replicas. With JWT, each request is self-contained 
and any replica can validate it independently.

## Changes
- \`src/auth/\`: replaced session middleware with JWT middleware
- \`src/models/user.py\`: added \`refresh_token_hash\` field
- \`src/routes/auth.py\`: new login/refresh/logout endpoints
- \`config/\`: added JWT_SECRET, TOKEN_EXPIRY settings
- Removed: \`src/sessions/\`, Redis configuration

## Breaking Changes
⚠️ **All existing sessions will be invalidated.** Users need to 
log in again after deployment.

API changes:
- \`POST /auth/login\` now returns \`{ access_token, refresh_token }\`
- All authenticated endpoints require \`Authorization: Bearer <token>\`
- \`POST /auth/refresh\` replaces automatic session refresh

## Migration Guide
1. Deploy the new code
2. Run \`python manage.py migrate\` for the new DB field
3. Remove Redis session store configuration
4. Update frontend to use token-based auth

## Testing
\`\`\`bash
pytest tests/test_auth.py -v
pytest tests/test_integration.py -v
\`\`\`

## Checklist
- [x] Unit tests pass
- [x] Integration tests pass
- [x] Migration script tested
- [x] Documentation updated"

Code Review con Claude Code

Claude Code puede actuar como un code reviewer. Puede analizar diffs, identificar problemas, y explicar cambios.

Revisar un diff

Tú: Revisa los cambios que hice hoy. ¿Hay algo que mejorar?

Claude Code ejecuta git diff (o git diff --staged), analiza los cambios, y responde:

He revisado tus cambios. Observaciones:

1. **src/services/user.py:34** - La query no tiene límite. Si la tabla 
   tiene millones de registros, esto va a ser un problema:
   
   users = db.query(User).filter(User.active == True).all()
   
   Sugiero agregar paginación o al menos un .limit().

2. **src/routes/users.py:67** - El endpoint acepta un user_id como 
   string pero no lo valida. Un UUID inválido causará un 500 en lugar 
   de un 400.

3. **tests/test_users.py** - Buen coverage, pero falta un test para el 
   caso de usuario no encontrado (404).

¿Quieres que aplique estas correcciones?

Revisar un PR de otra persona

Tú: Revisa el PR #42 de GitHub. Enfócate en seguridad y performance.

gh pr diff 42

Claude Code lee el diff del PR y da feedback enfocado en lo que pediste.

Resolución de merge conflicts

Cuando hay conflictos en un merge, Claude Code puede entender ambos lados y proponer una resolución informada.

Ejemplo

Tú: Tengo conflictos de merge. Resuélvelos manteniendo la 
    funcionalidad de ambas branches.

Claude Code lee los archivos con conflictos:

<<<<<<< HEAD
def calculate_price(item, quantity):
    base = item.price * quantity
    return base * 0.9  # 10% member discount
=======
def calculate_price(item, quantity, discount_code=None):
    base = item.price * quantity
    if discount_code:
        discount = get_discount(discount_code)
        return base * (1 - discount)
    return base
>>>>>>> feature/discount-codes

Y propone:

def calculate_price(item, quantity, discount_code=None):
    base = item.price * quantity
    if discount_code:
        discount = get_discount(discount_code)
        return base * (1 - discount)
    return base * 0.9  # 10% member discount (default when no code)

Claude Code entiende que HEAD agregó un descuento fijo para miembros y la otra branch agregó soporte para códigos de descuento. La resolución mantiene ambas funcionalidades.

Comparaciones y decisiones

¿Cuándo dejar que Claude Code haga commits vs hacerlos tú?

¿Branch o commit directo?

Patterns comunes

Pattern: Git status al inicio de sesión

Agrega a tu CLAUDE.md:

# Al iniciar sesión
- Ejecuta git status para verificar el estado del repo
- Si hay cambios sin commit, pregúntame qué hacer antes de continuar
- Si estamos en una branch de feature, continúa el trabajo

Pattern: Commits atómicos

Tú: Implementa estos cambios. Haz commits atómicos — cada commit 
    debe hacer exactamente una cosa y el proyecto debe compilar 
    después de cada commit.

Claude Code se asegura de que:

1. Cada commit es independiente y compila
2. Los tests pasan después de cada commit
3. El mensaje describe exactamente qué cambió

Pattern: Branch protection

En tu CLAUDE.md:

# Git rules
- NUNCA hagas push directamente a main
- NUNCA hagas force push
- Siempre trabaja en branches de feature
- Nombra branches: feature/*, fix/*, docs/*, refactor/*

Protocolos de Seguridad Git en Claude Code

Claude Code tiene reglas de seguridad integradas para proteger tu repositorio. Estas reglas son automáticas — no necesitas configurarlas.

Reglas obligatorias

1. Co-Authored-By en todos los commits:

Todo commit creado por Claude Code incluye automáticamente:

Co-Authored-By: Claude <noreply@anthropic.com>

Esto permite rastrear qué código fue generado con AI — importante para auditorías, compliance, y transparencia.

2. Nunca force push:

Claude Code nunca ejecutará git push --force a menos que tú lo solicites explícitamente. Incluso si lo pides, te advertirá si el target es main o master.

3. Nunca skip hooks:

Los flags --no-verify y --no-gpg-sign nunca se usan automáticamente. Si un pre-commit hook falla, Claude Code investiga y corrige el problema en vez de saltarse la validación.

4. Commits nuevos sobre amend:

Claude Code siempre prefiere crear un commit nuevo en vez de usar --amend. ¿Por qué? Si un pre-commit hook falla, el commit NO se creó — hacer --amend modificaría el commit ANTERIOR, potencialmente destruyendo trabajo previo.

5. Staging selectivo:

Claude Code agrega archivos específicos por nombre (git add file.py) en vez de git add -A o git add ., para evitar incluir accidentalmente archivos sensibles (.env, credentials) o binarios grandes.

Qué significa para ti

✅ Puedes confiar en que Claude Code no destruirá tu historial
✅ Los pre-commit hooks siempre se ejecutan
✅ Los commits tienen trazabilidad de AI
✅ Los archivos sensibles no se incluyen accidentalmente

Pitfalls y edge cases

Pitfall 1: Claude Code hace push sin que lo pidas

Por defecto, Claude Code pide permiso antes de ejecutar git push. Pero si configuraste Execute(git push*) en allowedTools, lo hará sin preguntar. Asegúrate de que tus permisos son los correctos.

Solución: No pongas git push en allowedTools si quieres revisar antes de push.

Pitfall 2: Commits gigantes

A veces Claude Code acumula muchos cambios y hace un solo commit enorme. Esto dificulta el code review y el rollback.

Solución: Pide explícitamente commits granulares:

Haz commits separados para cada cambio lógico. 
No acumules múltiples cambios en un solo commit.

Pitfall 3: Mensajes de commit genéricos

Si no le dices a Claude Code qué estilo de commits usar, puede generar mensajes como "update files" o "fix bug".

Solución: Conventional commits en CLAUDE.md (ver sección anterior).

Pitfall 4: Conflictos con cambios locales

Si tienes cambios no committeados y le pides a Claude Code que haga checkout a otra branch, puede fallar o perder tu trabajo.

Solución: Claude Code debería ejecutar git stash antes de cambiar de branch. Agrégalo a CLAUDE.md:

# Antes de cambiar de branch
- Si hay cambios sin commit, haz git stash
- Después de volver a la branch original, haz git stash pop

Pitfall 5: Force push accidental

Claude Code nunca debería hacer git push --force en branches compartidas. Pero si se lo pides, lo hará.

Solución: Bloquea force push en tus permisos o en CLAUDE.md:

# PROHIBIDO
- git push --force (en cualquier branch)
- git push --force-with-lease (solo permitido en branches personales)
- git reset --hard en branches compartidas

Ejemplo completo integrado

Un workflow completo de inicio a fin:

Sesión de Claude Code
─────────────────────

Tú: Necesito agregar un sistema de rate limiting al API. 
    Trabaja en una branch, haz commits incrementales con 
    conventional commits, y abre un PR cuando termines.

Claude Code:
─────────────
# 1. Verificar estado del repo
$ git status
On branch main
nothing to commit, working tree clean

# 2. Crear branch
$ git checkout -b feature/rate-limiting

# 3. Implementar middleware
# ... escribe src/middleware/rate_limiter.py ...
$ git add src/middleware/rate_limiter.py
$ git commit -m "feat(middleware): add token bucket rate limiter

Implements token bucket algorithm with configurable rate
and burst size. Supports per-IP and per-user limiting.
Uses Redis for distributed rate limiting across replicas."

# 4. Configuración
# ... escribe src/config/rate_limits.py ...
$ git add src/config/rate_limits.py
$ git commit -m "feat(config): add rate limiting configuration

Default limits: 100 req/min for authenticated users,
20 req/min for anonymous. Configurable per-endpoint
via RATE_LIMIT_* environment variables."

# 5. Integrar con rutas
# ... modifica src/main.py ...
$ git add src/main.py
$ git commit -m "feat(api): apply rate limiting middleware

Rate limiter applied globally with per-endpoint overrides.
Auth endpoints: 10 req/min (brute force protection).
Upload endpoints: 5 req/min (resource protection)."

# 6. Tests
# ... escribe tests/test_rate_limiter.py ...
$ git add tests/test_rate_limiter.py
$ git commit -m "test(rate-limiting): add comprehensive test suite

Tests cover: token bucket refill, burst handling, Redis
failure fallback, per-user vs per-IP limits, and
concurrent request handling."

# 7. Push y PR
$ git push -u origin feature/rate-limiting
$ gh pr create \
    --title "feat: add API rate limiting with token bucket" \
    --body "## Summary
    Adds rate limiting to all API endpoints using token bucket 
    algorithm with Redis backend.
    
    ## Changes
    - Token bucket rate limiter middleware
    - Configurable limits per endpoint and user type
    - Redis backend for distributed limiting
    - Comprehensive test suite
    
    ## Testing
    pytest tests/test_rate_limiter.py -v
    
    ## Configuration
    Set RATE_LIMIT_DEFAULT=100 for custom limits.
    See src/config/rate_limits.py for all options."

Ejercicios prácticos

Ejercicio 1: Básico — Feature branch con commits

Pide a Claude Code que implemente una funcionalidad simple (por ejemplo, un endpoint que devuelve la fecha actual) usando el pattern de feature branch.

Requisitos:

• Crear branch feature/current-date
• Implementar el endpoint
• Commit con conventional commit
• Verificar con git log --oneline

Tú: Crea una branch feature/current-date. Implementa un endpoint 
    GET /api/date que devuelva la fecha y hora actual en formato ISO. 
    Haz commit con conventional commit.

git checkout -b feature/current-date

git add src/routes/date.py
git commit -m "feat(api): add /date endpoint returning current ISO datetime"
git log --oneline -3

Ejercicio 2: Intermedio — Conventional commits en CLAUDE.md

Configura conventional commits en tu CLAUDE.md y verifica que Claude Code los sigue.

Requisitos:

• Agrega una sección "Git conventions" a CLAUDE.md
• Pide a Claude Code 3 cambios diferentes (feat, fix, docs)
• Verifica que los commits siguen el formato

# Git conventions
- Conventional commits obligatorios: type(scope): description
- Tipos permitidos: feat, fix, docs, style, refactor, test, chore
- Scope: el módulo afectado
- Descripción: imperativa, en inglés, sin punto final, max 72 chars
- Body: explicar el "por qué" cuando no sea obvio

1. Tú: Agrega un endpoint /api/version que devuelva la versión de la app
2. Tú: El endpoint /api/health devuelve 500 cuando la DB está desconectada. Debería devolver 503.
3. Tú: Agrega un README explicando cómo ejecutar el proyecto

git log --oneline -3
# feat(api): add /version endpoint returning app version
# fix(api): return 503 instead of 500 when DB is disconnected  
# docs(readme): add project setup and run instructions

Ejercicio 3: Intermedio — PR con descripción completa

Después de implementar un feature en una branch, pide a Claude Code que abra un PR con descripción detallada.

Requisitos:

• Tener al menos 2 commits en una branch de feature
• PR con: summary, changes, testing instructions, checklist
• Usar gh pr create

Tú: Abre un PR para esta branch. Incluye un resumen de todos los 
    cambios, instrucciones de testing, y un checklist de review.

gh pr create \
  --title "feat: add user notification preferences" \
  --body "## Summary
Adds the ability for users to configure their notification 
preferences (email, push, SMS) per event type.

## Changes
- \`NotificationPreference\` model with per-event settings
- CRUD endpoints for preferences
- Integration with existing notification service
- Migration script for new DB table

## Testing
\`\`\`bash
pytest tests/test_preferences.py -v
\`\`\`
Manual: POST to /api/users/me/preferences with payload

## Checklist
- [x] Unit tests
- [x] Integration tests  
- [x] Migration tested
- [ ] Frontend integration (separate PR)"

Ejercicio 4: Avanzado — Resolve merge conflicts

Simula un conflicto de merge y pide a Claude Code que lo resuelva.

Pasos:

1. Crea dos branches desde main
2. En cada branch, modifica el mismo archivo de forma diferente
3. Merge una branch en main
4. Intenta merge la segunda — habrá conflicto
5. Pide a Claude Code que resuelva el conflicto

# Branch A: agrega validación de email
git checkout -b feature/email-validation
# edita src/validators.py → agrega validate_email()
git add . && git commit -m "feat: add email validation"

# Branch B: agrega validación de phone
git checkout main
git checkout -b feature/phone-validation  
# edita src/validators.py → agrega validate_phone()
git add . && git commit -m "feat: add phone validation"

# Merge A en main
git checkout main
git merge feature/email-validation

# Merge B → conflicto
git merge feature/phone-validation
# CONFLICT in src/validators.py

Tú: Tengo un merge conflict en src/validators.py. Resuélvelo 
    manteniendo la funcionalidad de ambas branches (email y phone 
    validation).

Ejercicio 5: Avanzado — Git workflow completo

Simula un workflow completo: analizar el proyecto, planificar cambios, implementar en branch, commit incremental, tests, y PR.

Requisitos:

• Usar Explore → Plan → Code
• Branch de feature con al menos 3 commits
• Tests que pasen
• PR con descripción detallada
• Todo gestionado por Claude Code

Tú: Quiero agregar un sistema de caché para los endpoints más 
    usados. Primero analiza qué endpoints se beneficiarían más, 
    luego diseña la solución, y finalmente impleméntala en una 
    branch con commits incrementales. Abre un PR al final.

Resumen

Lo que aprendiste en esta cápsula:

• Claude Code ejecuta Git commands nativamente desde la terminal — no necesita APIs especiales
• Hay 3 workflow patterns: Feature branch (el más común), Commit-as-you-go (historial granular), y Review before commit (máximo control)
• Conventional commits (feat:, fix:, docs:) se configuran en CLAUDE.md para consistencia automática
• Claude Code puede crear PRs con gh, generando descripciones detalladas basadas en los diffs reales
• Claude Code puede hacer code review analizando diffs y explicando cambios
• Para merge conflicts, Claude Code entiende el contexto de ambos lados y propone resoluciones informadas
• Los pitfalls principales: push sin revisar, commits gigantes, mensajes genéricos, y force push accidental
• Configura reglas claras en CLAUDE.md y permisos en settings.json para un workflow seguro

Siguiente cápsula: 03 - SDK Python y TypeScript — cómo acceder a Claude Code programáticamente para automatización, CI/CD, y scripts personalizados.

Recursos adicionales

Documentación oficial

• Git Integration — Uso de Git con Claude Code
• CLI Reference — Comandos de CLI para Git
• Best Practices — Workflows Git recomendados
• Settings — Configurar permisos para operaciones Git

Git y GitHub

• Conventional Commits — Especificación de conventional commits
• GitHub CLI — Documentación de gh CLI
• GitHub Actions + Claude Code — CI/CD con Claude Code

Complementarios

• Hooks — Hooks para validar operaciones Git
• Headless Mode — Git automation con headless mode