Guía práctica de pair programming con Claude Code: acelera con IA sin perder control

Hacer pair programming con Claude Code no significa entregar todo el teclado a la IA. El patrón que funciona en proyectos reales es más disciplinado: la persona define objetivo, límites y criterios de aceptación; Claude Code explora el repositorio, propone un plan, edita en pasos pequeños, ejecuta verificaciones y ayuda a preparar la revisión.

La documentación oficial de Claude Code overview lo describe como una herramienta de codificación agéntica capaz de leer el código, editar archivos, ejecutar comandos e integrarse con herramientas de desarrollo. Esa potencia es útil, pero también amplifica los prompts vagos. Si pides “arréglalo bien”, puede avanzar rápido en una dirección equivocada.

Esta guía es la continuación práctica de la guía de introducción a Claude Code. Resume un flujo que sirve para bugs pequeños, pruebas nuevas, refactors limitados y preparación de pull requests.

Define primero los roles

Antes de pedir una implementación, decide qué decisiones quedan en manos humanas. Claude puede leer muchos archivos y escribir código rápido, pero no debe redefinir silenciosamente la intención del producto, los límites de seguridad ni los criterios para hacer merge.

Área	Responsabilidad humana	Responsabilidad de Claude Code
Objetivo	Decidir qué cambia y qué no cambia	Encontrar archivos y rutas de implementación
Investigación	Marcar el alcance de lectura	Leer código, tests, diffs y logs
Implementación	Aprobar tamaño y riesgo del diff	Hacer cambios pequeños y enfocados
Verificación	Definir la señal de éxito	Ejecutar tests, lint, build o capturas
Revisión	Decidir si se puede mergear	Listar riesgos, tests faltantes y alternativas

Con esta división, Claude Code se convierte en un compañero de trabajo, no en un reemplazo sin supervisión. Para principiantes, también es una forma más segura de aprender: empieza con un bug, un archivo de tests o un componente antes de delegar una funcionalidad completa.

Prepara el repositorio en los primeros 10 minutos

La preparación cambia más el resultado que un prompt elegante. Las best practices de Claude Code recomiendan dar una forma verificable de comprobar el trabajo y separar exploración, planificación, implementación y validación. En mi rutina uso tres pasos.

Primero, trabajar en una rama o worktree, no directamente en main. Segundo, mantener un CLAUDE.md corto. La documentación de memoria explica que CLAUDE.md se carga al inicio de cada sesión como instrucciones persistentes. Tercero, indicar los comandos que demuestran que el cambio funciona.

# CLAUDE.md

## Project rules
- Before editing, summarize the files you plan to inspect.
- Prefer small diffs and explain risky changes before applying them.
- After code edits, run `npm run lint` and the narrowest relevant test.
- Do not read `.env*` files or change deployment settings without approval.

## Common commands
- `npm run lint`
- `npm run test`
- `npm run build`

No conviertas CLAUDE.md en una enciclopedia del proyecto. Si una instrucción es un procedimiento largo y repetible, puede vivir mejor como Skill, porque se carga solo cuando hace falta.

Usa el ciclo explorar, planificar, implementar y verificar

El error común es pedir “implementa esto” antes de que Claude haya entendido el código. Un ciclo más seguro se ve así:

flowchart LR
  A[Indicar objetivo] --> B[Explorar archivos relevantes]
  B --> C[Revisar plan]
  C --> D[Editar en pasos pequeños]
  D --> E[Ejecutar checks y ver diff]
  E --> F{Pasa?}
  F -- No --> C
  F -- Sí --> G[Resumir para PR]

El primer prompt no tiene que ser largo, pero sí concreto.

Objetivo: corregir el error 500 en la página de perfil después del login.
Alcance: empezar por `src/auth` y `src/pages/profile`.
No hacer: cambiar la estrategia de autenticación, modificar el schema de DB ni leer `.env`.
Proceso: lee los archivos relevantes, lista 3 causas probables y muestra un plan antes de editar.
Verificación: ejecuta los tests de auth existentes y `npm run lint`.

Cuando Claude proponga un plan, ajústalo antes de autorizar cambios. Puedes pedir el diff más pequeño o una prueba que falle primero.

El plan es razonable, pero escribe solo la prueba de reproducción primero.
Confirma que falla antes de tocar código productivo.
Después propón cambios de producción archivo por archivo.

Esto encaja muy bien con TDD, o desarrollo guiado por pruebas. TDD significa escribir una prueba fallida antes de la implementación. La ventaja no es ideológica: hace que el problema sea visible y que el cambio sea revisable.

Ejemplo pequeño que puedes ejecutar

Practica primero con una función pequeña, no con código crítico. Guarda este archivo como pair-check.test.ts y ejecútalo con Vitest.

import { describe, expect, it } from "vitest";

type ClaudeMode = "direct" | "plan-first" | "human-review";

