DOMINICODE

Tag: AI

  • Cómo usar especificaciones en desarrollo con IA para evitar problemas

    Cómo usar especificaciones en desarrollo con IA para evitar problemas

    ¿Quieres acelerar el desarrollo con IA o quieres estrellarte más rápido?

    Tiempo estimado de lectura: 6 min

    • La spec corta y accesible es imprescindible cuando usas IA para generar código.
    • Sin spec aparecen tres síntomas: incoherencia de estilo, pérdida de contexto y acoplamiento brutal.
    • Implementa una SPEC.md en la raíz, define contratos y divide el trabajo en prompts modulares.
    • Convierte al desarrollador senior en guardián de la spec para revisar PRs generados por IA.

    Poca gente habla de esto en las charlas brillantes de conferencias: darle a una IA permiso para escribir código sin una spec es como dejar a un pintor con un bote de pintura en la cocina de tu casa. Va a pintar rápido. Va a ser espectacular durante cinco minutos. Y luego tendrás harina pegada en la pared, cables pelados y una silla rota.

    Esto no es exageración. Es un patrón. Lo veo en proyectos pequeños y en réplicas gigantes: la velocidad instantánea convierte decisiones críticas de arquitectura en improvisación. Y la improvisación, por definición, no escala.

    Resumen rápido (lectores con prisa)

    • Qué es: Una spec es un archivo vivo y accesible que define objetivos, límites, reglas y contratos que la IA debe respetar.
    • Cuándo usarla: Siempre que el código toque dominio, datos, seguridad o infraestructura crítica.
    • Por qué importa: Evita decisiones locales de la IA que llevan a incoherencia, pérdida de contexto y acoplamiento.
    • Cómo funciona: Sirve al agente como brújula: convierte prompts vagos en contratos concretos y verificables.

    ¿Por qué la spec es el arma secreta (y olvidada) al programar con IA?

    La spec no es burocracia. No es un PDF que acumula polvo. Es el plano que limita la creatividad sin matarla. Es la instrucción que obliga a la IA a optimizar por coherencia, no por conveniencia momentánea. En términos sencillos: la spec transforma “hacer que funcione” en “hacer que funcione y siga funcionando”.

    Modelos probabilísticos y decisiones

    Poca gente entiende algo crucial: los modelos de lenguaje son motores probabilísticos. Responden con la solución más probable según su entrenamiento y tu prompt. No saben ni les importa tu SLA, tu GDPR ni el culto interno a las serverless functions que montaste el año pasado. Si no les pones una spec, toman decisiones por ti. Y esas decisiones rara vez son las correctas para tu sistema.

    Descubrí algo curioso: cuando un equipo usa IA sin spec, aparecen siempre tres síntomas en el código.

    1) Incoherencia estilística que mata el mantenimiento.

    Un archivo usa Fetch, otro Axios, otro una función casera que alguien copió de StackOverflow. Ninguna regla es compartida. El README promete TypeScript y encuentras middleware en JavaScript puro. La IA actúa por contexto inmediato, no por coherencia global.

    2) Pérdida de contexto.

    Las ventanas de los modelos tienen límite. Lo que no está fijado en una spec, desaparece del escenario cuando la conversación se estira. Resultado: soluciones que olvidan requisitos críticos (idempotencia, manejo de errores, validaciones).

    3) Acoplamiento brutal.

    Funciones monolíticas que mezclan acceso a datos, lógica de negocio y presentación. Todo junto. Porque la IA optimizó para el prompt: “haz que funcione ya”, no para testabilidad o escalabilidad.

    Esto tiene nombre: alucinación arquitectónica

    No es que la IA invente una ruta inexistente; inventa la forma en que tu sistema debería operar. Propone abstracciones que no encajan. Implementa patrones que rompen tus contratos. Y lo peor: lo hace con convicción. Te entrega un PR impecable y peligroso.

    Si trabajas con Next.js y pides “sistema de autenticación” sin más, la IA te va a devolver lo que suele devolver: la solución más popular en sus datos. ¿Que tu empresa requiere tokens rotativos y encriptación extra? La IA lo ignora. ¿Que solo se debe usar server components para ciertas páginas? La IA lo ignora. No lo hace con malicia. Lo hace por probabilidad estadística.

    Entonces, ¿qué es una spec moderna para desarrollo con IA?

    No es el viejo documento de 50 páginas que nadie lee. Es el System Prompt del repositorio. Es un archivo vivo, legible por humanos y por agentes. Contiene las respuestas a las preguntas que la IA no puede inferir del código: objetivos, límites, reglas y modelos de datos.

    Una spec efectiva incluye:

    • Objetivo funcional claro: qué problema resuelve este módulo y qué no debe hacer.
    • Stack y versiones permitidas: qué frameworks, librerías y versiones están aprobadas.
    • Reglas de arquitectura: patrones obligatorios (ej. “usar Server Components en Next.js salvo casos X”) y prácticas prohibidas.
    • Contratos de datos: interfaces TypeScript, esquemas de BD, formatos de API.
    • Políticas de seguridad y privacidad: qué información no puede exponerse, cómo manejar secretos.
    • Estrategia de testing y criterios de aceptación.

    Piensa en la spec como la brújula del proyecto. La IA es el marinero con experiencia, pero sin brújula se va con la corriente.

    Cómo empezar ahora mismo (sí, ahora): 5 pasos prácticos para evitar el caos

    1) Crea un SPEC.md en la raíz del repo.

    No lo escondas en Google Docs. Ponlo en el repo para que cualquier agente lo consuma. Que sea corto, directo y accionable. Primera frase: “Si esto cambia, consulta al team lead”. Segunda frase: “No uses X, usa Y”. Las reglas deben ser bullet points fáciles de aplicar.

    2) Define los contratos antes de pedir ejecución.

    Antes de pedir a la IA que escriba la lógica, define las interfaces. Si pides que implemente una función, dale la firma TypeScript y los tests. Esto convierte la tarea en un contrato a cumplir, no en una sugerencia.

    3) Usa archivos de reglas a nivel proyecto.

    Si tu herramienta lo permite, añade reglas que la IA lea automáticamente (.cursorrules, spec.json, etc.). Es la diferencia entre decir “por favor” y obligar. Hazlo parte del flujo de CI.

    4) Divide el trabajo en prompts modulares.

    No le pidas a la IA “haz todo”. Pide un plan paso a paso. Revisa el plan. Apruébalo. Luego pide que ejecute cada paso. Así preservas control y contexto, además de poder auditar decisiones.

    5) Convierte al desarrollador senior en guardián del criterio.

    El trabajo del senior no es escribir menos código; es decidir qué se debe escribir. Revisar PRs seguirá siendo necesario, pero con otro foco: ¿esto respeta la spec? ¿Esto escala? Si la respuesta es no, no merges.

    Historias reales: el junior, el senior y la IA

    Imagínate esto.

    El junior llega, emocionado. “Voy a acelerar. Uso Copilot y saco features.” En 48 horas hay un demo impresionante. El producto parece volar. La dirección está feliz.

    Luego viene la integración con otros servicios. El equipo descubre tokens rotos, errores raros en producción y tests que fallan en horarios impredecibles. El senior se sienta, mira el repo y ve 12 formas distintas de autenticación. Decide reescribir. Dos semanas perdidas en refactor. El demo se apaga.

    Cambia el final: el senior escribió la spec antes de empezar. El junior pidió permisos y la IA generó código que ya respetaba validaciones, logs y pruebas. Todo encajó. El demo no solo funcionó; aguantó.

    Metáfora rápida: la spec es el embudo

    La spec es el embudo que convierte la creatividad desenfrenada de la IA en soluciones útiles. Sin el embudo, la creatividad sale por todos lados y cubre el proyecto como aceite en el motor. Con el embudo, la creatividad llega donde debe y no inunda lo que no corresponde.

    No todo necesita spec rígida (también hay límites)

    Sí, hay casos donde pedirle a la IA que improvise está bien. Refactorizaciones locales, generación de mocks, o prototipos exploratorios. No necesitas una spec para cada línea de código. Pero necesitas reglas cuando el código toca el dominio, los datos, la seguridad o la infraestructura crítica.

    Regla práctica: cuando lo que cambias rompe contratos (APIs, bases de datos, auth, flujos críticos), necesitas una spec. Punto.

    Qué poner en la spec para que la IA realmente la entienda

    • Comandos claros: “No usar X”, “Usar Y con versión Z”.
    • Ejemplos: un snippet de código que es correcto y uno que no.
    • Criterios de aceptación: tests que deben pasar. Un checklist.
    • Casos borde: qué hacer con fallos del servicio, timeouts, reintentos.
    • Política de secretos: dónde y cómo almacenar tokens.
    • Responsabilidades: quién aprueba cambios que tocan módulos críticos.

    CTA simple y directo: haz esto ahora

    Abre tu repo. Crea SPEC.md. Escribe cinco cosas:

    • Objetivo del módulo en una frase.
    • Tres reglas de arquitectura innegociables.
    • Las interfaces de los datos (TypeScript).
    • Un test de aceptación.
    • Dónde poner secretos.

    Hazlo en los próximos 60 minutos. No lo dejes para el sprint. Si quieres, respóndeme este mensaje con “Quiero la plantilla” y te mando un SPEC.md listo para pegar en tu repo.

    Urgencia real: la deuda técnica no espera

    Cada PR que aceptas sin spec es una apuesta a que nadie tocará eso en seis meses. No confíes en esa apuesta. En seis meses, otro equipo, otro deadline o un pico inesperado de usuarios lo romperán. La deuda técnica es acumulativa y compite con tu tiempo de desarrollo futuro. Actuar ahora te evita horas de rehacer.

    Cierre que no cierra (a propósito)

    Si sigues creyendo que la IA es la varita mágica que arregla todo, tienes dos opciones: aprender a gobernarla o pagar el precio después. La spec es la forma más barata y efectiva de gobernarla.

    Esto no acaba aquí. Si quieres, te doy:

    • Una plantilla de SPEC.md.
    • Ejemplos de .cursorrules para Cursor.
    • Un checklist de revisión para PRs generados por IA.

    Dime cuál quieres y te lo mando. Ahora decide: acelerar desordenadamente o correr con una brújula. Tus commits lo recordarán.

    Si te interesa llevar estas prácticas a flujos automáticos y agentes dentro de proyectos reales, revisa recursos y experimentos prácticos en Dominicode Labs. Es una continuación natural para quien quiera convertir una spec en reglas consumibles por agentes.

    FAQ

    ¿Qué es exactamente una SPEC.md y dónde debe vivir?

    Es un archivo en la raíz del repositorio que documenta objetivos, reglas, contratos y criterios de aceptación. Debe estar en el repo para que agentes y desarrolladores lo consuman fácilmente.

    ¿Cuánto detalle necesita una spec?

    Suficiente para responder las preguntas que la IA no puede inferir: objetivos, límites, interfaces, versiones y criterios de prueba. Debe ser breve y accionable, no un tratado.

    ¿La spec reemplaza la revisión de código?

    No. Reduce el foco de la revisión: ahora el senior verifica cumplimiento de la spec, escalabilidad y contratos, en lugar de escribir todo el código.

    ¿Qué pasa si olvidamos actualizar la spec?

    La spec caduca y pierde valor. Debe ser un archivo vivo; incluye una línea de responsabilidad (quién aprueba cambios) para mantenerla vigente.

    ¿Cómo integro la spec en el CI?

    Añade validaciones automáticas que verifiquen contratos (types, esquemas), reglas de lint y que los tests de aceptación definidos en la spec pasen antes del merge.

    ¿Necesito una spec para prototipos?

    No siempre. Para prototipos exploratorios puedes prescindir de una spec rígida. Pero para cualquier cambio que afecte datos, seguridad o APIs, sí debes tener una spec.

  • Cómo SDD y TDD optimizan el desarrollo con Claude Code

    Cómo SDD y TDD optimizan el desarrollo con Claude Code

    SDD + TDD: el combo que convierte a Claude Code en un dev senior

    Tiempo estimado de lectura: 4 min

    • SDD reduce las decisiones del agente; TDD valida de forma determinista.
    • Especificación primero, tests después: contratos claros y criterios ejecutables.
    • Aplica cuando hay lógica crítica, APIs públicas y repositorios tipados.

    Introducción

    SDD + TDD: el combo que convierte a Claude Code en un dev senior. Poca gente lo practica en equipos que prueban agentes, y sin embargo es la diferencia entre recibir código usable o un cajón de sorpresas que rompe en producción.

    Claude Code (motor basado en Claude 3.7 Sonnet) puede leer tu repo, ejecutar comandos y escribir código. Genial. También puede inventar abstracciones, tocar capas que no debe y aplicar convenciones que no son las tuyas. La solución no es pedir menos; es pedir mejor: especificación primero, tests después.

    Resumen rápido (lectores con prisa)

    SDD = especificaciones codificadas (tipos, interfaces, reglas). TDD = tests que hacen las especificaciones ejecutables. Juntos reducen la improvisación del agente y transforman código generado en artefactos verificables y mantenibles.

    Por qué SDD + TDD: el combo que convierte a Claude Code en un dev senior

    Un modelo de lenguaje es, por naturaleza, probabilístico. Sin restricciones explícitas, el agente construirá “la versión más probable” de tu feature, no la versión correcta para tu sistema. SDD (Specification-Driven Development) fuerza el contrato: tipos, firmas, reglas y límites. TDD (Test-Driven Development) convierte esos contratos en criterios ejecutables: rojo, verde, refactor.

    Juntos funcionan así:

    • SDD reduce el espacio de decisiones del agente.
    • TDD da un criterio determinista para validar el trabajo.
    • Claude Code deja de improvisar y se limita a cumplir pruebas que tú definiste.

    Referencias útiles: Anthropic (Claude) docs, TDD (Martin Fowler).

    Qué debe incluir una SDD práctica para agentes

    No es un brief largo: es el mínimo necesario para quitar decisiones al modelo.

    • Tipos e interfaces visibles en código
      TypeScript: exporta types / interfaces antes de pedir implementación. (TypeScript: docs)
      Python: define modelos Pydantic para entradas/salidas. (Pydantic)
    • Reglas explícitas de efectos secundarios
      “Función pura — sin DB, sin llamadas HTTP” o “Permitido: escribir en tabla payments; Prohibido: llamar a servicios externos”.
    • Manejo de errores y contratos de retorno
      `Result<T, E>` vs excepciones. Si decides una convención, documenta y hazla código.
    • Casos límite documentados
      Inputs inválidos, límites numéricos, retries, timeouts, políticas de deduplicación.

    Escribe esto en archivos que el agente pueda leer (por ejemplo *.types.ts, *.schema.py, .md con reglas) y no lo dejes solo en un prompt.

    El ciclo TDD que hace verificable al agente

    Con la spec lista, el flujo TDD para Claude Code es práctico y repetible:

    • Fase Roja — Generar tests.
      Prompt: claude “Lee payment.types.ts y las reglas en comments. Genera tests en Vitest que cubran todos los casos límite. Ejecuta los tests y reporta fallos.”
      Resultado esperado: tests fallando (porque no hay implementación).
    • Fase Verde — Implementación mínima.
      Prompt: claude “Implementa payment.ts respetando los tipos. Ejecuta los tests y corrige hasta que pasen en verde. No cambies firmas ni añadas dependencias externas.”
    • Refactor — Mejorar con seguridad.
      Prompt: claude “Refactoriza para reducir la complejidad ciclomática, manteniendo todos los tests en verde.”

    Herramientas recomendadas para el ciclo: Vitest o Jest, integradas en la terminal que usa Claude Code.

    Ejemplo práctico (resumen)

    En vez de: “Crea validación de email”, escribe:

    • types.ts:
      – interface CreateUser { email: string; name?: string }
      – type Result = { ok: true; value: T } | { ok: false; error: string }
    • Comentario en createUser.ts:
      // Función pura. Rechaza dominios genéricos (gmail.com, hotmail.com). Retorna Result. No lanza excepciones.
    • Prompts:
      • Genera tests → ejecuta → confirma fallo.
      • Implementa hasta pasar tests → refactor.

    La diferencia es mínima en tiempo de setup y enorme en predictibilidad.

    Cuándo aplicar este enfoque (y cuándo no)

    Aplica SDD + TDD cuando:

    • Construyes lógica de negocio crítica o APIs públicas.
    • Trabajas en repositorios compartidos y tipados.
    • Necesitas trazabilidad y responsabilidad en cambios.

    No lo apliques para:

    • Scripts one-off o hacks exploratorios.
    • Prototipos que requieren máxima velocidad de experimentación.

    Lo que cambian estas prácticas en tu equipo

    La escritura de código se convierte en commodity; el verdadero valor pasa a:

    • Diseñar contratos claros.
    • Anticipar edge cases.
    • Traducir decisiones de producto a reglas verificables.

    Claude Code seguirá escribiendo código — pero ahora ese código será verificable y, lo que es más importante, mantenible. Si defines la partitura (SDD) y pones el metrónomo (TDD), el agente tocará afinado.

    Fuentes y lectura recomendada

    FAQ

    ¿Qué es SDD y en qué se diferencia de un brief tradicional?

    SDD (Specification-Driven Development) codifica las decisiones clave —tipos, interfaces, reglas de efectos secundarios— en artefactos que el agente puede leer. Un brief tradicional suele ser texto libre; SDD es código y contrato.

    ¿Por qué es necesario TDD cuando uso un agente capaz de ejecutar tests?

    TDD transforma la especificación en criterios ejecutables (tests). Sin tests, el agente puede producir la solución más probable; con tests, debe producir la solución que pasa los criterios que definiste (rojo → verde → refactor).

    ¿Qué archivos debo incluir en la SDD para que el agente los use?

    Archivos legibles por el agente: *.types.ts, *.schema.py, y .md con reglas y comentarios. Define tipos, modelos y reglas de efectos secundarios en esos archivos.

    ¿Puedo usar este flujo con agentes distintos a Claude Code?

    Sí. El patrón SDD + TDD es aplicable a agentes que puedan leer repositorios y ejecutar comandos. Se basa en contratos verificables y tests automatizados, no en peculiaridades de un motor concreto.

    ¿Qué herramientas recomiendan para ejecutar el ciclo TDD?

    Herramientas recomendadas: Vitest o Jest. Integradas en la terminal del agente para ejecutar fases Roja/Verde/Refactor.

    ¿Cómo manejo cambios de contrato sin romper downstream?

    Versiona tipos y contratos, introduce migraciones y añade tests de compatibilidad. Documenta cambios en la SDD y agrega pruebas que verifiquen compatibilidad hacia atrás cuando sea necesario.

    ¿Cuándo NO debo aplicar SDD + TDD?

    No lo apliques para scripts one-off, hacks exploratorios o prototipos donde la prioridad es iterar rápido sin garantías fuertes.

  • Implementación de Managed Agents en la Plataforma de Anthropic

    Implementación de Managed Agents en la Plataforma de Anthropic

    Anthropic lanzó Managed Agents — agentes de largo plazo en la plataforma

    Tiempo estimado de lectura: 4 min

    • Managed Agents mueve la responsabilidad de ejecutar agentes de largo plazo desde tu infraestructura hacia la plataforma de Anthropic.
    • Proporciona primitivas críticas: sesiones estables, sandboxes con estado duradero, harnesses de ejecución y gestión segura de herramientas/credenciales.
    • La Rate Limits API permite orquestar y escalar controlando capacidad disponible antes de lanzar trabajos.
    • Patrón práctico: usar un orquestador (ej. n8n) para desacoplar el lanzamiento y la finalización de las sesiones agénticas.
    • Riesgos: vendor lock-in, observabilidad limitada, fuga de datos temporales y límites de tasa; requieren políticas y controles explícitos.

    Introducción

    Anthropic lanzó Managed Agents — agentes de largo plazo en la plataforma el 25 de abril de 2026. Esta funcionalidad en Claude Platform no es una mejora menor: cambia la responsabilidad operativa de ejecutar agentes agénticos prolongados desde tu infraestructura hacia la plataforma de Anthropic. Fuente: Anthropic Platform Docs

    Resumen rápido (lectores con prisa)

    Managed Agents ofrece sesiones estables, sandboxes con estado duradero, harnesses y gestión de herramientas/credenciales en la plataforma. Reduce engineering necesario para ejecutar agentes asíncronos largos y añade una Rate Limits API para orquestación segura. Útil cuando priorizas velocidad de entrega; no es apropiado si necesitas control forense total sobre ejecución y datos.

    Qué significa que Anthropic lanzó Managed Agents — agentes de largo plazo en la plataforma

    La noticia clave es de infraestructura, no de modelo. Managed Agents provee primitivas que antes tenías que inventar: sesiones estables, sandboxes con estado duradero, harnesses de ejecución y acceso seguro a herramientas. Eso corrige tres cuellos de botella clásicos de agentes autónomos en producción:

    • Persistencia de estado entre pasos (que evita reinyectar historial en cada request).
    • Aislamiento y ejecución segura de código (sandboxes duraderos).
    • Gestión segura de credenciales y herramientas (Secure Tool Use).

    Estos elementos transforman agentes episódicos y frágiles en procesos asíncronos confiables que pueden correr horas sin reinyectar contexto manualmente.

    Componentes técnicos y por qué importan

    Interfaces estables para sesiones

    Managed Agents expone IDs de sesión y APIs para consultar su estado. Eso permite diseños desacoplados: lanzas un agente, recibes un session_id y vuelves más tarde por el resultado. En prácticas reales esto reduce el acoplamiento entre orquestador (n8n, cron, Lambda) y ejecución agéntica.

    Harnesses y sandboxes con estado duradero

    El harness controla la inyección de prompts y la ejecución de herramientas; el sandbox es el runtime persistente donde sobreviven variables, artefactos y dependencias entre pasos. Esto elimina el cold-start continuo y permite construcciones incrementales (tests encadenados, scraping por lotes, refactors multi-archivo) sin retransmitir todo el contexto en cada llamada.

    Acceso seguro a herramientas

    Anthropic gestiona credenciales y permisos en la plataforma. El agente consume interfaces a servicios externos sin exponer secrets dentro del texto del prompt o logs de razonamiento. Es un requisito mínimo para producción: evita fugas accidentales de credenciales y facilita auditoría centralizada.

    Startup optimizado

    Reducir la latencia de arranque entre pasos cambia el coste operativo de tareas largas. Si tu agente ejecuta cientos de scripts por sesión, el ahorro acumulado en tiempo y coste es real y medible.

    Rate Limits API: control programático del escalado

    El 25 de abril Anthropic también lanzó la Rate Limits API, que permite consultar programáticamente los límites de tokens y uso de la organización. Si vas a orquestar docenas de agentes concurrentes, necesitas este dato antes de lanzar trabajos. Patrón operativo recomendado:

    • Consulta la Rate Limits API antes de encolar un agente.
    • Si la capacidad disponible es < 20% (umbral configurable), encola la tarea y reintenta más tarde.
    • Prioriza trabajos críticos y aplica un backoff exponencial en la cola.

    Ejemplo (pseudocurl): curl -H “Authorization: Bearer $ANTHROPIC_KEY” Rate Limits API

    Integración práctica con n8n (patrón de arquitectura)

    n8n es el orquestador natural para este enfoque. Patrón de integración:

    1. n8n recibe trigger (webhook, cron, evento).
    2. Llama a Rate Limits API; decide lanzamiento o encolado.
    3. Si hay cuota, invoca Managed Agent con contexto y guarda session_id.
    4. n8n cierra la ejecución; recibe webhook de finalización o consulta el estado con polling.
    5. Procesa y distribuye resultado (commit a Git, notificación Slack, inserción en DB).

    Este patrón desacopla totalmente el tiempo real de ejecución del agente del flujo orquestador, permitiendo escalado horizontal sin mantener hilos abiertos.

    Riesgos, límites y controles que debes imponer

    1. Vendor lock-in y compliance: durante la ejecución, código e inputs residirán en la plataforma de Anthropic. Para entornos regulados (SOC 2, HIPAA) exige SLA/Docs de retención y capacidad de auditoría antes de producción.
    2. Observabilidad y debugging: cuando una sesión falla dentro del sandbox, las herramientas forenses pueden ser menos ricas que en tu propio Kubernetes. Diseña checkpoints y exporta artefactos intermedios a tu almacenamiento controlado (S3 cifrado) con permisos limitados.
    3. Fugas de datos temporales: define políticas de redacción y minimización de datos en prompts; sanea PII antes de enviar a la plataforma.
    4. Rate limits y resiliencia: no asumas disponibilidad ilimitada. Implementa encolado, prioridad y backoff; monitoriza 429 y métricas de latencia.

    Cuándo delegar y cuándo no

    Delegar a Managed Agents tiene sentido cuando ahorrarás semanas de ingeniería en infra (sandboxes, orquestación, secretos) y necesitas fiabilidad en tareas asíncronas prolongadas. No lo uses si tu negocio requiere retención forense total o control absoluto sobre ejecución (por ejemplo, datos regulados que no pueden salir de tu red). En esos casos, preferir un cluster interno con un harness local y un modelo autohospedado —aunque más coste inicial— puede ser la opción correcta.

    Conclusión operativa

    Anthropic lanzó Managed Agents para abstraer la parte más aburrida y frágil de la ejecución agéntica: estado, aislamiento y herramientas. La plataforma acelera adopción, pero no elimina la responsabilidad del equipo: gobernanza, observabilidad y políticas de datos siguen siendo necesarias. Integra la Rate Limits API, usa un orquestador (n8n) para desacoplar, y define reglas rígidas de handoff, checkpoints y retención para evitar que un avance operativo se convierta en una deuda técnica costosa.

    Si quieres explorar patrones de integración y pruebas alrededor de orquestación y agentes, consulta Dominicode Labs para recursos y ejemplos prácticos que complementan este enfoque.

    FAQ

    Respuesta:

    Managed Agents son agentes de largo plazo gestionados por la plataforma de Anthropic; la funcionalidad fue lanzada el 25 de abril de 2026.

    Respuesta:

    Resuelven persistencia de estado entre pasos, aislamiento y ejecución segura (sandboxes), harnesses para ejecutar herramientas y gestión segura de credenciales, reduciendo la necesidad de infraestructura propia para agentes asíncronos largos.

    Respuesta:

    La Rate Limits API permite consultar los límites de tokens y uso organizacional de forma programática, lo que te deja decidir antes de encolar o lanzar agentes y aplicar encolado/prioridad/backoff cuando la capacidad es limitada.

    Respuesta:

    n8n sirve como orquestador desacoplado: recibe triggers, consulta Rate Limits API, lanza Managed Agents guardando session_id y luego procesa resultados con webhooks o polling, evitando mantener hilos abiertos y facilitando escalado horizontal.

    Respuesta:

    Riesgos clave: vendor lock-in y requisitos de compliance, menor observabilidad forense dentro del sandbox, posible fuga de datos temporales y dependencia en límites de tasa; se requieren políticas, checkpoints y exportación controlada de artefactos.

    Respuesta:

    No delegues si tu negocio exige retención forense total o control absoluto sobre la ejecución y datos (por ejemplo, datos regulados que no pueden salir de tu red). En esos casos, considera un cluster interno con harness local y modelo autohospedado.

  • Cómo orquestar subagentes de IA para un desarrollo eficaz

    Cómo orquestar subagentes de IA para un desarrollo eficaz

    Subagentes como equipo de desarrollo: orquestación con Claude Code

    Tiempo estimado de lectura: 4 min

    Ideas clave

    • Plan, delega, commit, valida: estructura que convierte a un asistente en un equipo con coordinador y subagentes.
    • Riesgos mitigados: degradación de contexto, decisiones implícitas y falta de trazabilidad.
    • Regla de commit inquebrantable: cada subagente debe hacer un commit atómico antes de avanzar.
    • DAG y paralelismo: lanzar en paralelo solo nodos sin dependencias y revisar diffs antes de desbloquear dependientes.
    • Requisitos para producción: CLAUDE.md, pipelines rápidos, política de revisión y auditoría de commits.

    Introducción

    Subagentes como equipo de desarrollo: orquestación con Claude Code es el patrón que convierte a un asistente de IA en un equipo real: un coordinador que descompone trabajo y subagentes que ejecutan tareas atómicas, hacen commits y devuelven resultados auditables. Si vas a automatizar entregas complejas, empieza por esta estructura: plan, delega, commit, valida.

    Resumen rápido (lectores con prisa)

    Patrón que transforma un asistente en un equipo con un coordinador que define la spec y un conjunto de subagentes que implementan tareas atómicas. Útil cuando puedes separar trabajo por interfaces claras y hay necesidad de trazabilidad y rollback atómico. Requiere commits por subagente, pipelines rápidos y un CLAUDE.md como referencia.

    Subagentes como equipo de desarrollo: por qué importa y cómo cambia el riesgo

    La diferencia entre generar código rápido y entregar cambios sostenibles no está en la velocidad de la IA, sino en cómo gestionas el contexto y las decisiones. Un agente que trabaja solo acumula contexto y toma decisiones implícitas; eso produce deuda técnica que emerge en integración. Orquestar subagentes reduce tres riesgos claves:

    • Degradación de contexto: cada subagente opera con una ventana limitada y relevante.
    • Propagación de decisiones implícitas: el coordinador valida outputs antes de avanzar.
    • Falta de trazabilidad: cada subagente hace un commit atómico, facilitando revertir y revisar.

    Documentación útil: Claude Code overview y Claude (Anthropic)

    Cómo funciona el flujo: roles, primitives y regla del commit

    1. Agente principal (coordinador)

    – Define la spec global y el DAG de dependencias.
    – Descompone el trabajo en tareas atómicas.
    – Lanza subagentes con la primitiva task.

    2. Subagentes (desarrolladores)

    – Reciben una tarea acotada: archivos relevantes, firmas esperadas, criterios de aceptación.
    – Implementan cambios, añaden tests y hacen un commit.
    – Devuelven al coordinador el diff, logs de test y un resumen de riesgos pendientes.

    3. Regla inquebrantable: cada subagente hace un commit antes de que el coordinador asigne la siguiente tarea dependiente

    Beneficios: aislamiento de errores, validación incremental, trazabilidad en Git.

    Ejemplo de secuencia para migración

    • Task 1: migrar modelo de pagos → commit “payments: migrate model v2”
    • Task 2: actualizar servicio de facturación (depende de Task 1) → commit “billing: use payments v2”
    • Task 3: actualizar tests e2e (paralelo) → commit “tests: update e2e for payments v2”

    Reglas operativas: cómo escribir tareas para subagentes

    Una mala especificación produce malos resultados, aunque el subagente sea capaz. Sigue estas reglas:

    • Objetivo claro en 1–2 líneas.
    • Alcance: archivos y módulos permitidos.
    • Contratos: firmas, DTOs, errores esperados.
    • Criterios de aceptación automatizables (tests unitarios o comandos de CI).
    • Comando de commit esperado y mensaje sugerido.
    • Limitar tiempo/recursos si procede.

    Plantilla mínima para una tarea

    • Título: actualizar UserService para usar AuthV2
    • Archivos permitidos: src/services/userService.ts, src/types/auth.ts
    • Contrato: getUser(id): UserDto
    • Tests: añadir unit tests para getUser con mocks de AuthV2
    • Commit: “user: migrate to AuthV2 — tests added”

    Integración, paralelismo y control de dependencias

    – Construye un DAG (grafo acíclico) de tareas. Lanza en paralelo solo nodos sin dependencias entre sí.
    – Siempre inspecciona el diff tras cada commit. El coordinador puede ejecutar hooks o pipelines ligeros antes de desbloquear tareas dependientes.
    – Si una tarea paralela falla, su rollback es local: revertir su commit o patch específico, sin tocar el trabajo válido previo.

    Requisitos previos para producción

    • CLAUDE.md actualizado en la raíz: stack, patrones prohibidos, comandos CI. Los subagentes la leerán al iniciar. (Ver ejemplo de uso de CLAUDE.md en prácticas de equipo).
    • Pipelines de CI rápidos: que verifiquen commits intermedios (lint, tests unitarios).
    • Política de revisión: define qué commits requieren revisión humana inmediata (p. ej., cambios en auth, DB).
    • Mecanismo de auditoría: etiquetas de commit que identifiquen subagente y tarea.

    Cuándo aplicar este patrón (y cuándo no)

    Úsalo cuando

    • Puedes descomponer trabajo en módulos con interfaces claras.
    • Hay paralelismo real entre módulos.
    • Necesitas trazabilidad y rollback atómico.

    No lo uses cuando

    • La tarea es totalmente secuencial o indivisible.
    • Las interfaces son ambiguas o el proyecto carece de convenciones documentadas.
    • El overhead de coordinación supera el beneficio (scripts pequeños, fixes triviales).

    Métricas que importan para medir éxito

    • Tiempo medio desde task creada hasta merge sin rework.
    • Número de reverts por milestone.
    • % de tasks que pasan CI en primer commit.
    • Latencia de integración (tiempo entre commit de dependencia y comienzo de tareas dependientes).

    Un aumento en la proporción de merges sin rework y una caída en los reverts indican que la orquestación está funcionando.

    Limitaciones honestas

    El patrón amplifica capacidad, no sustituye criterio. Si el coordinador delega mal —tareas vagas, contratos inconsistentes— obtendrás implementaciones rápidas y equivocadas. La diferencia está en quién escribe las specs: la IA ejecuta, el humano decide.

    Dominicode Labs

    Para seguir explorando patrones de orquestación y automatización aplicados a equipos mixtos humano+IA, consulta Dominicode Labs. Es una continuación lógica para pruebas de concepto y plantillas de CLAUDE.md en equipos de ingeniería.

    FAQ

    Es una estructura donde un coordinador descompone trabajo en tareas atómicas y subagentes ejecutan esas tareas, hacen commits atómicos y devuelven diffs, logs y riesgos pendientes.

    Cuando puedes descomponer trabajo en módulos con interfaces claras, hay paralelismo real y necesitas trazabilidad y capacidad de rollback atómico.

    Objetivo en 1–2 líneas, alcance (archivos permitidos), contratos (firmas/DTOs), criterios de aceptación automatizables, comando de commit esperado y límites de tiempo/recursos si procede.

    Se recomiendan pipelines rápidos que verifiquen commits intermedios con lint y tests unitarios. No se prescribe una herramienta específica en este texto.

    El rollback es local: revertir el commit o aplicar un patch específico de la tarea fallida, sin tocar el trabajo válido previo.

    Debe incluir stack, patrones prohibidos y comandos CI. Los subagentes la leerán al iniciar y sirve como referencia de equipo.

    Aumentos en merges sin rework, caída en reverts, tiempo medio hasta merge menor, alto % de tasks que pasan CI en primer commit y baja latencia de integración.

  • Cómo aplicar la regla del 60% en la gestión de contexto para LLMs

    Cómo aplicar la regla del 60% en la gestión de contexto para LLMs

    Gestión de contexto: la regla del 60% para sesiones en Claude Code

    Tiempo estimado de lectura: 5 min

    • Regla operativa: nunca dejes que una sesión consuma más del 60% de la ventana de contexto sin persistir el estado y limpiar la memoria.
    • Patrón de trabajo: dividir tareas en Research → Plan → Implement → Validate, con artefactos en disco y limpieza de contexto entre fases.
    • Artefactos clave: /CLAUDE.md, /RESEARCH.md, /PLAN.md, /TASK_STATE.md, /VALIDATION_REPORT.md y commits atómicos por módulo.
    • Señales y métricas: observar contradicciones, repeticiones de contexto y fallos por “olvidos”; medir % de tareas con rework y tiempo de retoma.

    Introducción

    La frase “gestión de contexto: la regla del 60%” no es un eslogan. Es la regla operativa que evita que sesiones largas con agentes como Claude Code produzcan código coherente hoy y deuda técnica mañana. Si trabajas con LLMs en ingeniería, aplica esto desde el primer día: nunca dejes que una sesión consuma más del 60% de la ventana de contexto sin persistir el estado y limpiar la memoria.

    Resumen rápido (lectores con prisa)

    La regla del 60% limita cuánto de la ventana de contexto puede usar una sesión antes de persistir el estado. Úsala para fragmentar trabajo en sesiones controladas y guardar artefactos versionados (archivos en el repo). Aplica especialmente con agentes que leen/escriben repositorios como Claude Code.

    Qué significa “Gestión de contexto: la regla del 60%” y por qué importa

    Los modelos de lenguaje tienen una ventana finita de tokens. Cuando esa ventana se aproxima a su límite —y en la práctica cuando supera el 60%— el modelo comienza a priorizar lo más reciente. Eso no produce errores ruidosos: produce decisiones de diseño que olvidan criterios definidos al inicio, bugs detectados temprano y validaciones que ya no se tienen en cuenta.

    La regla del 60% obliga a fragmentar el trabajo en sesiones controladas y a externalizar el estado en artefactos versionados (archivos en el repo). Con Claude Code esto es práctico y repetible porque el agente puede leer/escribir el repositorio: https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview y https://www.anthropic.com/claude.

    El patrón operativo: 4 fases limpias por sesión

    Divide cualquier tarea compleja en cuatro fases: Research → Plan → Implement → Validate. Cada fase debe terminar con un artefacto en disco y una limpieza explícita del contexto antes de pasar a la siguiente.

    1) Research — auditoría

    – Objetivo: mapear dependencias, puntos de dolor y deuda técnica sin cambiar nada.

    – Salida: RESEARCH.md con módulos auditados, preguntas abiertas y riesgos priorizados.

    – Acción: cerrar sesión. No cargar más archivos que los estrictamente necesarios.

    2) Plan — diseño acotado

    – Objetivo: con RESEARCH.md + CLAUDE.md (contrato del proyecto) definir módulos, orden y criterios de aceptación.

    – Salida: PLAN.md con tareas atómicas y criterios verificables.

    – Acción: validar el plan con un humano; cerrar sesión.

    3) Implement — sesiones por módulo

    – Objetivo: una sesión por módulo. Cargar solo PLAN.md, CLAUDE.md y archivos del módulo.

    – Salida por módulo: commit atómico + actualización de TASK_STATE.md (estado por módulo) y tests unitarios.

    – Acción: limpiar contexto entre módulos (reiniciar sesión o instanciar subagente nuevo).

    4) Validate — verificación objetiva

    – Objetivo: sesión en blanco que lea PLAN.md y ejecute validaciones (tests unitarios, integración, contratos).

    – Salida: VALIDATION_REPORT.md con pass/fail y pasos de corrección.

    – Acción: abrir PR / merge si pasa; en caso contrario, agregar tareas correctivas al plan y repetir ciclo.

    Ejemplo práctico (prompt y artefactos)

    Estructura de archivos mínima:

    /CLAUDE.md
