Migrar de espec a producción en un día con Claude Code

De spec a producción en un día: migración real con Claude Code

Tratar a Claude Code como un “programador más” es la receta para rehacer horas de trabajo. Tratarlo como un equipo paralelo que ejecuta specs precisas es la forma de pasar de spec a producción en un día: migración real con Claude Code. Aquí tienes el flujo probado, las reglas rígidas y los errores que realmente te harán perder el día.

Resumen rápido (lectores con prisa)

Claude Code acelera la ejecución técnica cuando recibe specs precisas y sesiones acotadas. Usa un CLAUDE.md versionado, descompone el sistema en módulos con contratos, lanza sesiones por módulo y valida cada handoff antes de integrar. El flujo minimiza errores y permite pasar de spec a producción en un día si se siguen las reglas.

Tiempo estimado de lectura: 6 min

De spec a producción en un día: el patrón que funciona

Referencias clave

• Documentación oficial Claude Code
• Claude (Anthropic)

La diferencia entre una migración rápida y una que se desboca está en la disciplina: especificar antes de ejecutar, fragmentar antes de paralelizar y validar antes de integrar. Claude Code acelera ejecución; no reemplaza la necesidad de criterio humano para tomar decisiones arquitectónicas.

A continuación, el flujo operativo que equipos reales usan para migrar en un día sin incendios.

Fase 0 — Precondición: el contrato de proyecto

Antes de cualquier línea de código, publica o actualiza un CLAUDE.md en la raíz del repo con:

• Stack, comandos y convenciones (ej.: pnpm, TypeScript strict, patrón de servicios).
• Patrones prohibidos y límites de seguridad.
• Comandos de CI y thresholds de tests.

Claude Code incorpora este archivo al contexto inicial; sin él, el agente inventa decisiones. Mantén el CLAUDE.md versiónada y sincronizado con cualquier cambio de stack.

Fase 1 — Spec de arquitectura (1–2 horas)

El líder técnico escribe la spec: estado actual, objetivo, invariantes y una descomposición en módulos con contratos públicos.

Resultado concreto:

• Lista de módulos atómicos y su orden (dependencias DAG).
• Para cada módulo: signature, DTOs, efectos secundarios permitidos, criterios de aceptación automáticos y manuales.

Ejemplo simple para migrar API REST a tRPC:

• Módulo A: AuthService — createSession(userCreds): SessionDto
• Módulo B: UserService — getUser(id): UserDto (depende de AuthService)
• Módulo C: Billing — charge(accountId, amount): ChargeResult (depende de UserService)

La spec es el contrato. Nada se implementa sin ella.

Fase 2 — Implementación paralela con sesiones acotadas (3–4 horas)

Lanza sesiones independientes de Claude Code por módulo. Cada sesión recibe:

1. CLAUDE.md.
2. Spec del módulo (requirements, design, tasks, acceptance).
3. Lista de tareas atomizadas (crear tipos, implementar funciones, tests unitarios).

Reglas de sesión:

• Mínimo contexto: solo archivos relevantes y la spec del módulo.
• Tasks atómicas y verificables: “añadir interfaz X” > “implementar función Y”.
• Tests deben ser parte de la entrega. Claude produce código + tests.

Ventaja: el agente no necesita retener todo el repo, evita “alucinaciones” arquitectónicas y produce artefactos integrables.

Fase 3 — Handoff e integración (1–2 horas)

Cada módulo terminado pasa por revisión humana contra la spec. Validaciones rápidas:

• ¿Las firmas coinciden con las prometidas?
• ¿Se respetaron patrones prohibidos del CLAUDE.md?
• ¿Los tests pasan y la cobertura cumple el mínimo definido?

Integración:

• Merge secuencial según DAG de dependencias.
• Ejecutar builds e integración continua en cada step.
• Resolver conflictos de API con parches mínimos, volver a ejecutar tests.

Si algo falla, el alcance de la corrección está acotado al módulo fallido. No es necesario rehelar toda la migración.

