DOMINICODE

Category: Claude Code

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

    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

    • Ideas clave:
    • Claude Code funciona como un ejecutor: especifica antes de ejecutar y valida antes de integrar.
    • Divide la migración en módulos atómicos con contratos y tests incluidos.
    • Usa sesiones acotadas para evitar que el agente “invente” decisiones arquitectónicas.
    • Revisión humana en cada handoff y pipelines de CI por módulo son obligatorios.

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

    Referencias clave

    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?

    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.

  • Dominando Claude Code como agente CLI para automatización efectiva

    Dominando Claude Code como agente CLI para automatización efectiva

    Claude Code – La guía práctica: Ingeniería de agentes en la terminal

    Tiempo estimado de lectura: 4 min

    • Claude Code es un agente CLI que lee árbol de archivos, ejecuta bash, corre tests y propone parches; requiere sandboxes y gobernanza técnica.
    • Controla tokens y contexto desde el día 1 usando comandos operativos como /cost, /compact y flags como --safe.
    • Define prompts como contratos con contexto, tarea, restricciones, verificación y condición de parada para evitar bucles.
    • Extiende de forma segura con MCP y orquesta validaciones con n8n; nunca expongas credenciales y aísla ejecuciones en contenedores.
    • Aplica políticas de seguridad, revisión humana obligatoria y auditoría de logs antes de producción.

    Claude Code – La guía práctica es el manual operativo que necesitas si tu equipo va a delegar trabajo real en un agente CLI. Claude Code (Claude 3.7 Sonnet) no es un autocompletador: es un agente que lee el árbol de archivos, ejecuta bash, corre tests y propone parches. Dominarlo exige reglas claras, sandboxes y gobernanza técnica.

    Resumen rápido (lectores con prisa)

    Claude Code es un agente CLI capaz de operar sobre repositorios (leer archivos, ejecutar comandos, proponer parches). Úsalo con sandboxes (Docker/DevContainers), define prompts como contratos y controla costes con comandos como /cost. Extiende funciones con MCP y orquesta validaciones con n8n, manteniendo revisión humana para cambios sensibles.

    Claude Code – La guía práctica: qué aprender primero

    Arranca por lo esencial. La documentación oficial y el MCP son la base:

    Instalación básica

    Instalación global con npm:

    npm install -g @anthropic-ai/claude-code

    Crea un .claudeignore en la raíz para proteger secretos:

    .env*
node_modules/
dist/
secrets/
*.log

    Lee “Permissions and Security” en la docs antes de ejecutar en repos real. No es opcional.

    Fundamentos operativos: control de contexto y coste

    Claude Code consume tokens por lectura/escritura. Controla eso desde el día 1.

    Operaciones y flags

    • /cost — audita tokens de la sesión. Obliga a revisar antes de tareas largas.
    • /compact — comprime historial de conversación para evitar alucinaciones si el agente lleva horas iterando.
    • /abort — detiene loops. Úsalo rápido si ves repetición.
    • Flags: --safe (revisar comandos propuestos), --read-only (auditoría sin mutar), --detach (tareas largas en background).

    Estos comandos son tus palancas operativas para no perder control.

    Ingeniería de prompts y contratos de ejecución

    Un prompt es un contrato, no un deseo. Estructura clara:

    • Contexto (stack, convenciones).
    • Tarea (qué cambiar).
    • Restricciones (qué no tocar).
    • Verificación (tests, coverage, linter).
    • Condición de parada (máx iteraciones).

    Ejemplo compactado

    Contexto: Angular 22 Zoneless.
Tarea: Migrar src/dashboard a Standalone Components usando Signals.
Restricciones: No tocar auth-service.
Verificación: Ejecutar `vitest --coverage` y superar 90%.
Parada: Abortar si >3 iteraciones fallidas.

    Sin eso, el agente entra en bucles y consume tokens sin producir valor.

    Extensibilidad: MCP y orquestación con n8n

    MCP te permite dar herramientas seguras al agente. Monta un servidor MCP interno y expón solo capacidades limitadas (leer DB, disparar webhooks), nunca credenciales.

    Ejemplo conceptual de servidor MCP (Node.js)

    // mcp-server.js (conceptual)