/RESEARCH.md
/PLAN.md
/TASK_STATE.md
/VALIDATION_REPORT.md
/tasks/auth-migration.md

    Prompt de recuperación inicial (Research → Plan):

    Lee /RESEARCH.md y /CLAUDE.md. Propón un PLAN.md que divida la migración de Auth en módulos atómicos,
cada uno con criterios de aceptación y tests mínimos. No implementes código.
Guarda PLAN.md y termina la sesión.

    Prompt para Implement (módulo user-service):

    Lee PLAN.md y CLAUDE.md. Trabaja únicamente en src/services/user-service.* según el criterio de la tarea "UserService".
Agrega tests unitarios que validen los criterios. Actualiza TASK_STATE.md antes de hacer commit.
No toques otros módulos.

    Regla inquebrantable: actualizar TASK_STATE.md y hacer commit antes de terminar la sesión.

    Señales de que estás cruzando el 60% (y qué hacer)

    – Necesitas repetir contextos largos en prompts para que el agente recuerde una regla inicial.

    – El agente empieza a contradecir decisiones anteriores sin justificación.

    – Validaciones fallan por “olvidos” de requisitos que estaban en el RESEARCH.md.

    Si ves cualquiera de estas señales: persiste el estado en disco, cierra la sesión y reinicia con el artefacto correspondiente.

    Ventajas prácticas y métricas que importan

    Aplicar la regla del 60% reduce ruido y mejora trazabilidad:

    • Menos reverts por decisiones olvidadas.
    • Mayor porcentaje de tasks que pasan CI en el primer commit.
    • Tiempo de retoma por sesión < 5 minutos (leer artefacto) en vez de re-auditar todo.

    Mide: % de tareas con rework, número de bugs registrados en TASK_STATE.md, tiempo desde apertura de sesión hasta reanudación efectiva.

    Límites y advertencias

    Esto no sustituye especificaciones claras ni revisiones humanas. Si la planifica es ambigua, la IA persistirá ambigüedades más rápido. El patrón reduce riesgos operativos, no el riesgo conceptual de malas decisiones de diseño. Además, no necesitas este overhead para fixes rápidos o scripts aislados: aplica la regla cuando el alcance y la duración lo justifiquen.

    La regla del 60% es una disciplina: no es bonita, pero evita que la IA genere parches brillantes que fallan en integración. Si automatizas en serio, diseña tu flujo con RESEARCH.md, PLAN.md, TASK_STATE.md y VALIDATION_REPORT.md, obliga a commits atómicos y reinicia sesiones a tiempo. Con eso, la memoria del modelo deja de ser un talón de Aquiles y se convierte en parte auditable de tu pipeline.

    Continuación práctica y recursos: Dominicode Labs

    FAQ

    ¿Qué es la regla del 60%?

    Es una regla operativa que limita el uso de la ventana de contexto: nunca permitir que una sesión consuma más del 60% sin persistir estado y limpiar la memoria.

    ¿Cuándo debo aplicarla?

    Aplica siempre en sesiones largas con LLMs y agentes que manejan proyectos no triviales; evita su uso solo en fixes rápidos o scripts aislados.

    ¿Por qué importa con Claude Code?

    Porque Claude Code puede leer y escribir el repositorio; fragmentar el trabajo y persistir artefactos hace el flujo práctico y repetible.

    ¿Cuáles son los artefactos mínimos?

    /CLAUDE.md, /RESEARCH.md, /PLAN.md, /TASK_STATE.md, /VALIDATION_REPORT.md y archivos de tareas (por ejemplo /tasks/auth-migration.md).

    ¿Cómo se mide el éxito?

    Métricas: % de tareas con rework, número de bugs registrados en TASK_STATE.md y tiempo desde apertura de sesión hasta reanudación efectiva.

    ¿Qué hacer si detecto que crucé el 60%?

    Persistir el estado en disco, cerrar la sesión y reiniciar con el artefacto correspondiente.

  • Automatiza tareas avanzadas con Claude Code sin programar

    Automatiza tareas avanzadas con Claude Code sin programar

    Claude Code no es solo para devs: 3 cosas que puedes hacer sin escribir una línea de código

    Tiempo estimado de lectura: 4 min

    • Claude (modelo) permite resolver problemas técnicos sin instalar herramientas.
    • Puedes orquestar flujos en n8n, transformar datos y generar documentación técnica sin escribir JS.
    • La diferencia clave: la CLI modifica repos locales; el modelo responde a instrucciones conceptuales.

    Introducción

    Claude Code no es solo para devs: 3 cosas que puedes hacer sin escribir una línea de código. Si leíste “CLI” y cerraste la pestaña, vuelve. La herramienta CLI existe y exige terminal, Git y permisos. Pero el ecosistema Claude —el modelo razonador accesible vía web y API— te permite resolver problemas técnicos reales sin teclear una sola línea de código. Aquí explico cómo, con ejemplos y enlaces para que lo pruebes.

    Resumen rápido (lectores con prisa)

    Qué es: Claude Code (CLI) es una herramienta para desarrolladores; Claude como modelo es un motor de razonamiento accesible vía web y API.

    Cuándo usarlo: Usa la CLI cuando necesites que un agente toque tu repo y ejecute tests; usa el modelo web/API para diseño de flujos, limpieza de datos, diagramas o specs.

    Por qué importa: Si sabes describir un problema técnico con precisión, puedes extraer valor sin instalar nada.

    Cómo funciona: El CLI actúa sobre repos locales; el modelo responde a instrucciones bien formuladas y genera artefactos accionables.

    1) Orquestar automatizaciones avanzadas en n8n — sin tocar JS

    Problema común

    Un webhook llega con JSON irregular y el flujo se rompe. Solución habitual: pedir a un dev un snippet de JavaScript. Alternativa real: usar Claude.

    Qué pedirle al modelo

    • “Este es el payload (pega ejemplo). Necesito extraer user.id, normalizar created_at a ISO y crear un campo active (true/false) según status. Dame el fragmento listo para pegar en un Code Node de n8n.”

    Qué obtendrás

    • Código listo para pegar que itera arrays, maneja nulos y transforma fechas.
    • Instrucciones de configuración del nodo HTTP (headers, auth).
    • Un plan de manejo de errores: retry con backoff exponencial, alertas en caso de 500/429.

    Por qué importa

    Reduces la fricción de integración y acortas el tiempo desde idea a flujo en producción. Documentación n8n: Documentación n8n

    2) Transformar datos y generar consultas SQL sin abrir una hoja de cálculo

    Caso real

    Recibes CSV/XML legacy y necesitas convertirlo a un esquema usable o sacar métricas complejas.

    Lo que puedes pedir

    • “Toma estas 50 filas (pega muestra). Genera un JSON Schema y un script de transformación (pseudocódigo) que normalice fechas, campos anidados y valores por defecto.”
    • “Explícame la regex para extraer IDs que empiezan por TX- seguido de 8 dígitos.” (Ejemplo: TX-\d{8})

    Qué devuelve Claude

    • JSON Schema validado y reglas de transformación.
    • Consultas SQL optimizadas para tu motor (Postgres, BigQuery), con JOINs, window functions y filtros temporales.

    Por qué importa: eliminas horas de limpieza manual y reduces errores humanos en pipelines de datos. Si necesitas precisión, adjunta la estructura de tablas y el motor SQL para que la query sea ajustada.

    3) Generar documentación técnica y diagramas antes de la implementación

    Usos prácticos

    • Describe el flujo de registro y pide código Mermaid.js para un diagrama de secuencia; pega el resultado en Notion o GitHub y obtén el gráfico inmediato. (Mermaid.js (diagramas))
    • Describe un endpoint (inputs, outputs, errores) y pide un contrato OpenAPI/Swagger listo para revisión. (OpenAPI Spec)
    • Pide un mapa de infraestructura cloud (colas, bases, funciones) con puntos de fallo y recomendaciones de mitigación.

    Qué ganas

    Conversaciones técnicas más cortas, menos malentendidos y decisiones con criterios concretos en lugar de intuición.

    Cómo decidir: CLI o modelo web/API

    Usa Claude Code (CLI) cuando quieras que un agente toque tu repo, ejecute tests o refactorice código localmente. Requiere desenvoltura con terminal y control de versiones.

    Usa Claude Web/API o integraciones (p. ej. n8n) cuando necesites diseño de flujos, limpieza de datos, diagramas o specs. Necesitas claridad conceptual, no sintaxis.

    La ventaja real no es escribir código: es estructurar problemas. Si puedes describir el estado actual, los invariantes y el resultado esperado, Claude lo transforma en artefactos técnicos accionables.

    Dominicode Labs

    Si quieres explorar integración práctica de automatizaciones y artefactos generados por IA en procesos de ingeniería, considera profundizar con recursos adicionales en Dominicode Labs. Es una continuación lógica para llevar los fragmentos y especificaciones que genera Claude hacia pruebas reproducibles y gobernanza de despliegue.

    FAQ

    ¿Necesito instalar algo para usar Claude como modelo?

    No. Claude como modelo está accesible vía web y API, por lo que puedes usarlo sin instalar la CLI ni herramientas locales.

    ¿Cuándo debo preferir la CLI de Claude?

    Prefiérela cuando necesites que un agente modifique repositorios locales, ejecute tests o interactúe con tu entorno de desarrollo. Requiere terminal y control de versiones.

    ¿Puedo usar Claude para generar código listo para n8n?

    Sí. Puedes pedir fragmentos listos para pegar en Code Nodes, junto con configuración HTTP y planes de manejo de errores.

    ¿Claude puede generar consultas SQL optimizadas?

    Sí. Claude devuelve queries ajustadas por motor (Postgres, BigQuery) incluyendo JOINs, window functions y filtros temporales si proporcionas la estructura de tablas.

    ¿Es seguro usar el modelo para datos sensibles?

    El artículo no añade recomendaciones de seguridad concretas, pero sugiere integrar artefactos en procesos de gobernanza y despliegue para que la automatización sea segura y mantenible.

    ¿Dónde encuentro documentación oficial de Claude y herramientas relacionadas?

    Referencias citables en el artículo: Anthropic – Claude Code overview, Claude (Anthropic), n8n (automatización), Mermaid.js (diagramas) y OpenAPI Spec.

  • Cómo construir un SaaS con IA resiliente y escalable

    Cómo construir un SaaS con IA resiliente y escalable

    ¿Quieres un SaaS con IA que sobreviva seis meses en producción o solo un demo viral de 48 horas?

    Tiempo estimado de lectura: 5 min

    • Ideas clave:
    • La diferencia entre un demo viral y un SaaS real no es la idea ni el modelo, sino la arquitectura.
    • Diseña asumiendo que la IA falla: latencia, rate limits y respuestas inconsistentes son inevitables.
    • Separación clara de responsabilidades (frontend, backend, orquestador, workers, persistencia) y asincronía por defecto salvan proyectos.
    • Contratos estrictos (JSON + validación) y observabilidad desde el inicio son imprescindibles para producción.

    ¿Quieres un SaaS con IA que sobreviva seis meses en producción o solo un demo viral de 48 horas?

    La diferencia no es la idea ni el modelo que uses. Es la arquitectura. Y sí: la IA te hace sentir productivo en minutos. También te hace pagar por la reescritura en semanas.

    Voy al grano. Si tu apuesta es “poner un prompt en un endpoint y ver qué pasa”, estás construyendo un wrapper, no un producto. Un wrapper se rompe cuando el proveedor cambia precios, cuando la latencia sube o cuando un caso borde que nunca imaginaste llega a producción. Un SaaS real convierte la IA en un componente confiable dentro de un sistema diseñado para fallar sin morir.

    Aquí tienes un plan práctico y sin postureo para construir un SaaS real con IA sin improvisar.

    Resumen rápido (lectores con prisa)

    Qué es: Buenas prácticas de arquitectura para convertir modelos de IA en componentes fiables dentro de un SaaS.

    Cuándo usarlo: Desde el MVP que pretende escalar hasta productos en producción con múltiples tenants y requisitos de coste y seguridad.

    Por qué importa: Evita que un prototipo se convierta en deuda técnica cara y en incidentes de producción.

    Cómo funciona, en pocas palabras: Separación de responsabilidades, asincronía por defecto, contratos estrictos (JSON + validación), observabilidad y pruebas que incluyan fallos de IA.

    Primera regla: asume que la IA falla… constantemente

    No es pesimismo. Es ingeniería. Latencia, rate limits, respuestas inconsistentes, cambios en la API: todo será parte de la vida diaria. Diseña para eso.

    Qué separar desde el minuto uno

    No mezcles interfaz, orquestación y persistencia. Divide responsabilidades claras:

    • Frontend: experiencia, manejo de latencia, feedback al usuario.
    • Backend de negocio: validaciones, reglas, monetización, seguridad.
    • Orquestador de IA: flujos, reintentos, parsing y almacenamiento de resultados.
    • Workers: procesamiento asíncrono, reintentos idempotentes.
    • Persistence: PostgreSQL (con pgvector), logs, metadatos.

    Si todo está en el mismo contenedor, el sistema se romperá bonito y rápido.

    Patrón que salva proyectos: asincronía por defecto

    Olvida la llamada síncrona “cliente→server→LLM→cliente”. Es la receta del timeout.

    • Client envía tarea → server registra job (estado: pending) → responde 202.
    • Worker (o n8n) toma job, hace llamadas a LLMs, actualiza estado.
    • Notifica por WebSocket/SSE o el cliente hace polling leve.

    Resultado: interfaz reactiva, control de reintentos y mejor experiencia cuando la IA tarda.

    Orquestación: usa n8n, no code spaghetti

    Sí, puedes encadenar prompts en código. También puedes terminar con funciones de mil líneas. Usa un orquestador (n8n o equivalente) para:

    • Encadenar pasos (call LLM → transformación → persistencia).
    • Ejecutar retries con backoff.
    • Manejar errores y circuit breakers visualmente.
    • Mantener logs de cada ejecución.

    El día que la API de IA se ponga inestable, agradecerás no tener que rastrear todo en un repo lleno de lambdas.

    Contratos > Prompts

    No pidas “texto bonito”. Pide JSON estricto. No hay excusas.

    • Define interfaces TypeScript o OpenAPI.
    • Obliga a la IA a devolver un objeto con esquema verificado.
    • Usa Zod o codegen para validar la respuesta y fallar rápido si hay desviaciones.

    Esto convierte a la IA en un microservicio con contrato, no en una caja negra caprichosa.

    RAG = potencia + responsabilidad

    Si vas a permitir que usuarios suban documentos para chatear con ellos, aplica aislamiento absoluto:

    • Cada vector con tenant_id.
    • Filtrado por tenant_id a nivel de consulta (antes de enviar contexto al LLM).
    • Escapa la tentación de “mezclar para mejores embeddings”. Eso rompe privacidad y compliance.

    Si trabajas con datos sensibles, aíslalo, audítalo y documenta quién lo puede ver.

    Costos y medición: que no te coja desprevenido

    Un SaaS con IA vive o muere por el coste por petición.

    • Metering por job: tokens consumidos, llamadas a terceros, tiempo de ejecución.
    • Alerts por coste semanal y por job atípico.
    • Fallbacks: versiones más baratas del modelo para tareas no críticas.
    • Caching inteligente: respuestas deterministas pueden cachearse.

    No hay nada más caro que ejecutar un modelo grande para una operación que podía resolverse con reglas.

    Idempotencia y seguridad en flujos asíncronos

    Reintentos inevitables → diseñalos bien:

    • Usa IDs de correlación.
    • Diseña workers idempotentes: reintentar no debe duplicar registros ni cobrar dos veces.
    • Aplica locks por job cuando haga falta.

    Observabilidad: telemetría desde el minuto cero

    Si no puedes medir, no puedes mejorar. Instrumenta todo:

    • Traces distribuidos (OpenTelemetry).
    • Métricas por endpoint, por modelo y por tenant.
    • Logs estructurados con contexto de job.
    • Dashboards y alertas (latencia, error rates, coste por tenant).

    Tests y contratos automáticos

    Haz que cada contrato tenga tests que fallen en CI si la IA devuelve algo fuera de esquema.

    • Mockea respuestas de LLM (positivas y negativas).
    • Tests de integración que simulen timeouts y retries.
    • Tests de seguridad: inyección de prompt, accesos cruzados entre tenants.

    Checklist MVP vs. Producción

    MVP mínimo viable (rápido, medible):

    • Job queue + worker básico.
    • Interfaces TypeScript + validación Zod.
    • Persistencia en PostgreSQL + pgvector.
    • Orquestación simple (n8n optional).
    • Métricas básicas y alertas de coste.

    Preparación para producción:

    • Observabilidad completa (traces, metrics, logs).
    • Políticas de multi-tenancy estrictas.
    • Circuit breakers, retries con backoff y dead-letter queues.
    • Billing y metering por tokens/calls.
    • Testing de resiliencia y chaos experiments.

    Plantilla rápida de SPEC.md que debes tener ya

    Pon esto en la raíz del repo. Si no lo haces ahora, lo pagarás después.

    • Objetivo del módulo (1 frase).
    • Stack aprobado y versiones.
    • Reglas innegociables (ej.: “No exponer secretos en frontend”, “Todo job idempotente”).
    • Contratos principales: Endpoints + interfaces TS.
    • Criterios de aceptación (tests que deben pasar).
    • Responsable técnico y proceso de cambios.

    Prompt maestro que funciona (ejemplo)

    Contexto + restricciones + output estricto:

    <contexto_negocio>Resumen en 3 frases</contexto_negocio>
    <stack>Next.js, Node 20, Postgres + pgvector</stack>
    <restricciones>No usar microservicios, respuesta JSON valida Zod</restricciones>
    <output_esperado>JSON { result: string, score: number, metadata: { sourceId: string } }</output_esperado>

    No es glamour. Es ingeniería que evita tickets nocturnos.

    El nuevo rol del equipo: menos héroes, más guardias

    Con IA el que más aporta no es el que teclea más rápido. Es el que fija límites, define contratos y establece el ritmo de iteración. El senior deja de ser “code god” para ser “arquitecto de fronteras”. Eso es lo que realmente escala.

    CTA corto y útil

    Si quieres, te doy ahora:

    • Una SPEC.md lista para pegar en tu repo.
    • Un prompt maestro para Claude + ejemplos de Zod.
    • Un .n8n workflow básico para encadenar llamadas a modelos con retries.

    Respóndeme con “Plantilla SaaS” y te lo envío. Hazlo ahora: crea el SPEC.md en la raíz antes del próximo commit generado por IA.

    Dominicode Labs

    Si quieres continuidad práctica y recursos relacionados con orquestación, workflows y automatización para productos de IA, visita Dominicode Labs. Es una continuación lógica para poner en práctica los enfoques descritos en este artículo.

    FAQ

    ¿Por qué no debería hacer llamadas síncronas al LLM desde el cliente?

    Porque los timeouts, latencias y rate limits hacen que la experiencia sea impredecible. La arquitectura asíncrona (jobs + workers) permite reintentos, control de costes y una interfaz más robusta.

    ¿Qué es un orquestador y por qué usar n8n?

    Un orquestador encadena pasos: llamadas a LLM, transformaciones, persistencia y retries. n8n ofrece visualización de flujos, gestión de errores y menos código espagueti en repositorios complejos.

    ¿Cómo obligo a la IA a devolver JSON válido?

    Define un contrato (TypeScript/OpenAPI) y valida con Zod u otro validador. Rechaza respuestas que no cumplan el esquema y trata esos casos en tus retries o dead-letter queues.

    ¿Qué medidas tomar para multi-tenancy en RAG?

    Aislamiento absoluto: cada vector con tenant_id, filtrado por tenant_id antes de consultas y auditoría de accesos. No mezclar datos entre tenants.

    ¿Qué métricas debo medir desde el primer día?

    Tokens consumidos por job, latencia por endpoint, error rate por modelo y coste por tenant. También traces distribuidos y logs estructurados por job.

    ¿Qué debe incluir mi SPEC.md mínimo?

    Objetivo del módulo, stack y versiones, reglas innegociables, contratos principales (endpoints + interfaces TS), criterios de aceptación y responsable técnico.

  • Cómo gestionar la gobernanza de IA para evitar la deuda técnica

    Cómo gestionar la gobernanza de IA para evitar la deuda técnica

    ¿Te vas a mirar el correo mientras la IA reescribe tu código… y luego vuelves a casa de locos?

    Tiempo estimado de lectura: 6 min

    • La delegación ciega a agentes que ejecutan cambios produce deuda técnica documentada fuera del repo.
    • La solución práctica es gobernar decisiones: exigir artefactos versionables con autoría y timestamp.
    • Plum: herramienta que intercepta commits, extrae decisiones y fuerza aprobaciones antes del commit.

    Poca gente lo dice en voz alta: dejar que un agente “lo corra y volvemos” es exactamente la forma más rápida de cavar una trampa de deuda técnica. Sales cinco minutos. Vuelves y el LLM te dejó un “decision” que grita: eso es una locura. No lo hagas.

    Esto no es un problema de postureo. Es práctico. Es urgente.

    Resumen rápido (lectores con prisa)

    Un agente que ejecuta cambios sin gobernanza introduce decisiones sin autoría en el repo. Necesitas un mecanismo externo que intercepte commits, extraiga decisiones y requiera aprobación, convirtiéndolas en artefactos versionables y auditable—eso reduce deuda técnica y mejora trazabilidad.

    1) Lo que pasa cuando “lo dejamos correr”

    Un agente se queda ejecutando tareas. Encuentra ambigüedades. Encuentra dependencias rotas. Para avanzar, toma atajos. Guarda esos atajos en su chat. Tú haces commit y pum: el código llega a la rama, los tests pasan y la intención se evapora.

    Resultado: hacks documentados en conversaciones privadas, no en el repo. Atajos que nadie planeó. Deuda técnica que aparece al lado del despliegue.

    2) Por qué esto es peor que un bug cualquiera

    Un bug puedes rastrearlo. Una decisión sin autoría es un agujero negro. Nadie recuerda por qué cambó la fórmula de impuestos a las 3 AM. Nadie puede auditar la razón. Y cuando el problema explota en producción, el “blame” no sirve: no hay decisión firmada, solo un commit huérfano y un chat que nadie va a revisar.

    3) La solución no es prohibir la IA. Es gobernarla.

    No más fe ciega. No más prompts que funcionan en beta pero rompen en prod. Necesitamos que cada decisión que importe deje rastro formal. Que sea un artefacto. Que sea buscable. Que tenga autoría y timestamp. Que puedas preguntar: “¿por qué esto existe?” y obtener una respuesta concreta.

    4) Plum: la plomada que obliga a decidir en serio

    Imagina una herramienta que corre al lado de Git y te fuerza a responder. No genera código por ti. No es una skill adentro del LLM. Es un checkpoint.

    Básicos del flujo

    • plum init → crea .plum y .plumignore, añade hooks.
    • Cambias código con un agente.
    • Intentas git commit. Plum compara diffs y scans de traces.
    • Si hay decisiones, el commit falla hasta que apruebes, edites o rechaces.
    • Si apruebas, plum actualiza la spec (Markdown) y agrega una entrada .jsonl con: pregunta, decisión, autor, branch y timestamps.

    ¿La ventaja? Cuando vuelvas del mail, no te encuentras sorpresas sin contexto. Te encuentras una decisión con nombre y apellido.

    5) No puede ser una “skill” del agente —y punto

    Una skill dentro del LLM es una sugerencia. Las sugerencias se ignoran. La gobernanza debe estar fuera. Tiene que poder bloquear commits, integrarse en CI y ser determinista. Si es opcional, no sirve.

    6) ¿Qué hay dentro del .jsonl y por qué importa?

    Ese archivo no es solo logs. Es la historia de la intención del proyecto. Cada entrada contiene:

    • El dilema técnico.
    • La decisión tomada.
    • Quién aprobó.
    • Si fue propuesto por el LLM o por un humano.
    • Vínculo a la diff/PR.
    • Marcas de tiempo.

    Eso convierte la intención en dato: indexable, auditable, útil para auditorías y forensics.

    7) Problemas reales —sin romanticismos

    • Deduping de decisiones es fuzzy. Detectar “la misma decisión” entre conversaciones distintas no es trivial. Requiere heurísticas y ajuste repo-específico.
    • Rollbacks automáticos: si rechazas la decisión, idealmente el sistema revierte el cambio o pide al agente rehacerlo. Hoy eso es work-in-progress.
    • Ruido: si cada hotfix dispara cinco decisiones, la herramienta es odiada. Necesitas umbrales configurables.
    • Specs crecen como malas hierbas. Hay que shardearlas en requerimientos atómicos, y sí: un LLM puede ayudar a fragmentarlas, pero diseña el flujo.

    8) Umbrales: sensibilidad y contexto

    La clave práctica es permitir tolerancias dinámicas:

    • Modo strict: todo pasa por aprobación (fintech, salud).
    • Modo sane: decisiones no críticas se agrupan y se presentan en lote.
    • Modo fast-lane: “dangerously approve all” para prototipos.
    • Filtros por carpeta: core = strict; ui-experiments = lenient.

    Hazlo configurable por módulo y por rama. No es capricho: es supervivencia.

    9) Integración con DSPy y el determinismo

    Cuando puedas validar con código, hazlo. Usa parsers, tests y reglas. Donde necesites LLMs (p.ej. parse semántico del spec), estructura las llamadas con DSPy: inputs y outputs tipados. Menos alucinaciones, más predictibilidad. Enrutamiento por velocidad: dedupe puede ir a modelos OSS rápidos; parsing pesado a modelos más potentes.

    10) ¿Qué debería cambiar en GitHub?

    Markdown no es solo texto. Debe ser ciudadano de primera clase. Tu spec tiene que ser operable, con vínculos directos a decisiones, código y tests. Visualizar esa malla en GitHub (decisiones ↔ requisitos ↔ tests ↔ diffs) debería ser trivial. Imagina abrir un diff de markdown y ver “este requisito cambia X líneas de código” con enlaces directos. Eso es la próxima generación de repositorios.

    11) Cultura y proceso: lo que no puedes automatizar

    No automatices la cultura. Exige que cada PR responda:

    • ¿Qué decisión justificó este cambio?
    • ¿Qué requirement se actualiza?
    • ¿Qué test cubre el cambio?

    Haz que la herramienta extraiga esos metadatos y los convierta en entradas .jsonl. Convierte la disciplina en hábito.

    12) Checklist mínimo para empezar hoy (15–30 minutos)

    1. Versiona tu spec en Markdown en la raíz del repo.
    2. Asegura tests automatizados (si eres Python, Pytest; si no, prepara adapter).
    3. pip install plum-dev
    4. plum init → apunta specs.md y carpeta de tests.
    5. Añade .plumignore (README, docs, assets).
    6. Configura umbrales: prod = strict; feature branches = lenient.
    7. Prueba: haz un cambio via agente, intenta commit, observa el fail y aprueba la decisión.
    8. Ejecuta plum sync -> revisa gaps spec↔tests↔code.

    13) Si no lo haces: la factura llegará

    Velocidad hoy = caos mañana. Cuando explote algo crítico a las 2 AM, nadie sabrá por qué la regla cambió. El time-to-fix se multiplicará. La deuda técnica se vuelve refractorable, y cada refactor cuesta más que el ahorro inicial de haber delegado.

    14) Beneficios reales (sí, más allá del miedo)

    • Auditoría real para compliance.
    • Onboarding más rápido: nuevos devs leen el árbol de decisiones.
    • Menos debates eternos en PRs: la intención está documentada.
    • Productividad con control: velocidad sin descontrol.

    15) Cierre y acción concreta

    No es sexy. Es necesario. Instala la plomada. Prueba en una rama. No por postureo: por supervivencia técnica.

    Quiero ayudarte a empezar ya. ¿Quieres que te mande:

    • el template de .jsonl listo para copiar,
    • el flujo de PR + configuración de CI que bloquea merges hasta sync exitoso,
    • y un checklist de integración de Plum en 15 minutos?

    Respóndeme “Mándame el template” y te lo doy ahora mismo.
    Y mientras lo instalas, recuerda esto: velocidad sin plomada es solo una forma elegante de cavar tu propia trampa.

    Esto no acaba aquí.

    Si quieres profundizar en prácticas de gobernanza y automatización que encajan con este enfoque, revisa Dominicode Labs para recursos y experimentos relacionados.

    FAQ

    ¿Qué hace exactamente Plum cuando detecta una decisión?

    Intercepta el commit, extrae decisiones desde los traces del agente y falla el commit hasta que alguien apruebe, edite o rechace la decisión.

    ¿Plum bloquea commits automáticamente?

    Sí: si detecta decisiones relevantes, el commit falla hasta que se resuelva la aprobación o edición de esa decisión.

    ¿Cómo se almacena la autoría y los timestamps?

    Se agregan entradas .jsonl con campos como pregunta, decisión, autor, branch y timestamps; además la spec en Markdown se actualiza para reflejar la decisión.

    ¿Cómo evito que la herramienta genere ruido?

    Configura umbrales y filtros por carpeta, agrupa decisiones no críticas en lotes y ajusta sensibilidad por rama o módulo.

    ¿Se puede integrar Plum en CI/CD?

    Sí. La gobernanza debe integrarse en CI para ser efectiva; Plum puede bloquear merges hasta que el sync y las aprobaciones sean exitosas.

    ¿Qué contiene una entrada .jsonl?

    Cada entrada incluye el dilema técnico, la decisión, quién aprobó, si fue propuesto por LLM o humano, vínculo a la diff/PR y marcas de tiempo.

    ¿Qué pasa si rechazo una decisión detectada?

    Idealmente el sistema revierte el cambio o solicita al agente rehacerlo; hoy ese comportamiento es work-in-progress y depende de la configuración del repositorio.

    ¿Cómo empezar en 15 minutos?

    Versiona la spec en Markdown, asegura tests automatizados, instala plum-dev, ejecuta plum init, configura .plumignore y umbrales, y prueba el flujo con un cambio vía agente.

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

  • Implementa Spec-First y TDD para asegurar código con Claude Code

    Implementa Spec-First y TDD para asegurar código con Claude Code

    Spec-First + TDD: el combo que hace que Claude Code no rompa nada

    Tiempo estimado de lectura: 4 min

    • Spec-First transforma requisitos en contratos ejecutables que eliminan ambigüedades.
    • TDD convierte esos contratos en tests que fallan primero (Red) y obligan a implementar hasta pasar (Green).
    • El flujo reduce suposiciones del agente, evita happy-paths y deuda técnica silenciosa.
    • Requiere versionar specs y tests junto a la implementación para trazabilidad y control.

    Spec-First + TDD: el combo que hace que Claude Code no rompa nada. Díselo a cualquier equipo que delega implementaciones críticas a un agente y observarás tres problemas: suposiciones, happy-paths y deuda técnica que aparece en silencio. Este patrón invierte el orden habitual: especificación primero, tests que fallan después, implementación solo para pasar tests. Resultado: la IA implementa contra contratos ejecutables, no contra intuiciones.

    Resumen rápido (lectores con prisa)

    Spec-First convierte requisitos en contratos ejecutables. TDD transforma esos contratos en tests rojos que deben pasar. El agente implementa únicamente para lograr que pnpm test devuelva exit code 0. Menos ambigüedad, más trazabilidad, menos regresiones.

    Spec-First + TDD: qué es y por qué lo necesitas con Claude Code

    Claude Code y otros agentes son excelentes generadores de código, pero su entrenamiento los empuja a soluciones “plausibles”, no necesariamente correctas para tu dominio. La solución no es prompts más largos; es cambiar el flujo de trabajo.

    Spec-First + TDD combina:

    • Spec-First: transformar requisitos en un contrato preciso y ejecutable (feature-spec.md).
    • TDD: traducir ese contrato a tests que inicialmente fallan (Red).
    • Implementación: conceder al agente la tarea de alcanzar el verde (Green) ejecutando y corrigiendo hasta que pnpm test devuelva exit code 0.

    Links útiles: Claude Code docs y Vitest para ejemplos de runners.

    Flujo operativo paso a paso

    1) Escribir la especificación (Spec)

    La especificación no es un texto largo: es un contrato. Define funciones, inputs, outputs, errores y reglas inmutables.

    Ejemplo (feature-spec.md):

    Feature: applyDiscount(order, coupon)