Fase 4 — Regresión y criterios de producción (2 horas)

Pruebas que deben pasar antes de deploy:

• Tests unitarios y de integración: cobertura igual o superior al sistema legado por módulo.
• Pruebas end-to-end en flujos críticos.
• Métricas de performance (p95) dentro de los límites definidos en la spec.
• Auditoría: sin dependencias nuevas no autorizadas, sin uso de patrones prohibidos.

Solo cuando todo esto pasa y la revisión humana valida, se programa el deploy.

Qué falla cuando fallas el proceso (anti-patrones)

– Enviar una spec ambigua. Resultado: implementaciones rápidas pero inconsistentes.

– Hacer una sesión única y global. Resultado: contexto saturado y decisiones implícitas.

– No versionar CLAUDE.md. Resultado: el agente aplica reglas obsoletas con más fe que un humano.

Checklist práctico para tu primer día de migración

• [ ] CLAUDE.md actualizado y en la raíz.
• [ ] Spec de arquitectura con módulos y contratos firmados.
• [ ] Tasks atomizadas por módulo y asignadas a sesiones de Claude Code.
• [ ] Validaciones automáticas y criterios de aceptación escritos en la spec.
• [ ] Revisión humana planificada para cada handoff.
• [ ] Pipeline de CI preparado para integración continua por módulo.

Cierre: por qué esto no es solo “más rápido”

La velocidad que trae Claude Code es real. Pero el verdadero valor viene de transformar la práctica: dividir el trabajo, especificar contratos y establecer handoffs claros. Si ejecutas el flujo como equipo (humano + agente), pasar de spec a producción en un día deja de ser una promesa de marketing y se convierte en un patrón repetible.

En la próxima publicación compartiremos una plantilla de spec y un ejemplo real de CLAUDE.md listo para copiar/pegar que puedes usar en tu primer experimento de migración con Claude Code.

FAQ

 

• ¿Qué es CLAUDE.md y por qué es obligatorio?
• ¿Cuánto contexto debe recibir cada sesión de Claude Code?
• ¿Qué deben incluir las tareas atomizadas?
• ¿Qué validaciones humanas son imprescindibles?
• ¿Cómo se gestiona la integración cuando un módulo falla tests?
• ¿Por qué evitar sesiones globales con el agente?

 

¿Qué es CLAUDE.md y por qué es obligatorio?

CLAUDE.md es un archivo en la raíz del repositorio que contiene el stack, comandos, convenciones, patrones prohibidos y thresholds de CI. Es obligatorio porque Claude Code incorpora este archivo al contexto inicial; sin él, el agente puede “inventar” decisiones arquitectónicas.

¿Cuánto contexto debe recibir cada sesión de Claude Code?

Cada sesión debe recibir el contexto mínimo necesario: el CLAUDE.md, la spec del módulo y solo los archivos relevantes. Reducir el contexto evita alucinaciones arquitectónicas y decisiones implícitas.

¿Qué deben incluir las tareas atomizadas?

Las tareas deben ser verificables y pequeñas: crear tipos, implementar funciones concretas, añadir tests unitarios. Ejemplos: “añadir interfaz X” o “implementar función Y”.

¿Qué validaciones humanas son imprescindibles?

Revisiones rápidas contra la spec: firmas de API, cumplimiento de patrones prohibidos en CLAUDE.md, que los tests pasen y que la cobertura cumpla los mínimos definidos.

¿Cómo se gestiona la integración cuando un módulo falla tests?

Si un módulo falla, el alcance de corrección se acota a ese módulo. Se corrige, se vuelve a ejecutar tests y se reintegra según el DAG de dependencias, sin rehacer toda la migración.

¿Por qué evitar sesiones globales con el agente?

Las sesiones globales saturan el contexto del agente y llevan a decisiones implícitas y variedad de implementaciones inconsistentes. Las sesiones acotadas garantizan consistencia y verificabilidad.