# Trabajo con Git a través de Claude Code: guía para principiantes

> Guía práctica completa sobre la integración de Git y Claude Code: staging inteligente, mensajes de commit automáticos, resolución de conflictos, GitHub CLI y estándares de seguridad.

## 1. Qué es la integración de Git en Claude Code

Claude Code cuenta con una profunda integración nativa con el sistema de control de versiones Git. A diferencia de las interfaces de chat de IA tradicionales donde el desarrollador debe copiar y pegar manualmente la salida de `git diff` o `git status`, el agente de terminal Claude Code interactúa directamente con tu repositorio local mediante sus herramientas de ejecución de comandos.

El agente analiza la estructura de los cambios, revisa el historial del proyecto, respeta las convenciones de nomenclatura establecidas y asume operaciones rutinarias: creación de ramas, preparación selectiva de archivos (staging), rebases seguros y generación de descripciones completas para Pull Requests.

```mermaid
flowchart TD
    A["Petición del desarrollador:<br><i>'Commit current changes'</i>"] --> B["Claude Code CLI"]
    B --> C["git status<br><i>(Comprobación de archivos modificados)</i>"]
    B --> D["git diff<br><i>(Análisis de lógica y cambios)</i>"]
    B --> E["git log -n 5<br><i>(Detección de convenciones de commit)</i>"]
    C & D & E --> F["Staging inteligente<br><i>(git add &lt;file&gt; selectivo)</i>"]
    F --> G["Generación de mensaje de commit<br><i>(feat/fix contextual)</i>"]
    G --> H{"Confirmación del usuario"}
    H -->|Aprobado| I["Ejecución de git commit"]
    H -->|Ajuste| J["Actualización del mensaje"]
```

### Ventajas de utilizar Git a través de Claude Code

| Criterio | Git manual tradicional | Trabajo con Claude Code |
| :--- | :--- | :--- |
| **Análisis de cambios** | Revisión manual de cada archivo con `git diff` | Comprensión automatizada de la semántica y relaciones entre archivos |
| **Mensajes de commit** | A menudo frases poco informativas como *"update"*, *"fix"* | Mensajes estructurados según el estándar Conventional Commits |
| **Staging** | Riesgo de añadir secretos o archivos basura con `git add .` | Staging selectivo y granular únicamente del código relevante |
| **Conflictos de fusión** | Complejo análisis manual de marcadores `<<<<<<<` | Síntesis inteligente preservando la lógica de ambas ramas |
| **Creación de PR** | Redacción manual del resumen, cambios y pruebas | Creación automatizada en Markdown conectando con `gh CLI` |

> [!NOTE]
> Claude Code opera en el contexto aislado de tu repositorio local y siempre solicita confirmación antes de ejecutar comandos que modifiquen archivos o reescriban el historial.

---

## 2. Creación de commits: preparación inteligente y descripciones

El flujo de trabajo más frecuente en el día a día de un desarrollador es consolidar cambios mediante commits. En lugar de ejecutar tres o cuatro comandos secuenciales en la terminal, puedes indicarle a Claude Code en lenguaje natural:

```bash
Commit these changes with a descriptive message
```

### Qué sucede bajo el capó

Cuando Claude recibe la orden de hacer un commit, ejecuta un diagnóstico paso a paso:

1. **Inspección del árbol de trabajo:** ejecuta `git status` para listar archivos modificados, eliminados y nuevos sin seguimiento.
2. **Análisis semántico del código:** ejecuta `git diff` para revisar las líneas alteradas, separando la lógica de negocio de cambios de formato.
3. **Aprendizaje de convenciones del repositorio:** consulta `git log -n 5` para detectar el estilo del equipo (por ejemplo, `feat(auth): ...` o frases concisas).
4. **Staging selectivo:** añade al índice de Git únicamente los archivos correspondientes a la tarea en curso, ignorando configuraciones o secretos locales.
5. **Formulación del mensaje:** redacta un título conciso y una descripción detallada que explica el motivo y el impacto de los cambios.

:::tabs
@tab Conventional Commits
```text
feat(cart): implement instant item quantity counter in navbar

- Add reactive useCartCount hook to synchronize state across tabs
- Optimize database query to aggregate item count in a single request
- Add unit tests for edge cases when cart contains empty items
```
@tab Descripción concisa (Simple)
```text
fix: resolve race condition in token refresh flow

Prevent multiple parallel requests from triggering duplicate OAuth
refresh cycles when access token expires.
```
@tab Vinculado a tareas (Jira/Linear)
```text
PROJ-412: refactor notification worker queue

Migrate Redis connection pool to cluster mode to handle burst traffic.
Closes #184.
```
:::

