Flujo de trabajo Git con Claude Code: ramas limpias, commits pequeños, CI y traspaso de equipo

Cuando Claude Code escribe más rápido, Git debe volverse más estricto. El problema no suele ser que la IA no pueda generar código, sino que mezcle archivos ajenos, cree commits demasiado grandes, resuelva conflictos sin entender la intención o haga push antes de ejecutar pruebas locales.

Esta guía propone un flujo de trabajo Git para trabajar con Claude Code en proyectos individuales y en equipos: rama limpia, commits pequeños, punto de revisión, higiene del worktree, manejo de conflictos, rollback seguro, CI antes del push y traspaso diario. También explica staging, commit y rebase con palabras simples.

Lecturas relacionadas: resolver conflictos Git con Claude Code, GitHub Actions avanzado y review workflow checklist. Referencias oficiales: Claude Code hooks, Claude Code headless mode, Git user manual, Git rebase, GitHub Actions workflow syntax y pre-commit.

Conceptos Git sin jerga

El working tree es la carpeta donde estás editando archivos. Claude Code también escribe ahí. El área de staging es la “caja del próximo commit”: git add no guarda todo para siempre, solo elige qué cambios entrarán en el siguiente commit.

Un commit es una instantánea con nombre de los cambios en staging. Un buen commit es pequeño y tiene una razón clara. Rebase significa tomar tus commits y ponerlos encima del main actualizado. El historial queda más lineal, pero reescribir una rama que otros ya usan puede romperles el trabajo.

Claude Code no debe ser solo un generador de código. En un flujo sano también lee el diff, propone qué llevar al staging, redacta el mensaje de commit, explica conflictos, ejecuta comandos de verificación y deja una nota de traspaso.

flowchart LR
  A["Definir objetivo"] --> B["Actualizar main y crear rama"]
  B --> C["Implementar un cambio pequeno"]
  C --> D["Leer diff y elegir staging"]
  D --> E["Review gate y CI local"]
  E --> F["Commit pequeno"]
  F --> G["Rebase o PR"]
  G --> H["Handoff y rollback"]

Rama limpia antes de pedir cambios

Antes de editar, deja claro el punto de partida. “Limpio” no significa siempre cero cambios; significa que no hay cambios ajenos a esta tarea.

git status --short
git fetch origin
git switch main
git pull --ff-only origin main
git switch -c feature/checkout-coupon-validation
git status --short

En PowerShell, una rama con fecha ayuda cuando ejecutas varias sesiones.

$topic = "checkout-coupon-validation"
$date = Get-Date -Format "yyyyMMdd"
git fetch origin
git switch main
git pull --ff-only origin main
git switch -c "feature/$date-$topic"
git status --short

El primer prompt debe fijar alcance, no solo pedir implementación.

Goal: add coupon expiry validation to checkout.
Scope: edit only src/checkout, src/coupons, and matching tests.
Do not stage, commit, push, or edit unrelated files.
Before editing, read package.json and existing checkout tests.
After editing, show git diff --stat and the exact test commands you ran.

Masa encontró este fallo varias veces en ClaudeCodeLab: una tarea de artículo terminaba mezclando borradores de producto, scripts locales o informes temporales. El código podía compilar, pero el diff ya no era explicable. La solución práctica fue escribir también lo que queda fuera del alcance.

Staging deliberado y commits pequeños

git add -A es cómodo, pero demasiado amplio para trabajo asistido por IA. Puede incluir archivos temporales, configuración local o cambios de otra tarea.

git diff --stat
git diff
git add src/checkout/validateCoupon.ts
git add tests/checkout/validateCoupon.test.ts
git diff --staged --stat
git diff --staged

Usa mensajes de commit fáciles de buscar.

git commit -m "feat(checkout): validate coupon expiry before payment"

Si el cambio afecta a usuarios, contenido o ingresos, agrega un cuerpo.

git commit -m "fix(content): keep Claude Code Git workflow CTA localized" -m "Updates the localized article body, internal links, and review checklist so translated pages follow the same Git workflow."

Puedes pedirle a Claude Code solo el mensaje.

Read only the staged diff.
Propose one Conventional Commits message.
Do not run git commit.
Mention the user impact in the body if the change affects readers or customers.

Reglas en CLAUDE.md

CLAUDE.md es el manual operativo para Claude Code dentro del repositorio. Si repites la misma advertencia en cada sesión, ponla ahí.

# Claude Code Git rules

- Start every coding task with `git status --short` and report unrelated dirty files.
- Do not run `git add -A`, `git commit`, `git push`, `git reset --hard`, or `git clean -fd` unless the user explicitly asks.
- Keep commits small: one behavior change, one test update, or one content slug at a time.
- Before proposing a commit, show `git diff --stat` and `git diff --staged --stat`.
- If a conflict appears, explain both sides before editing the conflicted file.
- Run the closest local checks before push: lint, typecheck, test, build, or article metadata checks.
- Leave a handoff note with changed files, commands run, failing checks, and rollback option.

En equipo, complementa esas reglas con un hook que bloquee comandos peligrosos. Los hooks de Claude Code son comandos definidos por el usuario que se ejecutan en eventos del ciclo de vida.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(git *)",
            "command": "node .claude/hooks/block-dangerous-git.mjs"
          }
        ]
      }
    ]
  }
}

// .claude/hooks/block-dangerous-git.mjs
import process from "node:process";

let raw = "";
for await (const chunk of process.stdin) raw += chunk;

const input = JSON.parse(raw || "{}");
const command = input.tool_input?.command ?? "";

