DOMINICODE

Category: AI

  • 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 usar Claude Code a diario: flujo, comandos y productividad

    Cómo usar Claude Code a diario: flujo, comandos y productividad

    Un lunes por la mañana abrí la terminal en la raíz de un monorepo, escribí "arregla el checkout, está fallando en producción" y me fui a por un café.

    Volví a los veinte minutos. Claude Code había tocado catorce archivos, había reescrito medio servicio de notificaciones que no tenía nada que ver con el bug y había dejado la suite en rojo por sitios nuevos. Novecientas líneas de diff. Tardé más en revisar aquello que lo que habría tardado en arreglar el bug a mano.

    La lectura fácil es "la IA todavía no está para esto". La honesta es otra: le di a un agente autónomo un objetivo ambiguo, un repositorio entero y ninguna forma de avisarme de que se estaba perdiendo. Lo raro habría sido que saliera bien.

    Desde entonces trabajo con él todos los días. Y lo que ha cambiado no son los prompts. Ha cambiado la forma del día: cómo arranco la sesión, qué le suelto entero, dónde pongo los límites y cuándo la corto. Este post es el mapa de ese flujo: cómo usar Claude Code un día entero de trabajo real, desde que arrancas la sesión hasta que la cierras. Cada pieza tiene después su propio post con el detalle.

    Qué es Claude Code y por qué no es un chat que escribe código

    Un chat te devuelve texto. Un agente ejecuta.

    Claude Code es el agente de codificación de Anthropic que corre en la terminal: lee los archivos de tu proyecto, ejecuta comandos, lee la salida real y vuelve a intentarlo hasta cumplir el criterio que le diste. No es un autocompletado ni un chat con contexto del repositorio: es un proceso que actúa sobre tu disco, tu git y a veces tu infraestructura.

    Eso cambia dos cosas de golpe. La primera: el contexto deja de ser gratis, porque cada archivo que lee entra en la ventana y se queda ahí compitiendo con lo que de verdad importa. La segunda: cada acción tiene consecuencias en tu disco, en tu git y a veces en tu infraestructura.

    Un compañero de turno necesita tres cosas para no estorbar: saber dónde trabaja, saber qué puede tocar y saber cuándo parar. Lo demás es decoración encima de eso.

    Los tres primeros minutos de la sesión

    Aquí se decide el resto. La mayoría de las sesiones que se van al garete estaban perdidas antes del primer prompt.

    Arranca donde trabajas, no en la raíz. El directorio desde el que lanzas claude determina qué ficheros CLAUDE.md se cargan —Claude Code sube por el árbol de directorios desde donde arrancas y los concatena— y qué rutas puede editar sin pedirte permiso extra. Abrir en la raíz de un monorepo para tocar un solo módulo es empezar con ruido. Si necesitas acceso puntual a otra carpeta, --add-dir te la añade sin mover la sesión.

    Arrancar acotado tiene un segundo efecto: lo que queda fuera del árbol de la sesión no entra en la ventana, y ahí viven los .env, los dumps y los logs que no quieres que se lean ni acaben citados en un commit.

    Comprueba qué se ha cargado de verdad. /context te enseña en qué se está yendo la ventana y qué ficheros de memoria han entrado. Es el primer sitio donde mirar cuando Claude ignora una regla que juras haber escrito: si el archivo no aparece ahí, no la ha leído. Punto.

    Ten un CLAUDE.md que sirva. /init genera uno inicial leyendo el proyecto, pero la versión buena la construyes tú. La regla que uso: si me oigo corregir lo mismo por segunda vez, deja de ser una corrección y pasa a ser una línea del archivo. Cómo estructurarlo para que no acabe siendo un vertedero de cuatrocientas líneas —que es lo que reduce la adherencia, no lo que la mejora— lo desarrollé en CLAUDE.md para proyectos.

    Un matiz que ahorra frustración: CLAUDE.md es contexto, no configuración. Pide, no impone. Para que algo sea imposible hace falta otra pieza, y llegamos a ella al final.

    Arranca en modo plan si la tarea no es trivial. Shift+Tab cicla entre los modos de permisos: manual, aceptar ediciones y modo plan. En modo plan investiga y te propone un plan sin tocar el código: solo edita cuando lo apruebas. Para planificar un prompt suelto, prefíjalo con /plan.

    Leer quince líneas de plan cuesta treinta segundos. Ese es el precio de no repetir el diff de novecientas líneas del principio de este post.

    Qué le delego entero y qué no

    La frontera no es "tareas fáciles contra tareas difíciles". Es reversibilidad y verificabilidad: si puedo comprobar el resultado con un comando y deshacerlo con un git, va entero. Si el coste del error se paga dentro de seis meses, lo conduzco yo.

    Tarea Cómo la trabajo Por qué
    Migración mecánica repetida en 40 archivos Delegada entera El resultado se verifica con tests y linter
    Tests sobre código que ya funciona Delegada entera El criterio de éxito es objetivo: pasa o no pasa
    Investigar por qué falla un test Delegada entera Es trabajo de lectura, no de decisión
    Primera versión de un endpoint con el contrato definido Delegada, reviso el diff El contrato ya está decidido; el relleno no me aporta
    Elegir la librería o el patrón del stack La decido yo, con el agente de sparring Es una decisión que arrastro meses
    Cambios en el modelo de datos con datos en producción Yo, línea a línea El error no es reversible con git
    Auth, permisos y facturación Yo leo cada línea del diff El coste del fallo no es técnico

    Esa tabla no sale de ningún framework. Sale de haberme equivocado en las dos direcciones. Si quieres el criterio completo para decidir de qué lado cae una tarea, lo desglosé en clasificar tareas con IA.

    Delega el ciclo, no el snippet

    Esto es lo que más separa a quien va rápido de quien se pelea.

    Pedir "escríbeme una función que valide el email" es usar un agente como un autocompletado caro. La unidad de trabajo no es la función. Es el ciclo.

    Un encargo bien montado lleva cuatro cosas: objetivo, criterio de éxito comprobable, límites y comandos permitidos.

    Migra src/billing para quitar la dependencia de legacy-lib.
    Los tests de billing tienen que seguir pasando: ejecuta npm test -- billing y corrige hasta que estén en verde.
    No toques src/auth ni las migraciones de base de datos.
    Cuando esté verde, resume en cinco líneas qué has cambiado y por qué.

    La pieza que hace el trabajo ahí es el criterio de éxito. "Que funcione" no es un criterio. "Que npm test -- billing pase" sí, porque el agente puede ejecutarlo, leer la salida real y volver a intentarlo sin ti en medio. Ese bucle es el valor de la herramienta.

    Cuando el encargo es más grande que un ciclo —una feature entera, no una migración— el prompt se queda corto y necesitas una especificación escrita antes de tocar código. Es la metodología que desarrollo entera en el libro de Spec-Driven Development: el agente no falla por falta de inteligencia, falla por falta de contrato.

    Qué hago cuando Claude Code se atasca

    Este es el momento que decide si el día te cunde o lo tiras.

    La señal es siempre la misma. Tres intentos, el test sigue rojo, las disculpas se repiten y las soluciones giran en círculo: toca el mismo archivo, lo revierte, lo vuelve a tocar.

    Cuando pasa eso, el problema ya no es el prompt. Es el contexto: la conversación está llena de intentos fallidos y cada intento nuevo se construye encima de esa basura.

    Insistir es la reacción natural y es la equivocada. Lo que funciona es rebobinar.

    /rewind —o Esc dos veces con el input vacío— abre el menú de puntos de la sesión y te deja restaurar el código, la conversación o las dos cosas. Volver al mensaje anterior al desvío y reformular la tarea con lo que acabas de aprender resuelve más bugs que cualquier prompt heroico.

    Dos limitaciones antes de que te confíes: los cambios que hizo un comando de bash (rm, mv, cp) no se revierten, y las ediciones que aplicó un subagente tampoco. Para eso está git. El checkpoint es un "deshacer" de sesión, no control de versiones.

    Si el atasco viene de haber cambiado de tarea sin darte cuenta, la herramienta es otra: /clear para empezar limpio y /compact para comprimir lo hablado. Arrastrar una conversación entera hacia una tarea que no tiene nada que ver es la forma más silenciosa de degradar los resultados, y está en la lista corta de errores comunes con Claude Code que veo una y otra vez.

    Y si la tarea es larga por naturaleza —una investigación que va a leer treinta archivos—, no la hagas en tu ventana. Delégala a un subagente, que trabaja en su propio contexto y te devuelve solo la conclusión.

    El cierre de sesión: la parte que casi nadie hace

    Casi todo el mundo cierra la terminal cuando el test se pone verde. Ahí se pierde la mitad del valor.

    Reviso el diff completo. Yo, con git diff, no un resumen escrito por el agente que acaba de hacer los cambios. Para diffs grandes lanzo /code-review antes de mirarlo: es rápido detectando lo mecánico —el error tragado, el caso borde sin cubrir, el any que se coló— y me deja la cabeza para lo que requiere criterio. Cómo montar esa revisión para que produzca señal y no ruido lo desarrollé en code review agéntico.

    Miro qué he corregido a mano. Si he tenido que decir "aquí validamos con Zod, no con yup", falta una línea en el CLAUDE.md. Claude Code también toma notas por su cuenta y las conserva entre sesiones, pero lo que quiero que se cumpla siempre lo escribo yo. La diferencia entre lo que anota él y lo que escribes tú, y cómo se comporta en sesiones largas, está en CLAUDE.md, memoria y contexto en un flujo real.

    Y cierro la sesión. En serio. Ocho horas arrastrando cuatro tareas distintas rinden peor que cuatro sesiones limpias, y encima cuestan más.

    Cuándo dejas de escribir prompts y empiezas a construir el entorno

    Llega un punto en el que te oyes repitiendo las mismas instrucciones. Ese es el aviso: el trabajo ya no es escribir mejores prompts, es configurar el entorno para no tener que escribirlos.

    Lo que necesitas Mecanismo Cuándo se carga
    Que conozca las convenciones del proyecto en toda sesión CLAUDE.md Al arrancar, siempre
    Reglas que solo aplican a ciertos archivos .claude/rules/ con paths Cuando toca archivos que encajan
    Un procedimiento repetido de varios pasos Skill (SKILL.md) Cuando la invocas o cuando encaja
    Impedir una acción pase lo que pase Hook En cada evento del ciclo de vida
    Investigación larga sin ensuciar tu contexto Subagente En su propia ventana de contexto
    Trabajo que ocurre sin ti (nocturno, por evento) Routine En la nube, por disparador

    Un skill es un SKILL.md con un procedimiento, y su cuerpo solo se carga cuando se usa, al revés que CLAUDE.md, que entra entero en cada sesión. Lo que es un procedimiento va a un skill; lo que es un hecho va a CLAUDE.md: crear un skill en Claude Code.

    El hook es la única pieza que se cumple sí o sí. CLAUDE.md pide; el hook impone. Si tienes una regla que no puede saltarse nunca —no tocar producción, no commitear sin formatear—, eso es un PreToolUse, no un "IMPORTANTE" en mayúsculas dentro del CLAUDE.md: hooks y guardrails.

    Y por encima están las routines: esa misma configuración ejecutándose sola en la nube de Anthropic, por horario, por API o por eventos de GitHub. En research preview a agosto de 2026, trátalas como tal, pero marcan el salto de "asistente que abro" a "trabajo que ocurre mientras duermo".

    Lo que haría yo mañana

    No montes el sistema entero de golpe. No funciona así y además no lo vas a mantener.

    Mañana, antes del primer prompt, dedica tres minutos:

    1. Lanza claude en la carpeta del módulo que vas a tocar, no en la raíz del monorepo.
    2. Ejecuta /context y comprueba que tu CLAUDE.md aparece entre los ficheros de memoria.
    3. Añade al CLAUDE.md la única cosa que corregiste a mano ayer.
    4. Arranca en modo plan con Shift+Tab y lee el plan antes de aprobarlo.

    Ese es todo el cambio del primer día.

    Cuando eso sea automático, añade la siguiente pieza: un skill para el procedimiento que repites, un hook para la regla que no puede saltarse, un subagente para la investigación que te llena la ventana.

    Si quieres ver este flujo aplicado a un producto real de principio a fin, es lo que construimos en el curso Construye con IA. Y si prefieres ver cómo trabaja gente que ya lo tiene integrado en su día a día, esa conversación pasa en Dominicode Labs.

    Entre agosto de 2025 y agosto de 2026 la herramienta ha cambiado más que tu forma de usarla. Ahí está casi toda la diferencia.

    Preguntas frecuentes

    ¿Cuánto contexto le doy a Claude Code al empezar una sesión?

    El mínimo que le permita hacer la tarea. Arranca en la carpeta del módulo en el que vas a trabajar, no en la raíz del monorepo, y usa --add-dir si necesitas acceso puntual a otro directorio. Después ejecuta /context para ver qué se ha cargado realmente: si tu CLAUDE.md no aparece en la lista de ficheros de memoria, Claude no lo está leyendo y ninguna de tus reglas está en juego.

    ¿Qué hago cuando Claude Code se atasca y repite el mismo error?

    Deja de insistir. Si lleva tres intentos con el mismo fallo, el problema es el contexto contaminado por los intentos anteriores, no el prompt. Usa /rewind (o Esc dos veces con el input vacío) para volver al punto anterior al desvío y reformula la tarea con lo que has aprendido. Ten en cuenta que el rewind no revierte los cambios hechos por comandos de bash ni las ediciones de un subagente: para eso necesitas git.

    ¿Pongo la regla en CLAUDE.md o en un hook?

    Depende de si es una guía o una ley. CLAUDE.md se carga como contexto: Claude lo lee y trata de seguirlo, pero no hay garantía de cumplimiento estricto, sobre todo si el archivo es largo o tiene instrucciones que se contradicen. Un hook se ejecuta en un evento del ciclo de vida y bloquea la acción decida lo que decida el modelo. Convenciones y estilo, a CLAUDE.md. Cosas que no pueden pasar nunca, a un hook.

    ¿Es seguro dejar que ejecute comandos sin confirmar cada uno?

    Depende del modo de permisos y del entorno. El modo manual pregunta antes de cada acción que no sea de lectura. El de aceptar ediciones va más lejos de lo que sugiere su nombre: además de las ediciones de archivo, aprueba comandos de sistema de ficheros —mkdir, touch, mv, cp, sed y también rm— sobre rutas dentro de tu directorio de trabajo. Ese rm se ejecuta sin preguntarte y /rewind no lo deshace. El modo plan investiga sin editar. El modo auto ejecuta con un clasificador aparte que revisa cada acción y bloquea lo que se sale de lo que pediste. Y el que salta todas las comprobaciones, bypassPermissions, solo tiene sentido dentro de un contenedor o una VM aislada, nunca sobre tu máquina de trabajo.

    ¿Claude Code sirve para proyectos grandes o solo para cosas pequeñas?

    Sirve para proyectos grandes, pero cambia lo que tienes que preparar. En un repositorio pequeño te vale con arrancarlo y hablar. En un monorepo necesitas CLAUDE.md por zona, reglas con paths para que solo se carguen cuando toca, y subagentes para que la exploración no llene la ventana principal. El tamaño del proyecto no limita la herramienta: limita cuánto puedes improvisar antes de configurarla.

    Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.

  • Fundamentos del Spec-First Development para desarrolladores

    Fundamentos del Spec-First Development para desarrolladores

    Deja de vibe-codear: Fundamentos del Spec-First Development

    Tiempo estimado de lectura: 6 min

    • Spec-First invierte minutos en especificar para evitar horas de corrección posterior.
    • Sin una spec, los agentes (p. ej. Claude Code) completan huecos con suposiciones que rompen invariantes.
    • Una spec efectiva contiene contexto, contrato, restricciones y casos de uso.
    • Usa vibe coding para prototipos; usa Spec-First para producción y sistemas compartidos.

    Deja de vibe-codear: Fundamentos del Spec-First Development. Deja de vibe-codear: Fundamentos del Spec-First Development. Si confías en prompting improvisado para todo, acabarás con un sistema que “funciona” y nadie entiende. Spec-First Development no es paperwork; es el antídoto práctico contra las suposiciones que los agentes —incluido Claude Code— introducen cuando no hay una especificación clara.

    Resumen rápido (lectores con prisa)

    Spec-First Development: escribir la especificación mínima (contexto, contrato, restricciones, ejemplos) antes de implementar. Útil para producción y sistemas compartidos. Evita suposiciones de agentes y pérdida de consistencia arquitectónica. Usa vibe coding solo para prototipos.

    Fundamentos del Spec-First Development: por qué importa antes de abrir Claude Code

    Vibe coding acelera prototipos. Funciona hasta que el prototipo debe vivir en producción. Los agentes como Claude Code operan dentro de ventanas de contexto finitas; cuando esa ventana se cierra, el agente no recuerda decisiones previas y completa lagunas con suposiciones. Resultado: fragmentos correctos en aislamiento que, juntos, rompen invariantes del sistema.

    Spec-First Development cambia el orden: primero especificas el sistema mínimo necesario (contexto, contrato, restricciones, ejemplos), y luego pides al agente que implemente. Así conviertes a Claude en un ejecutor alineado, no en un improvisador.

    Fuentes útiles:

    Qué falla con el vibe coding en sistemas reales

    • Pérdida de memoria arquitectónica: cada sesión es una pizarra limpia; las decisiones previas no viajan implícitas.
    • Suposiciones silenciosas: el agente rellena huecos según heurísticas, no según tus invariantes.
    • Deuda de coherencia: el conjunto pasa tests unitarios pero falla en invariantes transversales; refactorizarlo es costoso.

    No es que los agentes sean malos. Es que sin especificaciones les pides que inventen el contexto del proyecto en cada interacción.

    Qué debe contener una spec efectiva (los 4 pilares)

    1. Contexto del sistema

    – Stack, rutas, estructura modular, patrones de estado y librerías permitidas.

    – Ejemplo: “Next.js (App Router), Zustand para estado cliente, servicios de microservicios en /services, convención kebab-case para nombres de archivo.”

    2. Contrato de la interfaz

    – Inputs (tipos), outputs (tipos), efectos secundarios permitidos, invariantes.

    – Ejemplo: “Función getUser(id: string): Promise. No realizar llamadas externas salvo a auth-service; no mutar objetos globales.”

    3. Restricciones y criterios de aceptación

    – Requisitos no funcionales: latencia, límites de dependencias, compatibilidad con versiones, criterios de seguridad.

    – Ejemplo: “Respuesta en <200ms p95; no usar librerías con licencia X; cobertura mínima 80% en pruebas unitarias.”

    4. Casos de uso y ejemplos de I/O

    – Un caso nominal, al menos un caso borde y comportamiento ante error.

    – Ejemplo: entrada JSON, salida esperada, salida esperada cuando falta un campo.

    Estos cuatro pilares evitan que el agente “sea creativo” donde no debe.

    Cómo integrar specs en tu flujo con Claude Code (pasos prácticos)

    1. Escribe la spec antes de abrir la sesión del agente

    – No la guardes en Google Docs. Ponla en el repo: SPEC.md junto al test file o como comentario estructurado en tests.

    2. Incluye la spec textual como primer contexto en el prompt

    – No resumas: copia y pega. El agente necesita reglas explícitas, no interpretaciones.

    3. Pide la implementación y las pruebas asociadas

    – Solicita código + tests unitarios que verifiquen los criterios de aceptación.

    4. Valida resultado contra la spec antes de mergear

    – Verde en CI no equivale a alineación arquitectónica. Comprueba invariantes, latencias, dependencias y contratos.

    5. Versiona la spec junto al código

    – Si cambian los requisitos, actualiza SPEC.md; la spec es parte del contrato del repo.

    Ejemplo mínimo de SPEC.md (esquema)

    • – Contexto: [stack, rutas, convenciones]
    • – Contrato: [firma, tipos, efectos secundarios permitidos]
    • – Restricciones: [latencia, dependencias, seguridad]
    • – Casos: [input nominal → output; caso borde; error esperado]
    • – Criterios de aceptación: [tests, performance, compatibilidad]

    Guardarlo en el repo reduce el ciclo “pregunta-respuesta” y elimina ambigüedades en prompts posteriores.

    Cuándo usar vibe coding y cuándo spec-first

    – Vibe coding: validación rápida de concepto, experimentación aislada, exploración de bibliotecas.

    – Spec-First: producción, microservicios compartidos, sistemas con múltiples mantenedores, integraciones críticas.

    No es blanco o negro: usa vibe para idear, spec-first para construir. Esa transición mental es la diferencia entre velocidad aparente y velocidad sostenible.

    Cierre: el coste real de no especificar

    Un agente sin spec es un colaborador talentoso sin briefing: produce soluciones plausibles que resuelven problemas distintos al que tienes. Escribir specs no es burocracia; es invertir minutos que ahorran horas de corrección y semanas de deuda técnica. Antes de abrir Claude Code, escribe la spec. Tu base de código te lo agradecerá.

    Para equipos que trabajan con automatización, agentes y workflows, una práctica complementaria es centralizar plantillas y ejemplos en un laboratorio interno. Más recursos y experimentos aplicados están disponibles en Dominicode Labs.

    FAQ

    Respuesta:

    Spec-First Development es la práctica de definir la especificación mínima necesaria (contexto, contrato, restricciones, ejemplos) antes de implementar el sistema o función.

    Respuesta:

    Antes de comenzar una tarea que vaya a producción, que implique integración entre equipos o que afecte invariantes transversales. Para prototipos rápidos puedes saltarla.

    Respuesta:

    La spec es un contrato operativo y minimalista pensado para ejecución y validación (tests, CI), no un documento extenso de diseño. Está orientada a la implementabilidad.

    Respuesta:

    Sí. Los agentes consumen la spec como contexto explícito y la usan para reducir suposiciones. Es crucial pegar la spec textual en el prompt o ponerla en el repo accesible.

    Respuesta:

    Contexto del sistema, contrato de la interfaz, restricciones y criterios de aceptación, y casos de uso con ejemplos de I/O.

    Respuesta:

    Se pierde trazabilidad entre versiones del código y sus requisitos; provoca divergencias, errores en integración y mayor deuda técnica. Versionar la spec junto al código evita ambigüedades.

  • Implementando Plum para Gobernanza de Decisiones en Código

    Implementando Plum para Gobernanza de Decisiones en Código

    ¿Y si te dijera que tu “spec” es una tarjeta de bienvenida para el caos si no la conviertes en evidencia viva?

    Tiempo estimado de lectura: 6 min

    • Plum convierte decisiones de diseño y agentes en evidencia rastreable ligada a commits.
    • Fallar commits a propósito es el checkpoint que fuerza la aprobación humana y evita decisiones no registradas.
    • El flujo incluye init, extracción de decisiones, bloqueo de commits si hay decisiones pendientes y sincronización spec↔tests↔código.
    • Limitaciones reales: Pytest-only ahora, backfill difícil, deduping fuzzy y riesgo de ruido de interrupción.

    Introducción

    Poca gente habla claro de esto: cuando un Product Manager cambia una regla, la pregunta real no es “¿habrá que tocar el código?” sino “¿cómo sabré mañana quién decidió qué, por qué y con qué pruebas?”. Spoiler: la mayoría no lo sabe. Y con agentes de IA metidos en la cocina, ese “no saber” se vuelve que arda todo en silencio.

    Esto no es teoría bonita. Es práctica sucia. Y la herramienta que te salva la vida se llama Plum. Sí, Plum. La plomada. La que te dice si lo que has levantado está vertical o te lo estás inventando sobre la marcha.

    Resumen rápido (lectores con prisa)

    Qué es: Plum es un guardián operativo que convierte decisiones (humanas o de LLM) en artefactos rastreables ligados a commits.

    Cuándo usarlo: Cuando usas agentes o LLMs para tomar decisiones que afectan código, specs o tests.

    Por qué importa: Evita que las decisiones queden atrapadas en chats y que el repositorio pierda la memoria de intención.

    Cómo funciona (resumen): Hooks de Git + extracción de traces + bloqueo de commits hasta aprobación + sincronización spec↔tests↔código.

    Por qué hay que preocuparse ahora

    – Porque los LLMs generan código a ritmo industrial.

    – Porque cambios urgentes o hotfixes se meten directo al trunk.

    – Porque las decisiones que importan quedan atrapadas en chats —los famosos traces— y se evaporan al cerrar la sesión.

    – Porque las especificaciones se quedan en Markdown como si fueran altares estáticos, sin reflejar lo que el código realmente hace.

    La consecuencia: código que pasa tests pero no cumple intención. Tests que validan outputs, no contratos. Specs que no son contrato sino historia. Y equipos que no pueden responder cuando algo explota en producción.

    Cómo funciona Plum —sin poesía— pero con sentido

    1) plum init

    – Crea .plum y .plumignore.

    – Te pide dónde están tus specs (Markdown) y tus tests (por ahora Pytest).

    – Añade hooks a Git: el commit se convierte en punto de control, no en trámite.

    2) Haces código con un agente

    – El agente toma decisiones en el chat. Tú las apruebas o las ajustas.

    – Al intentar git commit, Plum hace su trabajo: compara diffs desde el último commit y escanea los traces del agente.

    3) Plum extrae decisiones

    – Deduplica (sí, imperfecto; más abajo explico por qué).

    – Te presenta: “estas son las decisiones que tomaste desde el último commit. ¿Las apruebas?”.

    – Si hay decisiones pendientes, el commit falla. Sí, falla a propósito. Tú apruebas o corriges.

    4) Aprobadas → actualizaciones y registro

    – Aprobadas => Plum actualiza la spec (Markdown) y genera un registro .jsonl con la decisión, la autoría (humano o LLM), rama, timestamps y vínculo al diff.

    5) Ejecutas plum sync

    – Plum te muestra las brechas entre spec, tests y código: requisitos sin tests, tests sin caso claro, etc.

    Por qué no puede ser “una skill” del agente

    Porque una skill es una sugerencia dentro del agente. Y las sugerencias se ignoran cuando hay prisa. Si quieres gobernanza necesitas un checkpoint externo e innegociable. Si el commit no falla, la herramienta es una opción más que nadie usa. Plum falla commits a propósito para forzar el acto reflexivo: “aprobación humana o nada”.

    La plomada no pinta paredes. Te evita derrumbes.

    Qué hay dentro del archivo JSONL y por qué importa

    El .jsonl no es un “log más”. Es un registro de intención con metadatos para auditoría.

    Ejemplo de entrada:

    – question: “¿Batchear updates de spec o aplicar por decisión?”

    – decision: “Batch spec updates across all decisions”

    – approved_by: user@example.com

    – proposed_by: LLM (o human)

    – branch: feature/x

    – diff_link: git://…

    – timestamps: created, approved, synced

    Ese registro responde a: quién decidió, qué decidió, por qué y cuándo. Lo que todo equipo serio debería exigir.

    Limitaciones reales (no las bonitas)

    • Pytest-only por ahora. Si usas otro runner, el análisis de cobertura falla. Esto es temporal, pero real.
    • Backfill: Plum funciona mejor si la spec va adelante del código. Analizar un monolito legacy y generar spec desde cero es una tarea distinta.
    • Decision deduping es fuzzy. Identificar “la misma decisión” entre conversaciones humanas y LLMs no es trivial. Depende del repo, del dominio y de tu tolerancia.
    • Ruido de interrupción. Si generas cinco decisiones por un hotfix, te puede cortar el flow. Por eso Plum necesita umbrales de interrupción configurables.
    • Rollbacks automáticos: si rechazas una decisión en la CLI, que se revierta el cambio en el código todavía requiere flujo claro entre agente y control de versiones. No siempre está resuelto. Lo ideal: rechazo en el CLI que abre un “rework” en el agente con rollback automático; hoy es work-in-progress.

    Diseño de umbrales —el arte de no volver loco al dev

    Velocidad es vida. Interrupciones matan. Así que Plum permite (y debe permitir) configurar tolerancias:

    • Modo “dangerously approve all” para prototipos.
    • Modo “auditable strict” para banking, salud, compliance.
    • Filtros por carpeta o tipo de archivo (ej.: cambios en README no generan decisiones).
    • Severidad: solo interrumpir cuando la decisión sea contradictoria con reglas previas o afecte invariantes del sistema.
    • Timebox: decisiones ligeras se acumulan y se presentan en lote, las críticas se presentan inmediatamente.

    Esto es clave: la herramienta debe ser lo suficientemente simple para que cada dev la mantenga en su cabeza. Si no, la ignorarán.

    DSPy y la búsqueda del determinismo

    No me gustan las soluciones que dependen sólo de LLMs para validar la validez de una regla. Cuando puedes usar código —tests, parsers, análisis sintáctico— úsalo. Donde no puedas, estructura las llamadas a LLMs. DSPy ayuda: define inputs/outputs tipados para las llamadas a modelos, reduce alucinaciones y permite testear las respuestas.

    Ejemplo práctico:

    • Deducción de decisión = tarea rápida → GPT-OSS (rápido).
    • Parse semántico de spec = tarea precisa → modelo con DSPy que devuelva JSON estricto.
    • Cuando falla la determinación, vuelve al humano.

    Por qué esto cambia la revisión de código

    Hoy revisas sintaxis y estilo. Mañana, sin estas herramientas, revisarás humo. Con Plum revisas intención. Ves “por qué existe esta función” y no sólo “si el PR es legible”. Es code review con memoria. Y esa memoria evita que los agentes te reproduzcan antiguas prohibiciones por olvido de contexto.

    Checklist mínimo para empezar (15 minutos)

    1. Pip install plum-dev
    2. plumb init (apunta al folder de specs y a tu carpeta de tests)
    3. Añade .plumignore para evitar ruido (README, docs, etc.)
    4. Ajusta umbrales: prototipo vs production.
    5. Corre un hotfix con agente y haz commit — observa el commit-fail, aprueba decisiones.
    6. Ejecuta plum sync y revisa cobertura spec↔tests↔código.
    7. Guarda el .jsonl en la rama y pásalo por review.

    Casos de uso concretos

    • Startups: modo “dangerously approve” para protos, switch a strict cuando tienes usuarios reales.
    • Fintech / Salud: strict desde el primer día, cada micro-decision auditada.
    • Open Source: Plum ayuda a traducir PRs dispersos en decisiones rastreables y aprobadas.

    Metáfora breve

    Tu repo es un edificio. Los agentes son una cuadrilla hiperactiva que puede añadir habitaciones a velocidad absurda. La spec es el plano. Si no actualizas planos y firmas cambios, un día entras y la escalera está en el baño. Plum es la plomada: no te dice cómo pintar, te dice si la pared está derecha.

    La urgencia práctica

    Si ya usas agentes y no capturas decisiones, estás construyendo un legado que nadie asumirá. La deuda técnica no es solo trabajo: es riesgo legal, fiscal y reputacional. La gobernanza no es un lujo, es supervivencia.

    ¿Quieres empezar ahora?

    Pruébalo: pip install plum-dev y corre plum init en una rama de feature.

    Si quieres que te lo haga más fácil, te doy 3 cosas ahora mismo:

    • Un template de .jsonl para registrar decisiones.
    • Un flujo de PR (CI) que bloquea merges hasta sync exitoso.
    • Un checklist para integrar Plum en 15 minutos.

    Respóndeme este mensaje y te lo envío. O instala plum-dev y me cuentas qué encuentras en tu primer commit con agente. Te prometo que descubrirás decisiones que no sabías que habías tomado.

    Si el artículo y su enfoque encajan con tus flujos de automatización, considera explorar más en Dominicode Labs como continuación lógica a la integración de herramientas y procesos en equipos técnicos.

    FAQ

    ¿Qué hace exactamente Plum cuando instalo y lo configuro?

    Instala hooks de Git, identifica dónde están tus specs (Markdown) y tests (Pytest por ahora), y añade puntos de control en commits para extraer y registrar decisiones tomadas por humanos o agentes.

    ¿Plum genera código o modifica mi base de código automático?

    No. Plum no genera código. Actualiza specs y registra decisiones; el código lo sigue haciendo la persona o el agente. Plum actúa como checkpoint y registro.

    ¿Qué pasa si no quiero que ciertos cambios sean bloqueados?

    Puedes configurar umbrales, filtros por carpeta/tipo de archivo y modos (ej.: “dangerously approve all”) para reducir interrupciones en prototipos o áreas no críticas.

    ¿Plum soporta todos los frameworks de tests?

    No: actualmente es Pytest-only. El análisis de cobertura falla con otros runners hasta que se añada soporte explícito.

    ¿Cómo se ve un registro de decisión y qué metadatos incluye?

    Un .jsonl incluye: question, decision, approved_by, proposed_by (LLM o human), branch, diff_link y timestamps (created, approved, synced).

    ¿Qué ocurre si Plum detecta decisiones conflictivas?

    Plum puede bloquear el commit y presentar las decisiones para aprobación. La resolución puede requerir rework en el agente o intervención humana; el flujo de rollback automático es work-in-progress.

    ¿Plum puede integrarse en CI para bloquear merges?

    Sí. Un flujo de PR (CI) puede bloquear merges hasta que plum sync sea exitoso y las brechas entre spec, tests y código hayan sido resueltas.

  • Cómo redactar especificaciones efectivas para IA en desarrollo de software

    Cómo redactar especificaciones efectivas para IA en desarrollo de software

    ¿Quieres que la IA escriba código que aguante en producción o prefieres pagar la reescritura con horas de sueño robadas?

    Tiempo estimado de lectura: 6 min

    • Sin una spec sólida, la IA falla: la salida suele ser “lo más probable” y no lo que tu sistema necesita.
    • Una spec funciona como contrato: entradas, salidas y reglas inmutables (TS, DB, validadores).
    • Proceso y repo: coloca SPEC.md y reglas globales en el repo; pide tests antes de código.
    • Diseña para fallos: idempotencia, retries, observabilidad y mocks de LLM en CI.

    Poca gente dice esto claro: sin una spec sólida, la IA no te ayuda —te traiciona con estilo. Te da un PR brillante, lo mergeas, y dos semanas después estás en modo bombero arreglando incoherencias, dependencias raras y bugs que solo existen porque nadie le dijo al modelo las reglas del juego.

    Esto no es teoría. Es un manual corto y agresivo para escribir specs que conviertan a la IA en ejecutora precisa, no en improvisadora talentosa.

    Resumen rápido (lectores con prisa)

    La IA no entiende contexto técnico; genera lo más probable. Para usarla en producción necesitas specs como contratos: define entradas, salidas, validadores y versiones exactas del stack. Pon la spec en el repo, exige tests (mock de LLM en CI) y diseña idempotencia, retries y observabilidad desde el inicio.

    Primera verdad incómoda: la IA no piensa, predice

    Los modelos son máquinas de probabilidades. No entienden GDPR, SLAs o el negocio que hay detrás del botón. Si no les das límites, rellenan con lo más probable de su entrenamiento. Y lo más probable suele ser un parche bonito… que no encaja en tu arquitectura.

    Qué hace una spec que realmente funcione con IA

    1) Contexto de negocio (el “por qué”) — 1 párrafo

    No le cuentes la historia de tu vida. Di en una frase qué problema resuelve esta feature y qué sería un fallo. Ejemplo: “Crear usuarios con verificación por email. Éxito = usuario activo; fracaso = intento de signup duplicado.” Con eso la IA prioriza seguridad y unicidad, no UX glam.

    2) Contratos de datos inmutables — el núcleo

    Define TODAS las formas de datos:

    • Interfaces TypeScript (ej. CreateUserRequest, UserResponse).
    • Esquema de DB (SQL/Prisma).
    • Validadores (Zod schemas).

    Si el código espera un JSON con { email: string, password: string } dilo. Congela esos contratos. Si cambian, cambia la spec. Esto transforma a la IA en un generador que cumple un contrato, no en un novelista.

    3) Stack y versiones exactas — sin ambigüedades

    “Usa Next.js” es basura. Di “Next.js 14 — App Router — Node 20 — Postgres 15 — pgvector”. Lista librerías permitidas y las prohibidas. Los modelos tienden a usar patrones históricos; dar versión evita sorpresas.

    4) Reglas negativas — lo que NO se debe hacer

    La IA ama instrucciones. Si le dices “No hagas X”, lo recuerda. Lista antipatrones:

    • No exponer variables de entorno en cliente.
    • No añadir dependencias sin revisión CVE.
    • No implementar persistencia eventual en endpoints críticos.

    5) Criterios de aceptación comprobables

    Exige tests. Define qué pruebas deben pasar:

    • Unit tests (ej. hashing de password).
    • Integration tests (ej. createUser -> DB -> verify hash).
    • Tests de resiliencia (reintentos en worker).

    Pedir tests antes que código hace que la IA produzca implementaciones testables.

    Cómo estructurar la spec en el repo (hazlo ya)

    No metas la spec en Google Docs o Notion y esperes que la IA la lea. Ponla en el repo. Que el agente la tenga al lado del código. Dos archivos mínimos:

    Archivos mínimos

    • .cursorrules / .github/copilot-instructions.md — Reglas globales: stack, estilos, convenciones de nombres, políticas de seguridad. Que el agente lo lea siempre.
    • SPEC.md (micro-spec por feature) — Contexto corto, contratos TS, endpoints, criterios de aceptación, reglas negativas, responsables.

    Micro-spec vs contexto global: menos es más

    Saturar la ventana de contexto con miles de archivos confunde. Alimenta a la IA con:

    • SPEC.md del módulo.
    • Tipos globales que realmente importan.
    • Un archivo de reglas globales.

    Menos ruido, más precisión. La IA trabaja mejor con densidad técnica, no con bibliotecas de historia.

    Patrón de trabajo: plan antes de código

    Nunca pidas “haz el CRUD”. Pide un plan en pasos:

    1. Interfaces + DB schema.
    2. Contratos OpenAPI.
    3. Tests de aceptación.
    4. Implementación por sprint.

    Aprueba cada fase. Así evitas que la IA genere código que contradiga los contratos que aprobaste.

    Herramientas que convienen y por qué

    – TypeScript + Zod: transforma respuestas en contratos verificables.

    – Prisma/SQL: esquemas claros y migraciones.

    – OpenAPI: contratos de endpoint.

    – pgvector (si usas vectores): evita añadir otro servicio.

    – n8n para orquestación: sacas la lógica de integración fuera del repo y manejas retries visuales.

    RAG y seguridad: nunca lo tomes a la ligera

    Si vas a indexar documentos para chatear con ellos, cada vector debe llevar tenant_id. Punto. No mezcles tenants. Nunca. El filtro por tenant debe aplicarse en la consulta, no en la app. Si mezclas vectores, estás invitando a fugas de datos.

    Idempotencia, retries y jobs: diseña para fallos

    Asume que la IA y los servicios fallarán. Diseña:

    • Jobs con estado (pending, processing, success, failed).
    • Workers idempotentes por job_id.
    • Dead-letter queues para errores irreparables.
    • Retries con backoff exponencial y circuit breaker.

    No idempotencia = facturación duplicada + datos duplicados. No es elegante. Es caro.

    Observabilidad desde el minuto cero

    Si no mides, no mejoras. Instrumenta:

    • Traces distribuidos (OpenTelemetry).
    • Métricas: latencia por modelo, tokens por job, coste por tenant.
    • Logs estructurados con context_id.
    • Dashboards y alertas (picos de coste, aumentos de error rates).

    Tests: mockea la IA

    No dependas de la API real en CI. Mockea respuestas de LLM —positivas y negativas— y tests que simulen timeouts, respuestas malformadas y ataques de prompt injection. Así la spec y los tests te protegen cuando la IA se sale del carril.

    Plantilla mínima de SPEC.md (rápida y usable)

    Pon esto en la raíz del módulo. No lo copies sin adaptar, pero úsalo como base.

    • Título: Objetivo en una frase.
    • Contexto: 2 párrafos máximos.
    • Stack: versiones exactas.
    • Contratos: interfaces TS + esquemas SQL/Prisma.
    • Endpoints: método, path, payloads (ej. OpenAPI snippet).
    • Regla negativas: lista corta.
    • Criterios de aceptación: tests concretos.
    • Responsables: quién aprueba merge.

    El nuevo rol del senior: menos héroe, más guardián

    El valor del senior hoy no es teclear más rápido. Es decidir fronteras. Es escribir specs que no fallen en producción. Si no tienes eso, la IA solo acelera el desastre.

    Checklist rápido antes de pedir código a la IA

    • ¿SPEC.md está en la raíz del módulo?
    • ¿Interfaces TS y esquemas DB están definidos?
    • ¿Reglas negativas claras?
    • ¿Tests de aceptación definidos?
    • ¿El prompt obliga a devolver JSON validable?

    Si respondes no a cualquiera, no pidas código.

    CTA

    Si quieres la plantilla SPEC.md lista para pegar y un prompt maestro para Claude que funcione hoy, respóndeme “Quiero la plantilla”.

    Te la envío lista para pegar en el repo y para que la IA empiece a generar código que no te rompa la vida.

    Para quienes trabajan en automatización, agentes y workflows este enfoque encaja con prácticas de laboratorio y experimentación. Más recursos y experimentos vinculados a estos patrones están disponibles en Dominicode Labs, que complementan las plantillas y ejemplos prácticos descritos arriba.

    FAQ

    Respuesta: ¿Por qué necesito una spec si la IA puede escribir código por mí?

    Porque la IA genera lo más probable, no lo correcto para tu negocio. Una spec transforma requisitos en contratos verificables que la IA puede cumplir de forma repetible.

    Respuesta: ¿Qué debe contener obligatoriamente un SPEC.md?

    Título objetivo, contexto corto, stack con versiones exactas, contratos (TS + DB), endpoints, reglas negativas, criterios de aceptación y responsables.

    Respuesta: ¿Cómo evito fugas de datos en sistemas RAG?

    Indexa vectores con tenant_id, aplica el filtro por tenant en la consulta y evita mezclar índices entre tenants.

    Respuesta: ¿Qué pruebas debo pedir antes de revisar un PR generado por IA?

    Unit tests, integration tests que verifiquen contratos y tests de resiliencia (timeouts, retries, respuestas malformadas).

    Respuesta: ¿Cómo integro mocks de LLM en CI sin perder cobertura realista?

    Mockea escenarios positivos y negativos, timeouts y prompt injections. Mantén casos representativos que reflejen errores reales observados en producción.

    Respuesta: ¿Qué reglas negativas son las más críticas?

    No exponer env vars en cliente; no añadir dependencias sin revisión CVE; no usar persistencia eventual en endpoints críticos; exigir tests antes del merge.

  • 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 implementar Spec-Driven Development con generación de código

    Cómo implementar Spec-Driven Development con generación de código

    Spec-Driven Development y la librería sin código: lecciones prácticas para equipos que usan IA

    Tiempo estimado de lectura: 4 min

    • Los tests y las especificaciones pasan a ser el activo estratégico principal.
    • Los agentes aceleran la prototipación, pero la última milla exige juicio humano y arquitectura.
    • Modularidad y contratos claros son imprescindibles para desarrollo paralelo con agentes.
    • Trátalo como diseño de comportamiento: invierte en especificaciones y suites de pruebas vivas.

    Spec-Driven Development con IA no es una moda; es una reordenación de prioridades. Cuando los agentes pueden generar sintaxis fiable, el verdadero valor deja de estar en el archivo .js o .rs y pasa a estar en la especificación y la suite de tests. Eso no lo hace más fácil: lo hace más exigente.

    Resumen rápido (lectores con prisa)

    Spec-Driven Development centra el valor en especificaciones y suites de tests para permitir que agentes generen implementaciones confiables. Útil cuando las specs y tests son completos; no sustituye el juicio humano en la última milla. Diseña módulos con contratos claros y valida invariantes del sistema.

    Spec-Driven Development y la librería sin código: qué es y por qué importa

    El experimento es simple y brutal. Publicas en GitHub una librería sin código: un README/markdown que define el comportamiento, cientos —o miles— de pruebas de conformidad y un prompt de instalación para que un agente genere el código. Drew Brunig y otros mostraron que eso funciona para problemas acotados y deterministas: el agente lee la spec, ejecuta tests y genera código que pasa las pruebas.

    Los ejemplos más ambiciosos han escalado esto: reimplementaciones de Bash en TypeScript, intérpretes de Python en Rust o intentos de compilar C usando agentes. Vercel, Anthropic y otros equipos han probado variantes de este enfoque; el patrón es claro: la implementación fluye si la especificación y la suite de tests son precisas.

    Fuentes: Anthropic, Vercel.

    Tres razones por las que esto cambia la arquitectura del equipo

    1) Los tests son tu nuevo activo estratégico

    El código generado es barato; las pruebas no. Todos los proyectos que escalaron partieron de suites de testing masivas ya existentes. Si quieres que agentes produzcan un sistema confiable, primero inviertes en definir con precisión cada comportamiento, cada caso borde y cada ambigüedad. Eso es trabajo intelectual, no texto que copia una IA.

    2) La velocidad inicial es real. La última milla, no tanto.

    Con suficientes agentes y presupuesto puedes alcanzar rápidamente un prototipo que pasa el 80–90% de pruebas. Pero los últimos porcentajes —casos borde, coherencia entre módulos, performance y seguridad— requieren arquitectura, diseño y juicio humano. Ahí los agentes tropiezan: arreglar un fallo local puede romper otro subsistema.

    3) La modularidad ya no es sólo bonita; es imprescindible

    Si vas a ejecutar múltiples agentes en paralelo, necesitas módulos con contratos claros y dependencias mínimas. Un sistema fuertemente acoplado multiplica regresiones y conflictos de merge. Diseñar para desarrollo paralelo es diseñar para agentes: interfaces estables, tests de contrato y boundaries claros.

    Qué aprenden los equipos grandes (ejemplos y síntesis)

    • Reutiliza suites de tests fiables cuando existan; son la fruta madura.
    • Divide el problema en paquetes pequeños y bien definidos que puedan implementarse y probarse de forma independiente.
    • Añade pruebas que validen propiedades transversales (invariantes del sistema), no sólo outputs unitarios. Las pruebas que capturan invariantes evitan que arreglos locales creen fallos sistémicos.
    • Mantén la especificación viva: la implementación te enseñará dónde la spec era ambigua. No es un fallo; es el flujo natural: la implementación mejora la spec.

    Historia y perspectiva académica no son decoración: Margaret Hamilton acuñó “software engineering” para evitar exactamente este problema —la complejidad que excede la capacidad cognitiva de una persona— y para recordarnos que el software es diseño de sistemas, no solo código (https://en.wikipedia.org/wiki/Margaret_Hamilton_(computer_scientist)).

    Cómo aplicar esto en tu equipo hoy (guía práctica)

    • Prioriza las pruebas de dominio antes de automatizar la generación. Invierte en casos reales y casos borde.
    • Diseña el repo como una colección de contratos y tests: cada módulo debe tener su spec y su suite independiente.
    • Automate CI con pruebas de contrato y pruebas de integración reducidas que se ejecuten en cada PR generado por un agente.
    • Establece guardrails: linters, análisis estático y políticas de seguridad que los agentes deben respetar.
    • Trátalo como arquitectura colaborativa: los PRs no solo corrigen código; corrigen intención. Revisa tests con la misma seriedad que revisarías código.

    Qué no esperar (y por qué el hype falla)

    No esperes que este enfoque elimine la necesidad de ingenieros senior. No lo hará. Lo que cambia es la naturaleza del trabajo senior: menos tipografía de código, más diseño de comportamiento, más política de pruebas y más pensamiento sistémico. Los agentes son amplificadores; sin criterio técnico, amplifican errores más rápido.

    No esperes soluciones mágicas para sistemas no deterministas: sistemas distribuidos, UI con estados complejos, políticas de seguridad o requisitos de latencia siguen necesitando diseño humano profundo.

    Conclusión

    Spec-Driven Development con IA es una herramienta poderosa, pero exige una reorientación: de escribir código a diseñar comportamientos verificables. El activo que deberías proteger no es el repo, sino la suite de pruebas y los contratos que definen tu dominio. Si empiezas hoy a convertir ambigüedades en tests, estarás construyendo la infraestructura que permite a los agentes realmente escalar tu producto sin destruirlo. Haz eso y la IA deja de ser un truco y pasa a ser una línea de producción fiable.

    Para equipos que exploran flujos de trabajo con agentes y automatización, puede ser útil revisar enfoques prácticos y herramientas en Dominicode Labs. Esto complementa la práctica de convertir especificaciones en suites de tests desplegables.

    FAQ

    Respuesta: Spec-Driven Development con IA es un enfoque donde la especificación y una suite de tests rigurosa son la fuente de verdad; agentes generan implementaciones que son validadas contra esas pruebas.

    Respuesta: Es apropiado para problemas acotados y deterministas donde puedes definir comportamientos y casos borde exhaustivamente. Funciona menos bien en dominios no deterministas sin especificaciones completas.

    Respuesta: No. Los agentes amplifican productividad, pero el trabajo senior evoluciona hacia diseño de comportamiento, arquitectura de pruebas y evaluación de trade-offs.

    Respuesta: Las suites de tests de dominio y las pruebas que validan invariantes transversales son las más valiosas. Tests de contrato e integración automatizados evitan que soluciones locales rompan el sistema.

    Respuesta: Diseña módulos con contratos estables, limita dependencias y ejecuta pruebas de contrato en CI para cada PR generado por un agente. Linters y análisis estático ayudan como guardrails.

    Respuesta: Anticipa limitaciones en casos borde, performance, seguridad y sistemas no deterministas. La última milla requiere diseño humano; no es una solución automática para todos los dominios.

  • Cómo sincronizar especificaciones, pruebas y código en el desarrollo

    Cómo sincronizar especificaciones, pruebas y código en el desarrollo

    El Triángulo del Desarrollo Dirigido por Especificaciones: cómo evitar gestionar un proceso de programación que superó la capacidad de manejo de un solo hombre. Ni siquiera de un equipo; de un solo hombre..

    Tiempo estimado de lectura: 5 min

    • Ideas clave:
    • El triángulo fundamental: especificación, tests y código deben mantenerse sincronizados.
    • Los agentes aceleran implementación pero introducen decisiones trazables que deben registrarse.
    • Herramientas como Plum extraen decisiones de diffs y traces para actualizar la spec y generar artefactos auditable.
    • Procesos claros (captura de traces, aprobación humana, sync en CI) son necesarios para evitar deuda técnica acelerada.

    El triángulo es simple y brutal: especificación, tests y código. Si uno se despega, el proyecto se rompe. So welcome: este artículo explica por qué el Spec‑Driven Development dejó de ser una ecuación lineal y cómo convertir ese triángulo en una práctica gobernable cuando agentes de IA escriben código.

    Resumen rápido (lectores con prisa)

    Qué es: Un enfoque que trata a la especificación, la suite de tests y el código como un triángulo que debe permanecer sincronizado.

    Cuándo usarlo: Cuando agentes (LLMs/automations) o equipos múltiples generan cambios rápidos y necesitas trazabilidad.

    Por qué importa: Para evitar deuda técnica acelerada y pérdida de intención por decisiones no documentadas.

    Cómo funciona (resumen): Captura diffs y traces, extrae decisiones, confirma con humanos y sincroniza spec↔tests↔código.

    El triángulo: Spec, Tests, Código — So welcome: por qué no basta con una spec

    So welcome: si piensas que subir una spec y soltar agentes en ella es todo lo que hace falta, estás confundiendo velocidad con control. La spec define qué debe pasar. Los tests validan. El código implementa y descubre cosas. Pero la implementación introduce decisiones —humanas y de IA— que permanecen en los traces. Si no capturas esas decisiones, la spec se queda atrás y el sistema deriva. Resultado: managing a coding process that grew beyond one man’s ability to manage. Not even a team, one man.

    ¿Por qué esto importa hoy?

    • Porque los agentes aceleran la implementación.
    • Porque la implementación revela ambigüedades que la spec no anticipó.
    • Porque los hotfixes y cambios urgentes suelen entrar directo al código y no a la spec.

    Si no sincronizas, la velocidad se vuelve deuda técnica exponencial.

    Señales que te indican que el triángulo está roto

    • Commits frecuentes sin cambios en la spec.
    • Pull requests que corrigen tests porque la spec no reflejaba decisiones recientes.
    • Conversaciones largas con el agente donde se tomaron decisiones y nadie las documentó.
    • Cobertura de tests alta en líneas, baja en intención (las pruebas no cubren los requisitos del producto).

    Estas señales son tangibles. Úsalas. Git te cuenta qué cambió. Los traces de los agentes (chats, prompts, respuestas) contienen las decisiones. Los tests te dicen qué se ejecuta. Cruza esas fuentes y tendrás diagnóstico.

    Plum — la plomada que mide la verticalidad del triángulo

    No es teoría: existen herramientas prácticas. Plum (sí, como plomada) busca las decisiones en los diffs y en los traces y las convierte en artefactos verificables. Flujo resumido:

    Plum: Flujo resumido

    1. Ejecutas commit.
    2. Plum lee los diffs y analiza los traces del agente.
    3. Extrae decisiones, las dedupea y te pide aprobación.
    4. Actualiza la spec (Markdown) según lo aprobado.
    5. Ejecuta sync y te muestra brechas spec↔tests↔código.

    Genera además un archivo .jsonl con el historial de decisiones: pregunta, decisión, autor (humano/LLM), rama, timestamps. Eso pasa de “intención perdida en Slack” a “artefacto auditable en el repo”.

    Plum: Instalación mínima

    Instalación mínima: pip install plum-dev. (Limitación actual: integrado con pytest; funciona mejor cuando la spec está por delante del código.)

    Prácticas para mantener el triángulo en sincronía

    • Escribe la spec como un contrato de comportamiento, no como un manifiesto aspiracional. Casos de borde incluidos.
    • Prioriza la suite de tests como activo estratégico: invierte en pruebas que describan la intención, no solo en asserts unitarios.
    • Trata los traces de agente como código: captúralos, régistralos y asócialos a commits.
    • En cada PR generado por agente: exige la checklist de decisiones aprobadas y la actualización del spec.
    • Añade pruebas de invariantes sistémicas (property tests) que detecten regresiones causadas por cambios locales.
    • Diseña módulos con contratos estables para permitir paralelismo de agentes sin colisiones.

    Qué no esperar de los agentes (y por qué necesitas humanos

    • No esperes que un LLM mantenga la visión de producto a largo plazo. Puede sugerir cambios documentales, pero la validación de negocio es humana.
    • No esperes que arreglen deuda técnica sistémica solos. Pueden parchar, pero no rediseñar la arquitectura sin dirección.
    • No esperes que la spec se actualice mágicamente: necesita decisiones aprobadas y trazables.

    Checklist rápido para equipos que van a integrar agentes

    1. Tener specs en Markdown rastreables en repo.
    2. Tener suite de tests ejecutable en CI (pytest u otro).
    3. Integrar captura de traces de agentes (logs/JSON).
    4. Añadir herramienta de reconciliación (ej. Plum) en el pipeline local/CI.
    5. Forzar aprobación humana de decisiones extraídas antes de merge.
    6. Ejecutar sync spec↔tests↔código en cada PR.

    Cierre (acción clara)

    Si tu equipo ya usa agentes y no tiene un proceso de reconciliación entre spec, tests y código, estás acelerando la creación de un legado ilegible. Haz esto hoy: instala plum‑dev, apunta la herramienta a tu spec y a tus tests, y corre plum sync en tu CI. Si no puedes hacerlo aún, al menos comienza a registrar las decisiones en cada PR. No es glamour. Es gobernanza. Y sin eso, la velocidad que prometen los agentes solo te dará más problemas.

    Haz clic aquí para empezar: pip install plum-dev y corre plum init en un repo con spec y pytest.

    Para equipos que integran agentes y workflows de automatización, una continuación natural es explorar recursos y prácticas en Dominicode Labs, donde se agrupan experimentos y herramientas relacionadas con reconciliación de specs, capture de traces y pipelines de pruebas.

    FAQ

    ¿Qué es el “triángulo” en Spec‑Driven Development?

    Es la idea de que especificación, tests y código forman un conjunto interdependiente. Si cualquiera de los tres se desincroniza, el proyecto corre riesgo de perder intención y acumular deuda técnica.

    ¿Por qué los agentes rompen la sincronía entre spec, tests y código?

    Porque aceleran la implementación y toman decisiones durante el desarrollo (en prompts, chats, respuestas) que a menudo no quedan reflejadas en la spec ni en los tests, creando discrepancias trazables en diffs y commits.

    ¿Qué hace Plum exactamente?

    Plum analiza diffs y traces de agentes, extrae decisiones, las dedupea, solicita aprobación y actualiza la spec en Markdown. También genera un archivo .jsonl con el historial de decisiones para auditoría.

    ¿Cómo debo tratar los traces de agentes?

    Captúralos y regístralos como artefactos vinculados a commits; trátalos como código: deben estar versionados, asociados a PRs y revisados por humanos para extraer decisiones verificables.

    ¿Qué requisitos mínimos necesito para integrar este flujo?

    Specs en Markdown rastreables, suite de tests ejecutable en CI (por ejemplo pytest), captura de traces (logs/JSON) e integración de una herramienta de reconciliación en el pipeline.

    ¿Quién debe aprobar las decisiones extraídas por herramientas automatizadas?

    Siempre un humano con responsabilidad de producto o arquitectura. Las herramientas extraen y proponen; la validación de negocio y la aprobación final deben ser humanas.

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