> [!TIP]
> Si deseas registrar únicamente un archivo específico o un subconjunto de cambios, indícalo directamente en el prompt: `Commit only the changes in src/components/Header.tsx with an appropriate message`.

---

## 3. Gestión de ramas y cambio de contexto

Aislar el desarrollo en ramas independientes es una regla esencial del trabajo colaborativo. Claude Code permite crear una rama e iniciar inmediatamente la implementación sin necesidad de alternar constantemente entre la terminal y tu editor de código.

### Creación y cambio de ramas

```bash
# Crear una nueva rama y cambiarse a ella
Create a new branch named feature/instant-search and switch to it
```

Claude ejecutará automáticamente el comando `git checkout -b feature/instant-search` (o `git switch -c`).

### Combinar la creación de rama con la implementación

La mayor productividad se consigue al unir la intención de crear una rama con la formulación del objetivo técnico:

```bash
Create a branch called fix/email-validation, then fix the regex check in the signup form and write a test for it
```

### Prefijos estándar para ramas

- `feature/` o `feat/` — nueva funcionalidad o componente de interfaz (ej. `feature/stripe-payments`).
- `fix/` o `bugfix/` — corrección de errores (ej. `fix/oauth-redirect`).
- `refactor/` — reestructuración de código sin alterar el comportamiento externo (ej. `refactor/user-service`).
- `chore/` — actualización de dependencias, scripts de CI/CD o documentación (ej. `chore/upgrade-nextjs-15`).

---

## 4. Resolución de conflictos de fusión (Merge Conflicts)

Los conflictos de fusión ocurren cuando el mismo bloque de código ha sido modificado en dos ramas distintas. Resolver estas situaciones manualmente suele provocar la pérdida accidental de código funcional o errores sintácticos.

Claude Code analiza ambos extremos del conflicto, interpreta la intención de cada autor y consolida los cambios sin sacrificar funcionalidad.

### Flujo de trabajo paso a paso para resolver conflictos

1. **Inicia el proceso de fusión o rebase en la terminal:**
   ```bash
   git merge origin/main
   # o
   git rebase main
   ```
2. **Si aparecen marcadores de conflicto, invoca a Claude Code:**
   ```bash
   I have merge conflicts after rebasing on main. Please inspect each conflicting file, analyze both sides of the changes, and resolve them cleanly.
   ```
3. **Inspección de marcadores:** Claude examina las marcas `<<<<<<< HEAD`, `=======` y `>>>>>>>`, analizando cómo encajan los cambios en el contexto global.
4. **Verificación de compilación:** tras eliminar los marcadores, el agente ejecuta el comprobador de tipos (`tsc --noEmit`) o las pruebas (`npm test`) para garantizar la solidez de la solución.
5. **Staging de archivos resueltos:** el agente ejecuta `git add <archivos-resueltos>` y prepara el paso final para concluir el merge.

```typescript
// Ejemplo de conflicto en un archivo de configuración:
<<<<<<< HEAD
export const API_TIMEOUT = 10000; // Timeout incrementado para conexiones lentas en la rama feature
=======
export const API_TIMEOUT = 8000; // Estándar actualizado del backend desde main
export const RETRY_ATTEMPTS = 3;  // Nuevo parámetro agregado por un compañero en main
>>>>>>> origin/main
```

Claude propondrá una solución equilibrada: mantener tu timeout ampliado de `10000` e incorporar al mismo tiempo la nueva constante `RETRY_ATTEMPTS = 3` procedente de `main`.

---

## 5. Cherry-pick, Rebase y migración de commits

En ocasiones es necesario trasladar un parche aislado o una corrección crítica hacia una rama de producción sin arrastrar todo el historial de desarrollo en curso. Para estos casos se utilizan `cherry-pick` y `rebase`.

### Traslado de un commit específico (Cherry-pick)

```bash
Cherry-pick commit a7b9c1d from branch feature/cart onto release/v1.2.0
```

Si surgen pequeñas discrepancias de rutas o firmas de métodos, Claude adaptará los imports y resolverá las dependencias en el acto.

### Backporting inteligente

