DOMINICODE

Category: Claude Code

  • Cómo implementar CLAUDE.md para agentes de código automatizados

    Cómo implementar CLAUDE.md para agentes de código automatizados

    CLAUDE.md: el contrato entre tú y el agente

    Tiempo estimado de lectura: 6 min

    • Define reglas operativas claras para evitar que agentes automaticen o “improvisen” sobre código base.
    • Estandariza stack, comandos y convenciones para que el agente genere cambios compatibles con el repositorio.
    • Mantén el archivo actualizado y versiónalo junto con cambios en el stack para evitar divergencias.

    Introducción

    CLAUDE.md: el contrato entre tú y el agente es el punto de control que evita que Claude Code “improvise” sobre tu base de código. Colocar ese archivo en la raíz del repo cambia la relación: el agente deja de adivinar y empieza a obedecer reglas explícitas antes de generar cualquier cambio.

    Claude Code incorpora los CLAUDE.md al contexto inicial de la sesión. Si quieres que el agente respete decisiones de arquitectura, convenciones y restricciones operativas, no hay atajo: ponlas por escrito en un CLAUDE.md que Claude pueda leer. Para entender el diseño técnico del protocolo, revisa la documentación oficial (Anthropic — claude-code) y la página de Claude en Anthropic.

    ¿Qué debe contener un CLAUDE.md?

    Un CLAUDE.md no es un README para humanos ni un changelog. Es un contrato operativo para máquinas. Limítalo a lo esencial que el agente necesita conocer para no romper invariantes del sistema. Divide el archivo en cuatro bloques obligatorios:

    • 1. Stack técnico y decisiones no negociables.
    • 2. Comandos operativos (build, test, lint).
    • 3. Convenciones de código que el linter no puede forzar.
    • 4. Patrones prohibidos y límites de seguridad.

    A continuación, una plantilla mínima que puedes adaptar.

    Plantilla mínima

    ## Stack
- Next.js 14 (App Router). No Pages Router.
- TypeScript (strict: true).
- Tailwind CSS. No CSS Modules ni styled-components.
- Prisma como ORM. No SQL raw salvo migraciones.

## Comandos
- `pnpm dev` — dev server
- `pnpm test` — Jest (coverage >= 80%)
- `pnpm lint` — ESLint (project config)
- `pnpm build` — build prod (sin warnings)

## Convenciones
- Componentes: PascalCase en `/src/components`.
- Hooks: prefijo `use` en `/src/hooks`.
- Errores: usar tipos, no `any`. `catch(e: unknown)` -> narrow.
- No llamadas a APIs desde componentes: usar `/src/services`.