export function decideClaudeMode(input: {
  changedFiles: number;
  touchesSecrets: boolean;
  hasReliableTests: boolean;
}): ClaudeMode {
  if (input.touchesSecrets) return "human-review";
  if (input.changedFiles > 3) return "plan-first";
  if (!input.hasReliableTests) return "plan-first";
  return "direct";
}

describe("decideClaudeMode", () => {
  it("allows direct work for small, well-tested changes", () => {
    expect(
      decideClaudeMode({
        changedFiles: 1,
        touchesSecrets: false,
        hasReliableTests: true,
      }),
    ).toBe("direct");
  });

  it("requires a plan for broad changes", () => {
    expect(
      decideClaudeMode({
        changedFiles: 5,
        touchesSecrets: false,
        hasReliableTests: true,
      }),
    ).toBe("plan-first");
  });

  it("requires human review for secret-related work", () => {
    expect(
      decideClaudeMode({
        changedFiles: 1,
        touchesSecrets: true,
        hasReliableTests: true,
      }),
    ).toBe("human-review");
  });
});

npm install -D vitest typescript
npx vitest run pair-check.test.ts

Ahora pide a Claude Code que añada una regla: “si toca billing, requiere human-review”. Pídele que agregue primero el test, confirme el fallo, implemente la regla y vuelva a ejecutar Vitest. Es un ejemplo pequeño, pero entrena la misma disciplina que necesitas en handlers de API, componentes React o scripts de migración.

Cuatro casos de uso que funcionan

El primer caso es añadir una condición pequeña a una funcionalidad existente, por ejemplo “ocultar la exportación CSV para cuentas gratuitas”. Obliga a revisar UI, permisos y tests sin rediseñar todo el producto.

El segundo caso es investigar bugs. Pega el error, los pasos de reproducción y el resultado esperado. La página oficial de Common workflows recomienda dar comandos de reproducción y stack traces para que Claude busque la causa raíz.

El tercer caso es ampliar tests. Haz que Claude lea el estilo de tests existente y luego pida casos de éxito, usuario no autorizado, entrada inválida y datos vacíos. Para hacerlo de forma sistemática, combínalo con la guía de testing strategies.

El cuarto caso es la revisión previa al PR. Pide a Claude que lea git diff y priorice seguridad, compatibilidad, tests faltantes y nombres confusos. La documentación de GitHub sobre pull request reviews explica cómo los comentarios, aprobaciones y solicitudes de cambios protegen la calidad. Claude Code debe preparar la revisión humana, no reemplazarla.

Errores comunes y cómo evitarlos

Error	Qué ocurre	Hábito más seguro
“Mejóralo”	Entran refactors no pedidos	Especificar alcance, no objetivos y aceptación
Diff demasiado grande	La revisión se vuelve lenta	Una tarea, un diff, un plan
Sin verificación	El cambio solo parece terminado	Exigir tests, lint, build o captura
CLAUDE.md enorme	Las reglas importantes se pierden	Mover procedimientos a Skills
Permisos demasiado amplios	Secretos o producción quedan al alcance	Usar permisos y hooks

El riesgo menos visible es la fatiga de aprobación. Si todo pide confirmación, la gente aprueba sin leer. Si casi todo está permitido, un prompt malo puede llegar demasiado lejos. La regla práctica es dar alta confianza al trabajo reversible y mucha fricción al trabajo irreversible. Para patrones concretos, revisa la guía de approval and sandbox.

Convierte la sesión en un PR revisable

En equipo, no dejes que el valor quede encerrado en el chat. Termina pidiendo un resumen de pull request.

Resume este diff para una pull request.
Incluye:
- Por qué se hizo el cambio
- Archivos principales modificados
- Comandos de verificación y resultados
- Riesgos que el revisor debe mirar
- Áreas que se dejaron fuera a propósito

Claude puede redactar el borrador, pero una persona debe ajustar el texto final. En seguridad, pagos, privacidad y borrado de datos, la confianza del modelo no es evidencia. La evidencia es el diff, la salida de tests, los logs y la conversación de revisión.

Resultado al probar este flujo

Cuando Masa usó este ciclo en una corrección pequeña de Next.js, la revisión fue más rápida que con un prompt simple de “impleméntalo”. No fue porque Claude escribiera código perfecto, sino porque el primer prompt limitó los archivos, nombró lo prohibido y exigió lint más tests. Claude Code tocó menos archivos irrelevantes y dejó la evidencia de verificación en la conversación. En cambios visuales con pocos tests, la revisión humana siguió siendo necesaria. La lección es directa: pair programming con Claude Code no consiste en delegar responsabilidad, sino en diseñar qué responsabilidad se delega.

Para tu próxima sesión, elige una tarea pequeña y pásala por explorar, planificar, implementar y verificar. Si tu equipo necesita prompts compartidos y criterios de revisión, consulta ClaudeCodeLab training.