En proyectos con soporte para múltiples versiones estables, el backporting es una tarea habitual. Puedes delegar en Claude todo el ciclo:

```bash
Backport the security fix from commit 3f8a92 to the legacy-support branch. Verify that existing legacy tests still pass and commit the result.
```

### Rebase vs. Merge: cuándo elegir cada uno

| Operación | Cuándo utilizar | Beneficios clave | Acción de Claude |
| :--- | :--- | :--- | :--- |
| **`git rebase main`** | Al actualizar la rama de trabajo con los últimos cambios de `main` | Historial lineal y limpio sin commits de fusión innecesarios | Aplica los commits uno a uno, resolviendo conflictos triviales automáticamente |
| **`git merge main`** | Al incorporar una funcionalidad completa a la rama compartida | Preserva el orden cronológico exacto del desarrollo | Genera un commit de fusión único con un resumen detallado de los cambios |

---

## 6. Gestión de cambios temporales con Git Stash

Cuando necesitas cambiar urgentemente a otra rama para revisar una incidencia crítica pero tu trabajo actual no está listo para un commit, `git stash` es la herramienta idónea.

Claude Code puede coordinar secuencias complejas de comandos con el stash:

```bash
Stash my current changes with a label 'wip-checkout', switch to main, pull latest changes, and report back
```

### Recuperación del estado guardado

Una vez solventada la urgencia, recupera tus cambios pendientes:

```bash
Switch back to feature/checkout, pop the stash 'wip-checkout', and resolve any conflicts if the base changed
```

> [!TIP]
> Gracias al análisis semántico, Claude verificará si los archivos base cambiaron durante la pausa y aplicará el stash sin riesgo de sobrescrituras accidentales.

---

## 7. Creación de Pull Requests e integración con GitHub CLI (gh)

Si dispones de la herramienta oficial GitHub CLI (`gh`) en tu sistema, Claude Code se convierte en un asistente integral para la redacción y envío de Pull Requests.

### Creación automática de PR con Claude

En lugar de rellenar manualmente formularios en el navegador, ejecuta:

```bash
Push current branch to origin and create a pull request with gh CLI. Include summary, list of changes, and testing instructions.
```

### Ejemplo de Pull Request generado

Claude estructura una plantilla profesional en formato Markdown:

```markdown
## Summary
This PR implements user session invalidation on password reset to prevent
unauthorized access from stolen legacy tokens.

## Changes
- Add `revokeAllUserSessions` service in `src/services/auth.ts`
- Update password reset controller to call invalidation hook
- Add Redis blacklist mechanism for active JWT tokens
- Cover revocation flow with integration tests in `auth.test.ts`

## Testing Instructions
1. Login from two different browsers (simulate active sessions)
2. Trigger "Forgot Password" flow in Browser A
3. Verify that Browser B gets redirected to `/login` on next API call
4. Run test suite: `npm run test:auth`

Fixes #284
```

> [!IMPORTANT]
> Comprueba que tu sesión de GitHub CLI está activa con el comando `gh auth status` antes de solicitar la creación de Pull Requests.

---

## 8. Reglas de seguridad integradas y mecanismos de protección

Git es muy potente, pero el uso descuidado de ciertos modificadores puede provocar la pérdida irrevocable de código o alterar el historial compartido. Claude Code incorpora políticas estrictas de seguridad.

```mermaid
flowchart LR
    subgraph Acciones_peligrosas["Bloqueado sin confirmación explícita"]
        D1["git push --force a main"]
        D2["git add -A / git add ."]
        D3["git commit --amend en commits remotos"]
        D4["git commit --no-verify"]
    end
    subgraph Practicas_seguras["Estándar de Claude Code"]
        S1["Push normal o nuevo commit correctivo"]
        S2["Staging selectivo de archivos específicos"]
        S3["Creación de un commit posterior limpio"]
        S4["Corrección real de errores de linter/tests"]
    end
    D1 -.-> S1
    D2 -.-> S2
    D3 -.-> S3
    D4 -.-> S4
```

### Las cuatro reglas de oro de seguridad en Claude Code