## Patrones prohibidos
- No introducir dependencias sin PR aprobado.
- No usar `useEffect` para sincronización derivada.
- No crear contextos globales nuevos; usar Zustand.

    ¿Dónde colocarlo en monorepos?

    Claude Code respeta jerarquías: lee CLAUDE.md en la raíz y en submódulos relevantes. En monorepos, combina reglas globales con reglas locales:

    • /CLAUDE.md — reglas globales (tooling, CI, linters)
    • /apps/web/CLAUDE.md — reglas específicas del frontend
    • /packages/ui/CLAUDE.md — reglas del diseño compartido

    El agente fusiona las reglas aplicables según el contexto del archivo que edita. Esto te permite mantener consistencia sin replicar todo el contrato en cada paquete.

    Cómo cambia el flujo de trabajo con un CLAUDE.md

    Sin CLAUDE.md, cada sesión de Claude Code es una pizarra limpia: el agente infiere patrones, instala dependencias y propone cambios que “funcionan” pero rompen la coherencia del repo. Con CLAUDE.md:

    • El agente conoce el tooling exacto (ej. pnpm vs npm) y no ejecuta comandos incorrectos.
    • No propone o instala librerías fuera del stack definido.
    • Genera código que cumple las convenciones locales: ubicación de archivos, nombres, patrones de error.
    • Respeta las reglas de seguridad y de auditoría (por ejemplo, rutas que requieren autorización).

    El resultado práctico: menos PRs de corrección, menos reescrituras y menos deuda técnica introducida por el agente.

    Mantenimiento: el contrato debe evolucionar con el código

    Un CLAUDE.md desactualizado es peor que no tenerlo. El agente aplicará reglas obsoletas con tanta disciplina como aplicaría las correctas.

    Reglas simples de mantenimiento:

    • Actualiza CLAUDE.md en el mismo PR que cambia el stack o introduce un patrón nuevo.
    • Versiona las secciones críticas (ej. Stack v2) si el cambio es migratorio.
    • Añade ejemplos de I/O cuando la interacción es ambigua (ej. formatos JSON esperados).
    • No uses el archivo para documentación extensa de negocio; su propósito es técnico y operativo.

    Casos prácticos y límites

    – Si tu agente debe interactuar con la UI (acciones del DOM), documenta los casos en CLAUDE.md pero combina con una especificación de UI semántica (p. ej., WebMCP).
    – No almacenes secretos ni variables de entorno en CLAUDE.md. Usa vaults y referencias a los secretos gestionados por CI/CD.
    – Si tu repositorio permite múltiples stacks (ej. experimentos), usa CLAUDE.md por carpeta para evitar ambigüedades.

    Conclusión

    CLAUDE.md: el contrato entre tú y el agente es una inversión pequeña con retorno inmediato. Poner las reglas por escrito antes de pedirle a Claude Code que haga cambios transforma una relación de adivinanza en una colaboración predecible. Si tu objetivo es integrar agentes de forma práctica y segura, escribir y mantener CLAUDE.md debería ser parte del proceso de desarrollo —actualizado en el mismo PR que cambia tu arquitectura— no una tarea opcional.

    Dominicode Labs

    Para equipos que trabajan con agentes, automatización y flujos de trabajo técnicos, la práctica de formalizar contratos operativos como CLAUDE.md encaja con iniciativas de investigación aplicada. Más recursos y experimentos relacionados están disponibles en Dominicode Labs.

    FAQ

    Respuesta: ¿Qué es un CLAUDE.md y para qué sirve?

    Un CLAUDE.md es un archivo de reglas operativas que define cómo un agente (ej. Claude Code) debe comportarse respecto al repositorio. Sirve para evitar que el agente realice cambios incompatibles o no autorizados.

    Respuesta: ¿Dónde debe ubicarse en un monorepo?

    Colócalo en la raíz del repositorio para reglas globales y en subcarpetas relevantes para reglas locales (por ejemplo, /apps/web/CLAUDE.md). Claude Code combinará las reglas aplicables.

    Respuesta: ¿Qué pasa si no lo actualizo?

    Si está desactualizado, el agente aplicará reglas obsoletas, lo que puede introducir errores o incoherencias. Actualízalo en el mismo PR que modifica el stack o las convenciones.

    Respuesta: ¿Puedo incluir secretos en CLAUDE.md?

    No. No almacenes secretos ni variables de entorno en CLAUDE.md. Usa vaults o referencias gestionadas por CI/CD.

    Respuesta: ¿Cómo integro cambios en el contrato durante una migración del stack?

    Versiona secciones críticas (ej. “Stack v2”) y añade la actualización en el mismo PR que realiza la migración para mantener coherencia entre el código y el contrato.

  • Cómo usar Claude Code para tareas sin ser developer

    Cómo usar Claude Code para tareas sin ser developer

    Es claude code tan solo para developers ? 3 cosas que puedes hacer con claude sin ser developer

    “Tiempo estimado de lectura: 3 min”

    • Claude Code es una herramienta orientada a terminales y repos; Claude (modelo web/API) ofrece razonamiento técnico accesible sin instalar dependencias.
    • Con Claude puedes diseñar y depurar workflows en herramientas como n8n (automatización), transformar y analizar datos, y generar documentación y diagramas (Mermaid, OpenAPI).
    • La diferencia clave no es saber programar, sino estructurar problemas y validar hipótesis técnicas usando el modelo web/API.

    Introducción

    Es claude code tan solo para developers ? Si escuchaste “CLI” y cerraste la puerta, respira: la respuesta técnica es sí —pero la historia completa no es tan simple.

    Claude Code (el agente CLI de Anthropic) está pensado para terminales, repos y tareas que tocan el código. Pero Claude, el modelo, vive en la web, en APIs y en integraciones: te da razonamiento técnico sin obligarte a teclear npm install. Aquí te explico por qué importa y tres cosas concretas que puedes hacer sin ser developer.

    Resumen rápido (lectores con prisa)

    Qué es: Claude Code es un agente CLI; Claude (modelo) se accede vía web/API e integraciones.

    Cuándo usarlo: Usa Claude Code si un agente debe tocar tu repo y ejecutar tests; usa Claude Web/API para razonamiento, diseño de flujos y transformación de datos.

    Por qué importa: Permite a non-devs con criterio diseñar, validar y documentar soluciones técnicas sin convertirse en especialistas en sintaxis.

    Cómo funciona: En vez de escribir sintaxis, describes escenarios, estructuras y reglas; el modelo transforma esa descripción en snippets, esquemas y diagramas reutilizables.

    Es claude code tan solo para developers ? Lo esencial en 60 segundos

    Claude Code = herramienta para desarrolladores. Vive en la terminal. Requiere Git, variables de entorno y un repo que pueda inspeccionar y modificar.

    Claude (3.7 Sonnet y variantes) = modelo razonador accesible por web/API. No necesitas compilar nada, sí necesitas saber explicar problemas con precisión. En vez de escribir sintaxis, planteas escenarios, estructuras de datos y reglas. El peso se traslada del teclado al criterio.

    Traducción práctica: si eres product manager, automation builder o founder, puedes usar Claude como copiloto intelectual. No como quien programa, sino como quien diseña y valida soluciones.

    1) Diseñar y depurar workflows en n8n — sin tocar Node.js

    n8n es el lugar donde los flujos se vuelven reales. Pero cuando un JSON llega sucio o una API no tiene nodo nativo, la fricción aparece.

    Lo que haces con Claude:

    • Pegas el payload del webhook y pides: “Dame el fragmento JS para extraer estos campos y normalizarlos.”
    • Le pides la lógica de reintentos y manejo de errores: condiciones, backoff y notificaciones.
    • Si una API requiere HMAC o firma en cabeceras, Claude te escribe la plantilla para el nodo HTTP.

    Ejemplo (conceptual): le describes el JSON y obtienes el snippet listo para pegar en un Code Node de n8n. No tienes que memorizar async/await; solo validar la salida.

    Referencia: n8n (automatización)

    2) Transformar y analizar datos — sin pelear con hojas de cálculo eternas

    Limpiar datos es un agujero negro. Claude lo hace predecible.

    Casos concretos:

    • Generar regex para extraer emails, IDs o patrones específicos. (“Extrae solo .edu y .org que parezcan institucionales.”)
    • Convertir CSV/XML desordenados a JSON con esquema validado. Pegas 50 filas y pides el JSON-schema.
    • Redactar consultas SQL complejas: joins, ventanas, filtros por fechas. Le das la estructura de tablas y la métrica que quieres; él devuelve la query optimizada para tu caso.

    No es “codificar por ti”. Es convertir trabajo repetitivo y propenso a errores en instrucciones reproducibles.

    3) Documentación y diagramas técnicos que no te roban medio día

    El 70% del valor de una decisión técnica está en cómo se comunica. Claude entiende Mermaid.js y puede producir diagramas desde tu texto.

    Lo que recibes:

    • Código Mermaid listo para pegar en Notion o GitHub y ver el diagrama al instante.
    • Un borrador de OpenAPI a partir de la descripción de un endpoint (paths, parámetros, respuestas).
    • Un mapa de arquitectura cloud con dependencias y puntos de integración (ideal para alinear con ingeniería sin sonar inocente).

    Pequeña ventaja: llegas a la reunión con algo que se puede visualizar y discutir, no con una vaga idea.

    Docu: Mermaid (diagramas) · OpenAPI spec

    ¿Cómo decidir si usar Claude Code o Claude Web/API?

    Regla simple:

    • Si vas a dejar que un agente toque tu repo, ejecuciones y tests: Claude Code (requiere developer).
    • Si necesitas razonamiento, diseño de flujos, transformación de datos o documentación: Claude Web/API o integraciones (ideal para non-devs con criterio).

    El nuevo diferencial no es “saber programar”. Es saber estructurar problemas y validar hipótesis técnicas. Claude amplifica eso.

    Conclusión

    No conviertas la terminal en el test de tu valía. Aprende a describir problemas con precisión y tendrás una herramienta que piensa en arquitectura, no solo en sintaxis. Esto apenas comienza: la próxima ronda será cómo integrar Claude en tus procesos de despliegue y gobernanza sin romper producción.

    Fuentes útiles: Anthropic – Claude, n8n (automatización), Mermaid (diagramas), OpenAPI spec

    Para explorar implementaciones y experimentos relacionados con automatización y agentes, visita Dominicode Labs. Es una continuación lógica para quien quiere pasar del diseño a prototipos reproducibles.

    FAQ

    Respuesta: Claude Code es el agente CLI de Anthropic diseñado para operar en terminales y repos (requiere Git, variables de entorno y permisos de repo). Claude, en cambio, es el modelo accesible por web/API e integraciones y está orientado a razonamiento y generación sin necesidad de ejecutar comandos locales.

    Respuesta: No. Para acceder al razonamiento y generación de soluciones técnicas puedes usar Claude Web/API o integraciones; no necesitas ser developer, pero sí saber describir problemas con precisión.

    Respuesta: Sí. Puedes describir el payload o el problema y pedir snippets o plantillas listos para pegar en un Code Node de n8n, así evitas escribir Node.js desde cero.

    Respuesta: Generación de regex, conversión de CSV/XML a JSON con esquema validado, y redacción de consultas SQL complejas (joins, ventanas y filtros). Claude transforma tareas repetitivas en instrucciones reproducibles.

    Respuesta: Sí. Claude puede producir código Mermaid y borradores de OpenAPI que se pegan directamente en herramientas como Notion o GitHub para visualización inmediata.

    Respuesta: Elige que un agente toque tu repositorio cuando sea necesario ejecutar pruebas, aplicar cambios automáticos o inspeccionar código de forma programática. Si solo necesitas diseño, razonamiento o generación de artefactos técnicos, la web/API suele ser suficiente.

  • Implementación efectiva con Plan Mode en Claude Code

    Implementación efectiva con Plan Mode en Claude Code

    Plan Mode primero, código después: el workflow que cambia cómo trabajas con Claude Code

    Tiempo estimado de lectura: 5 min

    • Plan Mode obliga a auditar y planear antes de ejecutar cambios en código.
    • Workflow en tres fases: análisis, refinamiento y ejecución; cada fase reduce riesgo y scope de impacto.
    • Activa Plan Mode en cambios multiplataforma, código heredado o integraciones de librerías arquitectónicas.
    • Mide efectividad por integración sin rollback, estabilidad en CI y ahorro de horas en debugging.

    Plan Mode primero, código después es la regla que separa entregas limpias de correcciones interminables. Activa Plan Mode, deja que Claude analice el repositorio y produzca un plan antes de que toque una sola línea de código. Esa inversión de diez minutos evita horas de debugging por decisiones implícitas.

    Resumen rápido (lectores con prisa)

    Plan Mode obliga a auditar y planear cambios antes de codificar. Úsalo cuando el cambio implica múltiples archivos, código heredado o librerías que afectan la arquitectura. Workflow: análisis, refinamiento y ejecución. Mide por integración sin rollback y estabilidad en CI.

    Plan Mode primero, código después: qué es y por qué importa

    Plan Mode es un modo de sesión en Claude Code que obliga al agente a auditar el código existente, mapear dependencias y proponer una secuencia de cambios verificable antes de implementar. Se activa con Shift+Tab en sesiones interactivas de Claude Code; la documentación oficial lo describe como un flujo que prioriza planificación sobre ejecución (https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview y https://www.anthropic.com/claude).

    ¿Por qué importa? Porque los errores de diseño no son fallos de sintaxis: son decisiones implícitas que se propagan. Implementar primero amplifica esos errores. Planear primero los expone cuando aún cuestan cero cambios.

    Cómo funciona el workflow (práctico y repetible)

    El workflow consta de tres fases claras: análisis, refinamiento y ejecución. No son sugerencias; son pasos que los equipos efectivos repiten cuando integran agentes en su proceso.

    1) Análisis inicial (activar Plan Mode)

    Activa Plan Mode (Shift+Tab). Describe el objetivo como contrato, no como receta. Ejemplo: “Aísla la lógica de autenticación para pruebas unitarias sin DB” en vez de “usa repositorio para auth”. Deja que Claude liste archivos relevantes, dependencias directas y riesgos.

    2) Revisión y refinamiento (iterar sobre el plan)

    Lee el plan: archivos a tocar, orden propuesto, efectos secundarios y tests necesarios. Corrige límites de dominio si hace falta. Esa iteración es barata: texto, no commits. Aquí se define el alcance real y se evitan sorpresas de integración.

    3) Aprobación e implementación (ejecutar con control)

    Aprobas el plan y Claude implementa en el orden validado. Cada cambio es acotado, con tests adjuntos y notas de diseño. Si algo rompe, el impacto está limitado al módulo que se aprobó, no a toda la base de código.

    Ejemplo real de uso en migración

    Meta: migrar API REST a tRPC por módulos.

    Spec

    • Módulo A: AuthService (sin dependencias).
    • Módulo B: UserService (depende de A).
    • Módulo C: Billing (depende de B).

    Con Plan Mode, Claude devuelve: archivos a crear/modificar por módulo, tipos DTO esperados, tests unitarios y orden de merges. Implementación ocurre por sesión por módulo. Resultado: integraciones predecibles y rollback sencillo.

    Cuándo activar Plan Mode (criterio técnico)

    Activa Plan Mode cuando:

    • El cambio afecta múltiples archivos o contracts públicos.
    • Trabajas en código heredado que no conoces.
    • Vas a integrar una librería que afecta la arquitectura (auth, DB, infra).
    • La tarea es una refactorización o migración.

    No lo actives cuando:

    • El cambio es un ajuste pequeño en un único archivo.
    • Creas un archivo nuevo con una spec cerrada.
    • Resuelves un typo o validación trivial.

    El criterio es simple: a mayor riesgo arquitectónico, mayor valor del plan previo.

    Reglas prácticas para que Plan Mode funcione

    • Siempre comienza con CLAUDE.md actualizado. El agente leerá convenciones y patrones prohibidos antes de planear (si tu repo lo tiene, intégralo; si no, crea uno).
    • Exige que el plan incluya: archivos modificados, orden de cambios, tests a ejecutar y riesgos conocidos.
    • Valida el plan tú, un peer o el tech lead; las aprobaciones humanas reducen regresiones.
    • Mantén las sesiones acotadas: una sesión = un módulo. Evita planos globales indefinidos.

    Métricas que importan (no solo LOC/hora)

    Mide efectividad por:

    • Tiempo hasta integración sin rollback.
    • Número de handoffs con correcciones arquitectónicas.
    • Cobertura y estabilidad en CI tras cada merge.
    • Tiempo invertido en revisión del plan vs. horas ahorradas en debugging.

    Un plan de 10 minutos que evita 2 horas de corrección es ROI directo.

    Riesgos y límites honestos

    Plan Mode reduce errores, no elimina la necesidad de juicio humano. Si la spec es ambigua, Claude producirá una implementación ambigua más rápido. El agente no reemplaza decisiones críticas de diseño, trade-offs de rendimiento o consideraciones legales de seguridad. Su fuerza está en ejecutar lo que tú especificas mejor y antes de que toque escribir código.

    Conclusión

    Adoptar “Plan Mode primero, código después” cambia la métrica del equipo: de velocidad de salida a resiliencia de la plataforma. Si quieres que Claude Code deje de ser un generador de parches y pase a ser un colaborador técnico confiable, exige un plan. Haz que piense antes de tocar tu repo.

    Para equipos que exploran workflows, integraciones y automatización avanzada, consulta Dominicode Labs como continuación lógica del enfoque: recursos y experimentos centrados en agentes y productividad técnica.

    FAQ

    ¿Qué es Plan Mode?

    Plan Mode es un modo de sesión en Claude Code que obliga al agente a auditar el código existente, mapear dependencias y proponer una secuencia de cambios verificable antes de implementar.

    ¿Cuándo debo activarlo?

    Actívalo cuando el cambio afecta múltiples archivos, trabajas en código heredado, o integras librerías que afectan la arquitectura. Para cambios pequeños y aislados no es necesario.

    ¿Qué debe incluir un plan mínimo?

    El plan debe listar archivos a modificar, orden de cambios, tests a ejecutar y riesgos conocidos. También conviene indicar límites de dominio y criterios de aceptación.

    ¿Cómo reduce el riesgo en migraciones?

    Al definir el alcance y el orden de merge por módulo, limita el blast radius y facilita rollbacks. Permite validar la integración por partes con tests adjuntos.

    ¿Plan Mode reemplaza la revisión humana?

    No. Plan Mode reduce errores estructurales, pero las aprobaciones humanas siguen siendo necesarias para decisiones críticas y trade-offs no técnicos.

    ¿Qué métricas debe rastrear mi equipo?

    Tiempo hasta integración sin rollback, número de handoffs con correcciones arquitectónicas, cobertura y estabilidad en CI, y la relación entre tiempo de planificación y horas ahorradas en debugging.

  • 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).