const blocked = [
  /git\s+reset\s+--hard\b/,
  /git\s+clean\s+-[^\s]*f/,
  /git\s+push\s+--force(?!-with-lease)/,
  /git\s+checkout\s+--\s+\./,
  /git\s+restore\s+\.\b/
];

if (blocked.some((pattern) => pattern.test(command))) {
  process.stderr.write(`Blocked risky Git command: ${command}\n`);
  process.exit(2);
}

Un hook no sustituye la revisión humana. Sirve para reducir accidentes, no para eliminar la responsabilidad del equipo.

CI local antes del push

No esperes a que el CI remoto falle. Crea un preflight que ejecute solo los scripts disponibles.

// scripts/claude-git-preflight.mjs
import { execSync } from "node:child_process";
import { existsSync, readFileSync } from "node:fs";

const run = (command) => {
  console.log(`\n$ ${command}`);
  execSync(command, { stdio: "inherit", shell: true });
};

run("git diff --check");
run("git diff --cached --check");
run("git status --short");

const pkg = existsSync("package.json")
  ? JSON.parse(readFileSync("package.json", "utf8"))
  : { scripts: {} };

for (const script of ["lint", "typecheck", "test", "build"]) {
  if (pkg.scripts?.[script]) run(`npm run ${script}`);
}

node scripts/claude-git-preflight.mjs

Prompt recomendado:

After implementation, run the local preflight.
If a command fails, stop and explain the first failing command, likely cause, and smallest next fix.
Do not push until the preflight is green.

pre-commit y GitHub Actions

pre-commit ejecuta verificaciones antes de crear el commit.

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: git-diff-check
        name: git diff whitespace check
        entry: git diff --check
        language: system
        pass_filenames: false
      - id: npm-test
        name: npm test when available
        entry: node scripts/claude-git-preflight.mjs
        language: system
        pass_filenames: false

python -m pip install pre-commit
pre-commit install
pre-commit run --all-files

En pull requests, repite lo esencial con GitHub Actions.

# .github/workflows/claude-code-pr-gate.yml
name: Claude Code PR Gate

on:
  pull_request:
    branches: [main]

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm

      - run: npm ci
      - run: git diff --check origin/main...HEAD
      - run: npm run lint --if-present
      - run: npm run typecheck --if-present
      - run: npm test --if-present
      - run: npm run build --if-present

Conflictos, rebase y rollback

Un conflicto significa que Git no puede elegir entre dos cambios. Pide primero una explicacion de ambos lados.

git fetch origin
git rebase origin/main
git status --short
git diff --name-only --diff-filter=U

We are in a rebase conflict.
For each conflicted file, explain what our branch changed and what origin/main changed.
Resolve only after explaining the business intent.
After editing, run the narrowest relevant test.
Do not continue the rebase until I approve the resolved diff.

git add src/checkout/validateCoupon.ts
npm test -- --runInBand validateCoupon
git rebase --continue

Si la resolución va mal:

git rebase --abort

Para cambios compartidos, prefiere git revert.

git log --oneline -5
git revert --no-edit HEAD
git status --short

Para cambios sin commit, limita la ruta.

git restore --staged src/checkout/validateCoupon.ts
git restore src/checkout/validateCoupon.ts

Casos de uso y fallos comunes

Caso 1: funcionalidad individual. Crea feature/yyyyMMdd-topic, limita archivos y tests, haz un commit por comportamiento y ejecuta preflight antes de push.

Caso 2: PR de equipo. La sesión de implementación no crea commits. La sesión de revisión lee solo el staged diff. Una persona confirma título del PR, CI, riesgo y rollback.

Caso 3: contenido y producto. En ClaudeCodeLab, artículos, enlaces de Gumroad, CTA de formación y enlaces internos afectan los ingresos. Trabaja por slug y locale, y verifica description, hero, CTA, enlaces y texto localizado.

Caso 4: refactor largo. Primero tests, luego cambio interno y al final eliminación. No pidas una migración total en un solo commit.

Fallo	Causa	Prevención
git add -A incluye archivos ajenos	La IA tocó más de lo necesario	Añadir al staging por ruta
Commit gigante	Mezcla implementación, tests y configuración	Un objetivo por commit
Conflicto mal resuelto	No se entendió la intención	Explicar ours/theirs primero
Push peligroso tras rebase	Historia local y remota divergen	--force-with-lease solo con regla de equipo
PR rojo	No hubo checks locales	Ejecutar preflight
Rollback destructivo	Uso de reset --hard	Revert para commits compartidos

Traspaso diario

El traspaso debe ser corto, verificable y fácil de retomar.

## Handoff: 2026-06-02

Branch: feature/20260602-checkout-coupon-validation
Goal: validate coupon expiry before payment authorization

Changed:
- src/checkout/validateCoupon.ts
- tests/checkout/validateCoupon.test.ts

Checks:
- npm run lint: passed
- npm test -- --runInBand validateCoupon: passed
- npm run build: not run, no UI/build config touched

Risk:
- Coupon timezone boundary still needs one integration test.

Rollback:
- Revert commit `abc1234` if production checkout rejects valid coupons.

Siguiente paso

Si trabajas solo, empieza por la guía rápida gratuita de Claude Code. Si quieres prompts reutilizables, reglas CLAUDE.md y plantillas de review, revisa los productos de ClaudeCodeLab. Para equipos que necesitan adaptar ramas, CI, permisos, rollback y traspaso a un repositorio real, la ruta natural es formación y consultoría Claude Code.

Resultado al aplicarlo

Al usar este flujo en publicaciones de ClaudeCodeLab, la revisión pasó de “leer todo otra vez” a revisar slug, locale, metadatos, CTA y alcance del diff. git diff --staged --stat y el traspaso fueron lo más útil: dejan claro qué se verificó y qué queda pendiente.