1. **Prohibición de Force Push destructivo:** Claude nunca ejecuta `git push --force` o `-f` sobre ramas protegidas (`main`, `master`, `release`) sin tu confirmación directa y reiterada.
2. **Staging selectivo:** el agente evita órdenes ciegas como `git add .` o `git add -A`. Cada archivo se añade por su ruta exacta, previniendo la fuga involuntaria de variables de entorno (`.env`), claves secretas o copias locales de bases de datos.
3. **Preservación del historial:** el agente prioriza crear un commit correctivo nuevo antes que recurrir a `git commit --amend`, especialmente si los cambios ya han sido sincronizados con el servidor remoto.
4. **Respeto a los Pre-commit Hooks:** Claude no utiliza la bandera `--no-verify` para eludir comprobaciones de Husky, ESLint o Prettier. Si un hook detiene el commit, el agente localiza el error en el código, lo soluciona y vuelve a intentar el commit con normalidad.

> [!WARNING]
> Nunca solicites a un agente de IA que ejecute comandos no verificados como `git reset --hard HEAD~N` en ramas compartidas. Crea siempre una rama temporal de respaldo o utiliza `git stash` antes de reescribir el historial.

---

## 9. Taller práctico: ciclo completo desde la rama hasta el PR

Practiquemos un ciclo completo de trabajo en un proyecto real: desde la recepción del requerimiento hasta la apertura de un Pull Request verificado con Claude Code.

### Paso 1. Comprobación del estado y creación de la rama

Abre la terminal en tu repositorio, inicia `claude` e introduce:

```bash
Check git status, pull latest changes from main, and create a feature branch called feature/user-avatar
```

Claude comprobará que el directorio de trabajo esté limpio, descargará las actualizaciones recientes de `main` y cambiará a la nueva rama.

### Paso 2. Implementación de la tarea

Proporciona la especificación del componente:

```bash
Add an Avatar component in src/components/Avatar.tsx that renders a user image with fallback initials if the image URL is missing.
```

### Paso 3. Verificación y commit selectivo

Una vez creados los archivos, ordena la consolidación:

```bash
Review what was created, make sure tests pass, and commit only the avatar component files with a clear conventional commit message
```

Claude ejecutará las pruebas, añadirá al índice `src/components/Avatar.tsx` junto con sus tests y generará un commit impecable:

```text
feat(ui): add Avatar component with initials fallback

- Render user image with rounded profile styling
- Fallback to calculated two-letter initials on missing src or error
- Add unit test coverage for invalid image source handling
```

### Paso 4. Envío y apertura del Pull Request

Concluye el ciclo con una instrucción final:

```bash
Push this branch to GitHub and create a draft PR using gh CLI describing the changes
```

---

## 10. Autoevaluación rápida y lista de verificación final

Comprueba tu dominio de los conceptos abordados en esta guía con esta breve evaluación.

### Preguntas de repaso

> **1. ¿Por qué Claude Code añade archivos por su ruta exacta en lugar de ejecutar `git add .`?**
>
> > [!TIP]
> > **Respuesta:** Para evitar incluir accidentalmente en el repositorio credenciales locales (`.env`), archivos del sistema operativo (`.DS_Store`) o carpetas de compilación omitidas en el `.gitignore`.

> **2. ¿Cómo determina Claude Code el formato de los mensajes de commit?**
>
> > [!TIP]
> > **Respuesta:** El agente analiza de forma autónoma los últimos commits mediante `git log`, adoptando la convención ya existente en el proyecto (Conventional Commits, identificadores de Jira o descripciones breves).

> **3. ¿Qué ocurre si un Pre-commit Hook (Husky/ESLint) falla durante un commit ejecutado por Claude?**
>
> > [!TIP]
> > **Respuesta:** Claude no forzará el guardado con `--no-verify`. En su lugar, examinará el informe del linter o de las pruebas, corregirá el código problemático y repetirá el commit de forma segura.

### Lista de verificación para el uso diario de Git con Claude Code

- [ ] Utiliza la instrucción simple `Commit these changes` en lugar de la secuencia manual `status -> add -> commit`.
- [ ] Combina la creación de la rama con la especificación de la tarea en el mismo prompt para no fragmentar el contexto.
- [ ] Confía a Claude el análisis y la resolución inicial de conflictos tras operaciones de `rebase` o `merge`.
- [ ] Recurre a `git stash` a través de Claude para cambiar rápidamente a tareas imprevistas sin perder trabajo.
- [ ] Instala `gh CLI` para permitir que Claude redacte Pull Requests completos y estructurados en Markdown.
- [ ] Mantén activas las reglas de protección: revisa el diff final antes de enviar tus cambios a ramas remotas.