Función: applyDiscount(order, coupon)
Inputs:
- order: { id, subtotal, userId, items[] }
- coupon: { code, type: 'percentage'|'fixed', value, minOrder, expiresAt }

Reglas:
- Si coupon.expiresAt < now -> DiscountExpiredError
- Si order.subtotal < coupon.minOrder -> OrderBelowMinimumError
- total = max(0, subtotal - discount)

    Si necesitas respuesta HTTP o formatos JSON exactos, escríbelos. Nada queda implícito.

    2) Generar esqueletos de tests que fallen (Red)

    Pide a Claude que genere solo los tests: archivos Vitest/Jest que describan las aserciones exactas. Estos tests deben fallar inicialmente porque la implementación aún no existe.

    Ejemplo breve (applyDiscount.test.ts):

    import { applyDiscount } from './applyDiscount'
import { DiscountExpiredError } from './errors'

it('lanza DiscountExpiredError si el cupón expiró', () => {
  expect(() => applyDiscount(orderExpired, couponExpired)).toThrow(DiscountExpiredError)
})

    Ejecuta pnpm test localmente o desde el agente. Verás rojo: eso es correcto. Tienes un contrato ejecutable.

    3) Implementación: el agente repara hasta verde

    Autoriza a Claude a escribir el código con una instrucción clara:

    “Implementa applyDiscount() conforme a feature-spec.md. Ejecuta pnpm test y corrige hasta que todos los tests pasen. No modifiques los tests.”

    El agente iterará: escribir, ejecutar, leer errores, corregir. Termina cuando el runner devuelve 0. Esa condición objetiva sustituye la “autovalidación” del modelo.

    Beneficios reales y medibles

    • Trazabilidad: cada cambio está ligado a un test derivado de una especificación humana.
    • Determinismo: el criterio de finalización es el estado del test runner, no el juicio subjetivo del agente.
    • Menos regresiones: CI bloqueará commits que rompan contratos; el agente ya trabaja para pasar esa barrera.
    • Refactor seguro: optimizar sin romper es posible porque la suite revisa invariantes.

    Métricas a monitorear: porcentaje de PRs que pasan en la primera ejecución de CI, número de reverts por errores de negocio, tiempo medio para retomar trabajo en sesiones de agente.

    Cuándo aplicar este combo (y cuándo no)

    Aplica Spec-First + TDD cuando:

    • La lógica tiene invariantes críticas: facturación, pagos, permisos.
    • La feature afecta múltiples consumidores del API.
    • Vas a delegar implementación a sesiones autónomas del agente.

    No lo uses para:

    • Prototipos visuales donde la iteración UX prima.
    • Scripts puntuales o migraciones one-off.
    • Cambios triviales donde crear tests cuesta más que la implementación.

    Buenas prácticas y guardrails

    • Versiona feature-spec.md junto con la PR que implementa la feature.
    • No permitas que el agente modifique tests sin revisión humana.
    • Mantén artefactos pequeños: especificaciones por feature, no documentos gigantes.
    • Incluye en CLAUDE.md la referencia a specs y al contrato de proyecto para que Claude cargue el contexto inicial: esto reduce fricción y errores de interpretación (ver docs).

    Spec-First + TDD no es un ritual: es control. Si quieres que Claude Code deje de ser creativo y empiece a ser fiable, escribe contratos ejecutables primero, exige tests rojos y permite que la IA solo implemente para pasar tests. El resultado no es menos velocidad: es menos correcciones, menos deuda y más confianza en el código que llega a producción.

    Dominicode Labs

    Para equipos que automatizan con agentes y workflows, un laboratorio de pruebas y plantillas de specs acelera la adopción. Consulta Dominicode Labs como continuación lógica para crear artefactos y plantillas reutilizables.

    FAQ

    Respuesta: Spec-First es un contrato ejecutable que define funciones, inputs, outputs y errores de forma precisa. La documentación normal puede ser descriptiva; la spec exige reglas inmutables y formatos exactos que pueden traducirse a tests automatizados.

    Respuesta: Forzar tests rojos crea un criterio objetivo: la implementación debe satisfacer el contrato verificable. Evita que el agente implemente “por intuición” y asegura que el código cumpla casos límites y errores definidos.

    Respuesta: Usa runners como Vitest o Jest para ejecutar tests. Ejecuta pnpm test en CI y localmente para validar que el agente alcanzó exit code 0.

    Respuesta: Políticas de revisión de PR que bloqueen merges si los tests cambian sin aprobación humana y reglas de CI que rechacen cambios en archivos de tests son medidas efectivas. Además, incluye en el proceso de aceptación la verificación de artefactos versionados.

    Respuesta: Hay una inversión inicial: escribir specs y tests. Esa sobrecarga se compensa con menos rework, menos regresiones y mayor velocidad a largo plazo cuando los agentes trabajan contra contratos claros.

    Respuesta: Métricas recomendadas: porcentaje de PRs que pasan en la primera ejecución de CI, número de reverts por errores de negocio y tiempo medio para retomar trabajo en sesiones de agente.