Claude Code es mucho más que un chat con acceso a tu código. Cuando lo usas como una simple caja de preguntas y respuestas, dejas sobre la mesa la mayor parte de su potencial. La diferencia real está en adoptar un flujo de trabajo estructurado: planes explícitos antes de ejecutar, subagentes para explorar en paralelo, verificación adversarial antes de declarar la tarea lista y checkpoints claros entre fases. Este post cubre esa metodología: cómo pasar del chat suelto al flujo agéntico controlado.
Del chat al flujo de trabajo
El modo más básico de usar Claude Code es el chat: describes un problema, Claude propone una solución, tú la aplicas o la corriges. Funciona para tareas pequeñas y aisladas. Pero cuando la tarea involucra múltiples archivos, decisiones de arquitectura o una secuencia de pasos que se construyen unos sobre otros, el chat suelto se quiebra rápido.
El problema no es el modelo — es la ausencia de proceso. Sin un plan explícito, Claude puede optimizar el paso que tiene delante mientras ignora las restricciones del siguiente. Sin verificación, una solución que "parece correcta" en el diff puede romper el sistema de tipos o violar convenciones del proyecto. Sin checkpoints, una sesión larga acumula deuda silenciosa que solo aparece al final.
Un proceso estructurado resuelve esto en tres dimensiones:
- Reduce la ambigüedad: Especificaciones explícitas antes de escribir código eliminan la mayoría de las iteraciones por malentendidos.
- Distribuye el trabajo: Las tareas independientes pueden explorarse en paralelo con subagentes sin bloqueo mutuo.
- Garantiza calidad en la salida: La verificación adversarial (una perspectiva separada que busca activamente fallos) atrapa errores antes de que lleguen al historial de git.
En la práctica, este flujo tiene cinco elementos: el contrato del proyecto (CLAUDE.md), un plan antes de cada tarea compleja, subagentes para exploración paralela, verificación antes del commit y fases encadenadas con checkpoints explícitos.
CLAUDE.md: el contrato del proyecto
Cada vez que inicias una sesión de Claude Code, el archivo CLAUDE.md en la raíz del proyecto se carga automáticamente como contexto persistente. Es el único mecanismo que tienes para garantizar que Claude entiende tu proyecto antes de tocar una sola línea de código. Sin él, Claude infiere convenciones a partir del código que ve — lo que funciona pero produce inconsistencias cuando hay decisiones implícitas en el proyecto.
Piensa en CLAUDE.md como un contrato bilateral: tú documentes las reglas del proyecto, Claude las respeta en cada sesión. Los apartados más valiosos son las restricciones explícitas (qué no hacer) y los comandos de desarrollo, porque son los que más cuesta inferir desde el código:
# CLAUDE.md
## Comandos
```bash
npm run dev # Servidor de desarrollo (puerto 3000)
npm run build # Prisma generate + Next.js build
npm run lint # ESLint flat config
npx tsc --noEmit # Type check sin emitir
```
## Stack
Next.js 16 (App Router, Turbopack), React 19, TypeScript strict,
Prisma + PostgreSQL, Tailwind CSS v4, shadcn/ui, next-intl.
## Convenciones
- Componentes: PascalCase. Funciones/variables: camelCase. Rutas: kebab-case.
- "use client" solo cuando sea estrictamente necesario.
- Zod para toda validación de input en rutas API.
- cn() de utils/classNames.ts (clsx + tailwind-merge).
- Bilingüe a nivel de datos (campos Es/En), no con archivos de mensajes para el blog.
## No hacer
- No crear archivos de test (no hay framework configurado).
- No debilitar TypeScript strict mode.
- No añadir dependencias sin justificación.
- No modificar configuración de despliegue sin permiso explícito.
- No commitear archivos .env ni secretos.
La clave es la sección "No hacer". Claude Code respeta restricciones negativas con mucha más fidelidad que las instrucciones positivas genéricas. Si tienes una convención difícil de inferir (por ejemplo, que todas las rutas API deben usar un wrapper withAuth()), documéntala aquí con un ejemplo en lugar de recordársela en cada prompt.
El CLAUDE.md también puede tener secciones anidadas con instrucciones específicas por directorio. Un archivo app/admin/CLAUDE.md puede incluir contexto sobre el panel de administración que no es relevante para el resto del proyecto. Claude los carga en cascada: raíz primero, luego los específicos del directorio de trabajo.
Planificar antes de ejecutar
Para cualquier tarea que toque más de dos o tres archivos, el coste de escribir un plan explícito antes de ejecutar siempre se recupera. No porque Claude no pueda improvisar — puede — sino porque el plan crea un punto de acuerdo entre tú y el agente sobre qué se va a hacer, en qué orden y con qué restricciones.
El flujo es: spec → plan → ejecución.
La spec es una descripción en lenguaje natural de lo que necesitas, con el contexto relevante: qué archivos están involucrados, qué comportamiento debe cambiar, qué restricciones aplican. No tiene que ser larga — dos párrafos bien escritos son mejores que diez vagos.
El plan es lo que Claude genera a partir de la spec: una lista numerada de pasos con los archivos que tocará cada uno. Claude Code admite un modo de planificación donde le pides que investigue el codebase, proponga el plan completo y lo presente para tu aprobación antes de escribir una sola línea de código. Úsalo para tareas complejas.
En la práctica, el prompt de planificación tiene esta forma:
Antes de escribir código, genera un plan de implementación numerado para esta tarea:
**Tarea:** Añadir paginación server-side al listado de posts del admin.
**Contexto:**
- El endpoint está en app/api/admin/blog/route.ts
- El componente cliente es components/admin/BlogList.tsx
- La paginación debe ser por query params (?page=1&limit=20)
- Usar el patrón withAuth() existente para la autenticación
**Restricciones:**
- No modificar el esquema de Prisma
- Mantener la compatibilidad con los filtros de tag existentes
Presenta el plan. No escribas código hasta que yo lo apruebe.Este prompt produce un plan que puedes revisar, corregir y aprobar antes de que Claude empiece a editar archivos. Si el plan tiene un paso incorrecto, lo corriges en el plan — no en el diff de 200 líneas que viene después.
Subagentes en paralelo
Claude Code puede lanzar subagentes: instancias separadas del modelo que trabajan en paralelo sobre tareas independientes. Cada subagente tiene su propio contexto, sus propias herramientas y no bloquea al agente principal mientras trabaja.
El patrón más útil es el fan-out de exploración: cuando necesitas investigar varias partes del codebase sin que el resultado de una condicione la otra. Por ejemplo, antes de diseñar una nueva feature que afecta a múltiples subsistemas, puedes lanzar subagentes en paralelo para:
- Auditar el esquema de Prisma y los modelos relacionados.
- Mapear los endpoints API existentes que necesitarán cambios.
- Revisar los componentes de UI que consumirán los nuevos datos.
Los tres subagentes trabajan en paralelo y devuelven sus informes al agente principal, que los sintetiza en un plan de implementación coherente. Esto es significativamente más rápido que la exploración secuencial.
El otro patrón de subagentes es la ejecución paralela de tareas verdaderamente independientes. Si tienes que añadir la misma estructura de datos a tres secciones del admin (digamos, un campo de metadatos SEO a posts, autores y tags), puedes delegarlo a tres subagentes que trabajen en paralelo. La única precaución es que las tareas no toquen los mismos archivos — si lo hacen, los conflictos de merge manuales se comen el tiempo ahorrado.
Para que los subagentes funcionen bien, sus prompts deben ser completamente autosuficientes: incluir el contexto del proyecto, los archivos relevantes, las convenciones que aplican y el criterio de éxito. Un subagente bien briefeado es como un colega que entra a la sala con todo el contexto necesario para tomar decisiones, no alguien a quien tienes que explicar la arquitectura del proyecto desde cero.
Verificación adversarial
El error más costoso en flujos agénticos es dar por bueno el primer resultado que "parece correcto". Claude Code es muy bueno generando código que compila y que satisface la descripción literal de la tarea — pero eso no es lo mismo que código correcto, seguro y coherente con el sistema existente.
La verificación adversarial es el antídoto: antes de declarar cualquier tarea como terminada, someter el resultado a un proceso de revisión que busca activamente fallos, no que confirma el éxito.
El flujo de verificación mínimo tiene tres pasos:
- Verificación técnica automatizada:
npm run lint && npx tsc --noEmit(o el equivalente en tu stack). Si esto falla, nada de lo que viene después importa. - Revisión de diff:
git diffpara ver exactamente qué cambió. Los cambios inesperados (archivos que no debían tocarse, comportamientos que se modificaron implícitamente) aparecen aquí. - Revisión adversarial por subagente: Lanzar un subagente con el diff y el contexto del cambio, con la instrucción explícita de buscar problemas — no de validar que el código es correcto.
El prompt de revisión adversarial tiene esta forma:
Eres un revisor de código senior con mentalidad adversarial. Tu trabajo es encontrar
problemas en este diff — no confirmarlo como correcto.
**Contexto del cambio:** Se añadió paginación server-side al endpoint de posts del admin.
**Diff:** [contenido del git diff]
Busca específicamente:
1. Bugs de lógica (off-by-one, condiciones de borde no manejadas)
2. Problemas de seguridad (inputs no validados, auth bypassable)
3. Regresiones (comportamiento existente que puede haberse roto)
4. Inconsistencias con las convenciones del proyecto
5. Casos de uso del frontend que no funcionarán con la nueva API
Devuelve solo los problemas reales. Si no hay ninguno significativo, dilo.Un subagente revisando con este prompt frecuentemente encuentra cosas que el agente implementador pasó por alto: un campo que ahora es optional cuando el frontend lo trata como required, un caso de paginación en la página 0 que lanza un error, una query de Prisma que ignora el índice y se vuelve lenta con volumen.
La verificación adversarial no es desconfianza en el modelo — es reconocer que cualquier implementador (humano o agente) tiene puntos ciegos en su propio trabajo.
Encadenar fases sin perder el control
Las tareas complejas raramente son un solo paso. Tienen fases: exploración, diseño, implementación, verificación, refinamiento. El riesgo de un flujo agéntico sin estructura es que las fases se colapsen — que la implementación empiece antes de que el diseño esté consolidado, o que la verificación se salte porque "ya se ve bien".
La solución es encadenar las fases con checkpoints explícitos: puntos en los que tú revisas el estado antes de autorizar el siguiente paso. Esto no ralentiza el trabajo — ralentiza los errores, que es exactamente lo que buscas.
Un patrón de encadenamiento robusto para una feature significativa:
- Fase 1 — Exploración: Subagentes en paralelo auditan las partes del sistema afectadas. Checkpoint: revisas los informes y validas que el scope es correcto.
- Fase 2 — Plan: El agente principal sintetiza los informes y genera un plan de implementación. Checkpoint: apruebas el plan o lo corriges antes de que empiece a editar archivos.
- Fase 3 — Implementación: Ejecución por bloques (no de una vez). Después de cada bloque,
git diffrápido para confirmar que el rumbo es correcto. Checkpoint menor tras cada bloque. - Fase 4 — Verificación: Lint + type check + revisión adversarial del diff completo. Checkpoint: los problemas encontrados se priorizan y se decide cuáles bloquean el commit.
- Fase 5 — Commit: Solo cuando la verificación da luz verde. Mensaje de commit que describe el por qué, no el qué.
La clave de este encadenamiento es que cada checkpoint es una decisión tuya, no una automatización. Claude propone; tú dispones. Esto mantiene el control humano en los momentos que importan sin sacrificar la velocidad de la ejecución agéntica.
Para proyectos con lefthook o pre-commit hooks configurados, la verificación técnica de la Fase 4 puede automatizarse parcialmente: el hook ejecuta lint y type check antes de cada commit y falla si hay errores. Esto añade una red de seguridad que captura los casos donde la verificación manual se saltó.
La guía completa
Este post cubre la metodología base para trabajar con Claude Code más allá del chat. La guía en PDF expande cada elemento con plantillas listas para usar y flujos específicos por tipo de tarea:
- Plantillas de CLAUDE.md por stack: Next.js + Prisma, monorepo Turborepo, API Node.js, biblioteca de componentes — con las secciones y restricciones más comunes ya rellenadas.
- Hooks prácticos: Prettier post-edit, type check post-write, auto-stage de archivos relacionados — configuración completa de settings.json con ejemplos comentados.
- Skills propios: Cómo escribir skills de Claude Code personalizados para tu proyecto (revisión de código, generación de componentes, migración de esquema) y cómo invocarlos desde el editor.
- Flujos por tipo de tarea: Feature nueva, bugfix, refactoring, migración de base de datos, actualización de dependencias — cada uno con su secuencia de fases y checkpoints adaptada.
- Checklist de revisión: Lista de verificación adversarial lista para usar, con los 15 puntos que más frecuentemente revelan problemas en código generado por agentes.