const { createServer } = require('mcp');
const server = createServer({
  capabilities: {
    read_file: true,
    execute_shell: { shell: 'bash', workingDir: '/workspace' },
    trigger_n8n: { url: 'http://localhost:5678/webhook' }
  }
});
server.listen(8080);

    Integra con Claude Code: /mcp add --url http://localhost:8080.

    Flujo n8n recomendado

    1. Claude genera diff + artefactos.
    2. MCP envia payload a n8n.
    3. n8n ejecuta validaciones (linters, tests), crea ticket y notifica Slack.

    Así mantienes trazabilidad y control humano.

    Seguridad y sandboxing: reglas innegociables

    • Nunca ejecutes tareas destructivas en la host machine. Usa Docker/DevContainers.
    • .claudeignore obligatorio y auditado por SAST.
    • Políticas de gasto: quotas por usuario/equipo en Anthropic Console.
    • Revisión humana obligatoria para cambios que modifiquen infra o credenciales.
    • Logs y auditoría: guarda transcripts de sesiones y resultados de /cost.

    Riesgos comunes y mitigaciones rápidas

    • Bucles por flaky tests → define max_iterations en prompt; usa --safe.
    • Consumo inesperado de tokens → descompón tareas; monitoriza /cost.
    • Fuga de secretos → .claudeignore + escaneo pre-run.
    • Dependencias legacy (p. ej. zone.js en Angular) → audita npm ls previo y fija tests que cubran edge cases.

    Cuándo adoptarlo (criterio para Tech Leads)

    Adopta Claude Code si:

    • Tienes stack moderno (TypeScript, Angular 22+, Next.js).
    • La base tiene tests automáticos (Vitest/Playwright).
    • Puedes aislar ejecuciones en contenedores y aplicar políticas de gasto.

    Pospón si:

    • Repo monolítico sin cobertura.
    • Equipo sin habilidades de prompt engineering.
    • Restricciones presupuestarias que no toleran picos de tokens.

    Roadmap práctico (4 semanas)

    • Semana 1: Sandbox + --safe, .claudeignore, métricas /cost.
    • Semana 2: Prompts estructurados y pruebas automáticas con Vitest.
    • Semana 3: Implementa servidor MCP mínimo y flujo n8n.
    • Semana 4: Políticas de gobernanza, cuotas, playbook de incidentes.

    Claude Code no es magia; es ingeniería aplicada. Monta sandbox, define contratos de prompts, limita el alcance con MCP y registra todo. Hazlo bien y convertirás la terminal en un colaborador que acelera refactors y tareas repetitivas sin apagar el control humano. Esto empieza hoy: configura el sandbox y documenta las reglas internas; el resto viene después.

    Dominicode Labs

    Para equipos que diseñan flujos de automatización y orquestación con agentes, una fuente útil de referencia y experimentación es Dominicode Labs. Puede servir como continuación lógica para prototipar MCP + n8n y playbooks de gobernanza.

    Referencias y recursos

    FAQ

    ¿Qué es Claude Code y en qué se diferencia de un autocompletador?

    Claude Code es un agente CLI que puede leer el árbol de archivos, ejecutar comandos de shell, correr tests y proponer parches. No es solo un autocompletador: realiza acciones sobre el repositorio y requiere control operativo y políticas de seguridad.

    ¿Cómo evito que el agente consuma tokens excesivos?

    Monitorea con /cost, descompón tareas largas, establece max_iterations en prompts y usa /compact para reducir historial. Usa flags como --safe para revisar comandos propuestos.

    ¿Qué medidas de seguridad son obligatorias antes de ejecutar en repos reales?

    Usar sandboxes (Docker/DevContainers), tener .claudeignore auditado por SAST, cuotas en Anthropic Console y revisión humana para cambios que modifiquen infra o credenciales.

    ¿Qué es MCP y por qué usarlo?

    MCP (Model Context Protocol) permite exponer capacidades limitadas y seguras al agente (leer archivos, ejecutar shell controlado, disparar webhooks) sin revelar credenciales. Facilita gobernanza y trazabilidad.

    ¿Cuándo debo usar --safe o --read-only?

    Usa --safe para revisar comandos propuestos por el agente en tareas de riesgo, y --read-only para auditorías o análisis sin mutar el repositorio.

    ¿Cómo integro validaciones automáticas con n8n?

    Configura MCP para enviar payloads a n8n; n8n ejecuta linters y tests, crea tickets y notifica Slack. El flujo recomendado: Claude genera diff, MCP envía a n8n, n8n valida y crea trazabilidad.

    ¿Qué debe incluir un prompt para evitar bucles?

    Un prompt debe contener: contexto (stack), tarea específica, restricciones explícitas, criterios de verificación (tests, coverage) y condición de parada (máx iteraciones).