DOMINICODE

Category: Blog

Your blog category

  • Ultraplan y Computer Use: Mejora de procesos para validación y trazabilidad

    Ultraplan y Computer Use: Mejora de procesos para validación y trazabilidad

    Claude Code — Ultraplan + Computer Use en preview

    Tiempo estimado de lectura: 6 min

    • Ultraplan añade trazabilidad: planes auditablez y checkpoint de aprobación antes de ejecutar acciones automatizadas.
    • Computer Use permite interacción visual y de UI desde el CLI, cerrando parte del loop de validación visual.
    • El comando /resume reduce latencia en sesiones largas (hasta 67% según changelog) mediante optimización de Prompt Caching.
    • Adopción segura exige sandboxing, revisión humana y pipelines CI como árbitros finales.

    Claude Code — Ultraplan + Computer Use en preview aparece en el changelog publicado por Releasebot / Claude Code Changelog (6–10 abr 2026) y cambia dos conversaciones que llevábamos años teniendo: la auditablez de los agentes y su capacidad para interactuar con interfaces nativas. En las primeras líneas: Ultraplan separa planificación, revisión y ejecución; Computer Use permite que Claude abra apps, haga clics y verifique cambios visuales desde el CLI. Fuente: Releasebot / Claude Code Changelog (6–10 abr 2026).

    Resumen rápido (lectores con prisa)

    Ultraplan genera planes auditablez (árbol de decisiones) que requieren aprobación humana antes de ejecutar en entornos remotos. Computer Use permite interacciones GUI desde el CLI para validar cambios visuales. /resume mejora rehidratación de sesiones mediante Prompt Caching, reduciendo latencia al retomar contextos largos.

    Claude Code — Ultraplan + Computer Use en preview: qué hace cada pieza

    Ultraplan

    • Planifica desde el CLI: describes el objetivo y Claude genera un árbol de decisiones (archivos a tocar, comandos, condiciones de éxito).
    • Revisión en editor web: el plan se exporta para auditarlo de forma asíncrona (aprobación humana antes de ejecutar).
    • Ejecución remota: tras la aprobación, la ejecución corre en entornos remotos, no en la máquina local.

    Impacto: trazabilidad y cumplimiento. Ultraplan introduce un checkpoint explícito, similar a un PR de alto nivel, pero orientado a acciones automatizadas.

    Computer Use (research preview)

    • Desde el CLI, Claude puede abrir aplicaciones nativas, interactuar con UI (clics, formularios) y comprobar resultados visuales.
    • Caso de uso: implementar un modal en React → el agente levanta el dev server, abre el navegador, hace clic en “Login”, valida el modal y corrige CSS si detecta fallos visuales.

    Impacto: cierra el loop de validación visual que hasta ahora exigía intervención humana. Riesgo: fragilidad frente a resoluciones, animaciones y latencia.

    Comando /resume: hasta 67% más rápido

    • Mejora en rehidratación de sesiones largas: optimización de Prompt Caching que reduce la latencia al retomar contextos extensos.
    • Traducción práctica: retomar una sesión de debugging o un ticket de refactor en un monorepo deja de ser un dolor de cabeza.

    Fuentes principales: Releasebot changelog y documentación general de Anthropic sobre Claude.

    Por qué esto importa (y por qué no hay que lanzarse a ciegas)

    1) Auditoría y cumplimiento ya no son excusas.

    Ultraplan convierte un plan opaco en un artefacto revisable antes de ejecutar comandos destructivos. Eso es imprescindible en empresas con compliance y requisitos de trazabilidad. Si tu flujo de trabajo no permite revisar planes antes de ejecutar, no deberías usar agentes que escriben directamente en master.

    2) Validación visual automatizada acelera ciclos UX, pero es frágil.

    Computer Use es útil para comprobaciones rápidas en entornos controlados: smoke tests visuales, validaciones de flujo end-to-end en dev VMs, tests de regresión visual sencillos. No es adecuado todavía para pruebas deterministas en CI conectado a producción sin un sandbox robusto.

    3) Latencia reducida = sesiones realmente usables.

    El /resume más rápido no es solo confort; cambia la ergonomía de trabajo con agentes en proyectos reales. Si tu equipo ya trabaja con sesiones largas, esto mejora la adopción práctica.

    Limitaciones y recomendaciones técnicas

    • Sandbox obligatorio: correr Computer Use en máquinas con credenciales activas es irresponsable. Usa VMs o contenedores dedicados sin acceso a secretos.
    • No relies on pixel clicks: las pruebas deben combinar visión con checks DOM y tests automatizados. Si el agente actúa solo por coordenadas, esperen fallos por cambios menores de UI.
    • Revisión humana no es opcional: Ultraplan mitiga, pero no elimina, la necesidad de un Tech Lead que apruebe estrategias y revise trade-offs.
    • CI como árbitro final: cualquier PR o cambio generado por un agente debe pasar pipelines de integración, análisis estático y escaneo de dependencias antes del merge.
    • Documenta reglas de actuación: RULES.md, ADRs y guías de seguridad orientan al agente y reducen decisiones erráticas.

    Cuándo adoptar y cuándo esperar

    Adopta Ultraplan y Computer Use en preview si:

    • Necesitas acelerar refactorizaciones repetitivas con revisión humana.
    • Tienes capacidad de desplegar entornos aislados y pipelines robustos.
    • Quieres reducir el ciclo manual de validación visual en prototipos y pruebas de integración.

    No las uses en producción abierta si:

    • No puedes aislar el entorno del agente.
    • Tu UI depende de animaciones o resoluciones variables sin fallback DOM.
    • Tu organización no acepta un nuevo paso de auditoría humana en el flujo Dev→Prod.

    Conclusión

    Claude Code — Ultraplan + Computer Use en preview no es solamente una actualización de features; es una promesa operativa: agentes que planifican con trazabilidad y que pueden verificar visualmente cambios. La recompensa es real — velocidad y cierre de loops de validación—, pero la adopción requiere disciplina: sandboxing, CI riguroso y aprobación humana como norma.

    Lee el changelog original (Releasebot / Claude Code Changelog, 6–10 abr 2026) para detalles de versión. Para referencia del motor de razonamiento y mejores prácticas en agentes, consulta Anthropic.

    Integra estas capacidades en entornos aislados, añade reglas de seguridad y deja que la primera iteración falle allí antes de llevarlo a tus repositorios críticos. Esto no acaba aquí: lo que hoy es preview será mañana estándar—prepárate con criterio.

    FAQ

    ¿Qué es Ultraplan?

    Ultraplan es una funcionalidad que genera un árbol de decisiones desde el CLI (archivos a tocar, comandos, condiciones de éxito), permite revisión asíncrona en un editor web y ejecuta acciones en entornos remotos tras aprobación humana.

    ¿Qué permite Computer Use?

    Computer Use permite a Claude abrir aplicaciones nativas, interactuar con la interfaz de usuario (clics, formularios) y verificar resultados visuales desde el CLI, en un research preview.

    ¿Es seguro ejecutar Computer Use en máquinas con credenciales?

    No. Se recomienda ejecutar Computer Use en VMs o contenedores aislados sin acceso a secretos; correrlo en máquinas con credenciales activas es irresponsable.

    ¿Qué significa que /resume sea hasta 67% más rápido?

    Según el changelog, /resume mejora la rehidratación de sesiones largas mediante optimización de Prompt Caching, lo que reduce la latencia al retomar contextos extensos y hace las sesiones más ergonómicas.

    ¿Debo confiar en validaciones solo por clicks en píxeles?

    No. Las pruebas deben combinar visión con checks DOM y tests automatizados. Confiar únicamente en coordenadas de píxel es frágil frente a cambios menores en la UI.

    ¿Qué proceso de revisión recomiendan?

    Mantener aprobación humana explícita (Tech Lead) sobre planes generados por Ultraplan, someter cualquier cambio a pipelines CI, análisis estático y escaneo de dependencias antes del merge.

    ¿Dónde puedo leer el changelog y la documentación?

    El changelog está en Releasebot / Claude Code Changelog (6–10 abr 2026). La documentación y mejores prácticas de agente se encuentran en Anthropic.

  • Diseña interfaces con IA sin necesidad de diseño previo

    Diseña interfaces con IA sin necesidad de diseño previo

    UI/UX con IA: diseña interfaces profesionales sin saber diseñar

    Tiempo estimado de lectura: 3 min

    • Automatiza la entrega de UI conectando contratos de datos con generadores de componentes (ej. v0).
    • Diseño por prompt: define estructura, tipos y estados en el prompt para evitar deuda técnica.
    • Pipeline técnico: exporta componentes al repo, añade tests y linters, y orquesta workflows (ej. n8n).
    • Usa herramientas accesibles y tipado estricto para entregar interfaces reproducibles y auditables.

    UI/UX con IA: diseña interfaces profesionales sin saber diseñar. No es un titular rimbombante: es la forma práctica de pasar del boceto a componentes de producción en horas, manteniendo controles que evitan deuda técnica. Si eres desarrollador o fundador técnico, este artículo te da el camino concreto y reproducible.

    Resumen rápido (lectores con prisa)

    Definición: Generar UI tipada y exportable mediante modelos y herramientas que producen componentes (ej. v0).

    Cuándo usarlo: validar flujos rápido, iterar sin diseñador, o para MVPs y paneles internos.

    Por qué importa: acelera entregas manteniendo control técnico si se exige tipado, accesibilidad y tests.

    Cómo funciona: define contratos (TS/JSON), genera componentes por prompt, integra en repo, añade tests y orquesta workflows.

    UI/UX con IA: diseña interfaces profesionales sin saber diseñar — qué es y cuándo usarlo

    La IA ya no entrega solamente imágenes. Herramientas como v0 generan componentes React + Tailwind listos para importar. Si agregas un contrato de datos estricto y un pipeline claro, obtienes interfaces profesionales sin dominar Figma ni teoría tipográfica.

    Úsalo cuando:

    • Necesitas validar UX/flow rápido (MVP, panel interno).
    • Tienes control técnico para auditar el código generado.
    • Quieres iterar diseños sin depender de un diseñador en cada cambio.

    Evítalo si necesitas identidad visual muy distinta o dirección de arte avanzada.

    Herramientas clave (URLs y roles)

    • v0 — Generador UI: v0.dev
    • shadcn/ui — Sistema de componentes accesibles: ui.shadcn.com
    • Cursor — IDE asistido por IA para mantener contexto de repo: cursor.com
    • n8n — Orquestación y workflows: n8n.io
    • Supabase — Base de datos y auth: supabase.com
    • Anthropic / Claude — Modelos LLM para prompts estructurados: anthropic.com/docs

    Framework práctico: cómo hacerlo, paso a paso

    1) Define contratos de datos (TypeScript)

    • Archivo: ticket.types.ts, por ejemplo.
    • Ejemplo:
    interface Ticket { id: string; status: 'pending'|'active'|'cancelled'; amount: number; createdAt: string; logs?: string[] }

    Beneficio: cualquier UI generada consume tipos reales y no inventa propiedades.

    2) Crea el prompt técnico (Design‑by‑Prompt)

    Elementos del prompt:

    • Estructura: grid/columns, sidebar, header.
    • Contrato de datos: incluye el TypeScript o JSON schema.
    • Estados: loading skeleton, empty state, error state.
    • Accesibilidad: aria-labels, contraste AA.

    “Genera un componente React/TSX en Next.js + Tailwind que muestre un Dashboard con sidebar y tabla. Consume Tickets[] con {id,status,amount,createdAt}. Incluye skeleton loader, estado vacío con CTA y badges semánticos para status. Usa componentes shadcn/ui.”

    3) Scaffolding en v0

    • Pega el prompt en v0 y itera visualmente.
    • Exporta el componente como módulo importable.
    • Resultado: componentes tipados y estilizados con Tailwind, listos para conectar.

    4) Integra y sustituye mocks

    • Importa a tu repo.
    • Sustituye datos mock por hooks (React Query, useSWR) o Server Components.
    • Conecta a Supabase si necesitas datos reales.

    5) Cablea la lógica compleja en Cursor

    • Usa Cursor para que el agente genere tests unitarios (Vitest) y funciones que mantengan firmas.
    • Flujo: tests → fallan → implementación hasta pasar tests. TDD evita parches.

    6) Orquesta y despliega

    • Para pipelines (forms, uploads) usa n8n.
    • Añade validación en el extremo antes de persistir para evitar corrupción de datos.
    • Versiona workflows y exporta JSON al repo.

    Reglas prácticas para evitar deuda técnica

    • Tipado por delante: siempre. Si la UI no consume tus tipos, romperá en producción.
    • Prompt como contrato: incluye schema JSON/TS en el prompt.
    • Accesibilidad no negociable: pide aria y contraste AA.
    • Exporta código generado al repo y revísalo en CI con linters y tests.
    • Versiona prompts y componentes como plantillas en tu monorepo.

    Ejemplo de prompt minimalista (plantilla reutilizable)

    “Instrucciones: genera un componente TSX para Next.js que reciba prop tickets: Ticket[] (adjunto el TypeScript). Layout: sidebar izquierdo, header con search, tabla paginada. Estados: loading skeleton, empty state con CTA ‘Crear ticket’. Accesibilidad: aria-labels, keyboard navigation. Estilo: Tailwind + shadcn/ui.”

    Pega esto en v0 y ajusta el contrato según tu dominio.

    Límites y responsabilidad del técnico

    La IA entrega ejecución; tú defines criterio. Los modelos saturan el espacio de soluciones probadas (estilo SaaS), lo que es ideal para MVPs y herramientas internas. No esperes creatividad de marca radical ni decisiones estratégicas de UX. El diseñador del futuro para productos técnicos es quien define métricas, flujos y prioridades; la IA ejecuta la capa visual.

    Implementar UI/UX con IA acelera validación y reduce costes, pero obliga a una disciplina técnica: contratos, tests y revisiones. Hazlo bien: define tipos, genera componentes, integra, prueba y versiona. Y repite. Esto no acaba aquí; convierte estas plantillas en cultura de producto y haz que el diseño generado trabaje para tus métricas.

    Para equipos interesados en aplicar automatización, agentes y workflows en pipelines de UI/UX con IA, vea los experimentos y plantillas de Dominicode Labs. Es una continuación natural para quien integra herramientas como n8n o Cursor en sus procesos.

    FAQ

    Respuesta: Proyectos orientados a MVPs, herramientas internas y paneles administrativos son los más adecuados. Requieren rapidez de validación y control técnico para auditar el código generado.

    Respuesta: Define contratos de datos (TS/JSON) antes de generar UI, exige estados (loading/empty/error), añade tests y linters en CI, y revisa el código exportado al repo.

    Respuesta: Prioriza generadores de UI tipados (v0), sistemas de componentes accesibles (shadcn/ui), un backend con auth/DB (Supabase) y herramientas de orquestación (n8n).

    Respuesta: No siempre. Para entregas técnicas y rápidas un equipo con criterio y tipos puede prescindir de un diseñador. Para identidad de marca y dirección de arte avanzada sí se necesita un diseñador.

    Respuesta: Incluye requisitos de accesibilidad en el prompt (aria-labels, contraste AA), usa componentes accesibles (ej. shadcn/ui) y añade pruebas automatizadas que verifiquen etiquetas y navegación por teclado.

    Respuesta: Flujo mínimo: 1) definir tipos; 2) generar componente en v0 con el prompt; 3) exportar al repo; 4) reemplazar mocks por hooks; 5) añadir tests y CI.

  • Cómo utilizar Angular MCP Tools Read-Only para mejorar tu flujo de trabajo

    Cómo utilizar Angular MCP Tools Read-Only para mejorar tu flujo de trabajo

    Angular MCP Tools: Read-Only RAG e Inspectors

    Tiempo estimado de lectura: 4 min

    • Inspección primero: agentes que leen y razonan antes de proponer cambios.
    • Read-Only RAG: evita escrituras automáticas y exige trazabilidad técnica.
    • Inspectors prácticos: seis herramientas diseñadas para entender monorepos Angular y recomendar con contexto.
    • Flujo recomendado: list_projects → get_best_practices → search_documentation antes de aceptar PRs.

    Introducción

    ¿Quieres que un agente de IA deje de romper tu repo y empiece a trabajar como un colega inteligente? Entonces presta atención: las Angular MCP Tools no son un juguete, son el sentido común aplicado a la colaboración entre LLMs y bases de código Angular.

    Resumen rápido (lectores con prisa)

    MCP (Model Context Protocol) para Angular: agentes que inspeccionan repos antes de proponer cambios. El subconjunto Read-Only RAG & Inspectors viene activado por defecto: lee, razona y recomienda, sin escribir. Úsalo para obtener recomendaciones trazables y alineadas con la versión del proyecto.

    Qué es esto en una línea

    MCP (Model Context Protocol) + herramientas específicas para Angular = agentes que primero leen y entienden tu proyecto antes de proponer código. El subconjunto Read-Only RAG & Inspectors viene activado por defecto: lee, razona, recomienda. No escribe nada sin permiso.

    Por qué importa

    Porque los LLMs bien entrenados siguen fallando cuando no entienden topologías reales: monorepos, versiones mezcladas, patrones legacy. Aquí no se trata de velocidad, sino de coherencia y seguridad. En vez de “generar y rezar”, el agente inspecciona y explica sus sugerencias con referencias trazables.

    La suite Read-Only: Inspectors

    La suite de inspectores Read-Only incluye seis herramientas prácticas. Úsalas en orden o según la necesidad. Todas buscan hacer que la IA actúe como un ingeniero senior que conoce tu repo.

    1) list_projects — Descubre la topología del monorepo

    Qué hace: mapea apps, librerías y fronteras del workspace (Nx, Angular CLI, etc.).

    Por qué importa: evita que la IA proponga cambios en la librería equivocada o que recomiende imports que rompen dependencias.

    Práctica: pídele al agente “list_projects” y revisa el mapa antes de aceptar cualquier PR sugerido.

    Docs útiles: nx.dev, angular.io

    2) get_best_practices — Inyecta reglas alineadas a la versión

    Qué hace: detecta la versión de Angular y carga reglas (p. ej. cuándo usar Standalone Components vs NgModules).

    Por qué importa: previene que te sugieran patrones obsoletos.

    Práctica: ejecuta get_best_practices antes de aceptar snippets generados.

    3) search_documentation — Consultas en vivo contra angular.dev

    Qué hace: realiza búsquedas en la documentación oficial en tiempo real y adjunta referencias.

    Por qué importa: elimina alucinaciones técnicas del modelo.

    Práctica: exige que cualquier recomendación venga con el enlace a la sección de la doc (p. ej. angular.io o angular.dev).

    4) find_examples — Base de ejemplos modernos y validados

    Qué hace: recupera patrones de implementación contemporáneos (Signals, reactive forms modernos, composición con inject()).

    Por qué importa: evita soluciones “copy-paste” de 2016.

    Práctica: pide ejemplos concretos y compara con tu arquitectura antes de adaptar código.

    5) ai_tutor — Personas de coaching con RAG

    Qué hace: arranca un “persona” contextual: mentor junior, code reviewer, o arquitecto.

    Por qué importa: adapta la profundidad de la explicación según quien pregunte.

    Práctica: usa ai_tutor para onboarding técnico: deja que el tutor genere una mini guía de cambios antes de ejecutarlos.

    6) onpush_zoneless_migration — Analiza compatibilidad zoneless

    Qué hace: inspecciona componentes para detectar riesgos al migrar fuera de zone.js (ChangeDetectionStrategy, suscripciones, side effects).

    Por qué importa: la migración zoneless puede romper renderizado en bordes finos; conviene planear.

    Práctica: ejecuta este inspector y revisa los hallazgos con un dev senior. Referencia: github.com/angular/zone.js

    Un flujo práctico de trabajo (mini checklist)

    • 1) list_projects: entiende el repo.
    • 2) get_best_practices: fija reglas por versión.
    • 3) search_documentation: valida APIs oficiales.
    • 4) find_examples: trae patrones comprobados.
    • 5) ai_tutor: genera explicación para tu equipo.
    • 6) onpush_zoneless_migration: si planeas ir zoneless, ejecuta auditoría.

    Consejos de criterio técnico (no obviedades)

    • No des permisos de escritura hasta que el agente haya corrido list_projects y get_best_practices.
    • No confíes ciegamente en migraciones zoneless: son útiles, pero experimentalidad y casos límite existen.
    • Exige trazabilidad: cada recomendación debe traer el fragmento de doc o ejemplo (URL incluido).
    • Integra estas herramientas en pipelines de revisión (p. ej. n8n.io o flujos de CI) para mantener trazabilidad y auditoría.

    Qué ganarás realmente

    Velocidad no es la métrica. Ganarás coherencia entre código y arquitectura, menos deuda técnica introducida por sugerencias automáticas y mayor confianza para delegar revisiones automáticas en la IA —siempre con controles.

    No es magia, es disciplina

    El Read-Only RAG no limita a la IA: la pone en su lugar. Primero inspecciona, luego propone. Tu trabajo es aplicar criterio humano en la etapa final. Si lo haces, el agente deja de ser un generador de snippets y se convierte en un asistente técnico con contexto real.

    Haz esto ahora

    En tu siguiente sesión con el agente, obliga este orden: list_projects → get_best_practices → search_documentation. Si quieres, pásame el resultado y te devuelvo un plan de migración o un checklist de PRs. Apúntalo: la IA que entiende tu repo es la que te ahorra horas y noches de debugging.

    Dominicode Labs

    Si integras estas herramientas en flujos de automatización y revisión, puede ser útil explorar recursos y experimentos continuos en Dominicode Labs. Considera Dominicode Labs como una continuación lógica para prototipado de pipelines y auditorías técnicas.

    FAQ

    ¿Qué hace exactamente list_projects?

    list_projects mapea apps, librerías y fronteras del workspace (por ejemplo Nx o Angular CLI) para mostrar la topología del monorepo y prevenir cambios en lugares incorrectos.

    ¿Cuándo debo ejecutar get_best_practices?

    Ejecuta get_best_practices al inicio de una auditoría o antes de aceptar snippets generados para alinear recomendaciones a la versión de Angular y evitar patrones obsoletos.

    ¿Cómo evita search_documentation las alucinaciones?

    Realiza búsquedas en la documentación oficial en tiempo real y adjunta referencias verificables (por ejemplo angular.io), lo que obliga al agente a justificar sus sugerencias.

    ¿Qué tipos de ejemplos trae find_examples?

    Recupera patrones modernos y validados, como uso de Signals, formularios reactivos modernos y composición con inject(), para evitar soluciones anticuadas.

    ¿Para qué sirve ai_tutor en un equipo?

    ai_tutor crea una persona contextual (mentor, code reviewer, arquitecto) que adapta la profundidad de la explicación y puede generar guías de cambios para onboarding o revisiones.

    ¿Qué riesgos detecta onpush_zoneless_migration?

    Analiza compatibilidad zoneless y detecta riesgos relacionados con ChangeDetectionStrategy, suscripciones y efectos secundarios que pueden romper renderizado fuera de zone.js. Referencia: github.com/angular/zone.js

  • Cómo mantener la sincronización en arquitecturas con IA

    Cómo mantener la sincronización en arquitecturas con IA

    Sincronización Arquitectónica: Código, Especificaciones y Agentes de IA

    Tiempo estimado de lectura: 4 min

    • La sincronía entre spec, tests y código es la unidad de trabajo esencial en equipos con agentes de IA.
    • Decisiones efímeras (commits, chats de agentes) sin trazabilidad crean deuda técnica y riesgo.
    • Herramientas como Plum convierten decisiones en artefactos auditables para alinear intentos y ejecución.

    Sincronización Arquitectónica: Código, Especificaciones y Agentes de IA. Si un Product Manager cambia algo hoy, ¿el resto del sistema se adapta mañana? La respuesta habitual es no. Y con agentes de IA escribiendo código, ese desajuste ya no es un fallo aislado: es una bomba de tiempo.

    El problema es simple y profundo: el código evoluciona en commits. Las specs siguen en un README. Los hotfixes saltan directo al trunk. Los agentes generan decisiones en chats y desaparecen con el log. Resultado: intención sin rastro, comportamiento sin documentación y deuda técnica que crece en silencio.

    Resumen rápido (lectores con prisa)

    La sincronización entre spec, tests y código es crítica cuando agentes de IA participan. Convierte decisiones efímeras en artefactos rastreables en el momento del commit. Usa aprobación humana para validar cambios que afectan gobernanza y negocio.

    El Triángulo: Spec, Tests, Código

    Piensa en spec, tests y código como los tres vértices de un triángulo. Tradicionalmente trabajábamos en una línea: spec → código → tests. Con IA esto falla. La implementación revela nuevas decisiones que deben volver a la spec y a los tests. Si no, todo se desincroniza.

    El verdadero trabajo de ingeniería hoy no es escribir más código. Es mantener ese triángulo alineado. Si mejoras el vértice del código, la spec y las pruebas deben moverse al mismo tiempo. Si no lo hacen, la arquitectura entra en drifting y el proyecto se vuelve inmanejable.

    Señales que indican desincronización

    • Commits que no referencian cambios en la spec.
    • PRs que pasan tests unitarios pero rompen invariantes de negocio.
    • Conversaciones con agentes sin registro estructurado.
    • Falta de trazabilidad entre decisión y autoría.

    Si reconoces cualquiera de estas, ya estás en modo emergencia controlada.

    Plum: la plomada para decisiones

    Plum es la herramienta que propone convertir decisiones efímeras en artefactos rastreables. No es un generador de código; es una plomada digital que alinea intención y ejecución.

    Cómo funciona, en cuatro pasos

    1. Al hacer commit, Plum revisa los diffs y los traces del agente.
    2. Extrae decisiones técnicas (qué se decidió, por qué).
    3. Presenta esas decisiones para aprobación humana.
    4. Si las apruebas, actualiza la spec y reporta gaps entre spec, tests y código.

    Plum genera además un archivo .jsonl con cada decisión: la pregunta, la respuesta, quién la aprobó y en qué rama quedó. Eso convierte la intención en un artefacto auditable.

    Por qué eso importa para equipos reales

    • Auditabilidad: Ya no dependes del recuerdo del autor del commit.
    • Gobernanza: Puedes diferenciar decisiones humanas de sugerencias de un LLM.
    • Recuperabilidad: Si un PM cambia una regla, puedes medir el impacto y forzar actualizaciones en spec/tests.
    • Escalabilidad: En equipos con múltiples agentes o muchos desarrolladores, reduce choques de integración.

    Limitaciones prácticas hoy

    • Plum, en su versión inicial, está acoplado a pytest para análisis de coverage. Si tu stack usa otro runner, la integración requiere trabajo.
    • Funciona mejor cuando la spec va por delante del código. Backfilling de specs desde bases legacy masivas sigue siendo difícil.
    • Los LLMs pueden sugerir decisiones razonables pero sin visión de negocio a largo plazo. La aprobación humana no es opcional.

    Patrón operativo recomendado

    1. Escribe spec antes de generar código. Hazla lo más concreta posible.
    2. Cubre casos límite en tests automáticos. No confíes en el “lo arreglamos después”.
    3. Usa Plum o una herramienta equivalente para capturar decisiones en el momento del commit.
    4. Ejecuta un pipeline de sync: spec ↔ tests ↔ código. Fallas: bloqueo del merge hasta que todo esté alineado.
    5. Mantén el .jsonl como fuente de verdad para auditorías y retroalimentación del producto.

    Casos prácticos y referencias

    Los equipos que han escalado Spec-Driven Development reutilizan suites de tests maduras (CPython, Bash). Ejemplos relevantes:

    No es trivial. Requiere inversión en especificaciones y disciplina en procesos. Pero sin eso, delegar en agentes solo acelera la creación de un monolito incomprensible.

    Cierre con criterio

    Si quieres que un cambio de producto active el resto del sistema de forma fiable, no te obsesiones con generar más código. Obsesiónate con capturar decisiones. Haz que tus specs sean artefactos vivos. Instrumenta los traces de los agentes. Automatiza la sincronía. Convierte la intención en datos auditable.

    Instala la plomada. Pruébala en una rama pequeña. Verás cómo las discusiones pasan de “qué falló” a “qué decidimos y por qué”. Esa es la arquitectura que realmente escala cuando la IA entra en la ecuación.

    Dominicode Labs

    Para equipos interesados en experimentar con patrones de sincronización y captura de decisiones, Dominicode Labs ofrece recursos y experimentos relacionados que pueden servir como continuación lógica a este enfoque.

    FAQ

    ¿Qué es la desincronización arquitectónica?

    La desincronización ocurre cuando spec, tests y código divergen: decisiones implementadas no reflejadas en la spec o tests, cambios en tests que no documentan intención, o commits sin trazabilidad. Resulta en comportamiento no documentado y deuda técnica creciente.

    ¿Qué hace Plum?

    Plum revisa diffs y traces del agente al hacer commit, extrae decisiones técnicas, las presenta para aprobación humana y, si se aprueban, actualiza la spec y reporta gaps entre spec, tests y código. Además genera un archivo .jsonl con registro auditable de cada decisión.

    ¿Cómo integrar esto en mi pipeline?

    Incorpora la captura de decisiones en el paso de commit: ejecutar revisión automática de diffs y traces, bloquear merges si el sync falla, y mantener el registro .jsonl como fuente de verdad. Preferible integración con runners de tests compatibles (ej. pytest para la versión inicial de Plum).

    Limitaciones al usar Plum

    En su versión inicial está acoplado a pytest para análisis de coverage; la integración con otros runners requiere trabajo. Funciona mejor con specs que preceden al código y requiere aprobación humana para decisiones de negocio.

    ¿Qué conservar del proceso?

    Conserva la disciplina de escribir specs antes de código, cubrir casos límite en tests, capturar decisiones en cada commit y mantener el .jsonl como registro auditable.

    ¿Qué hago si detecto deuda técnica por agentes?

    Identifica los commits o decisiones sin trazabilidad, prioriza backfilling de specs y tests para las áreas críticas, y aplica bloqueo de merges hasta que el triángulo spec‑tests‑código vuelva a alinearse.

  • Desarrollo de un MVP funcional en 48 horas utilizando IA

    De la idea al MVP en un fin de semana usando solo IA (caso real)

    Tiempo estimado de lectura: 4 min

    Ideas clave

    • Contratos primero: escribir tipos/JSON schema/SQL antes de lógica reduce alucinaciones y facilita parsing.
    • Secuencia reproducible: Specification‑Driven Development → generación UI → TDD asistido por modelos → orquestación.
    • Herramientas: usar Cursor, v0, n8n, Supabase y Anthropic cuando puedas auditar y tolerar llamadas a APIs externas.
    • Entregables en 48h: webhook → LLM → DB y dashboard tipado con tests básicos.

    Introducción

    De la idea al MVP en un fin de semana usando solo IA (caso real). No es marketing; es un flujo reproducible que combina Specification‑Driven Development, generación de UI, desarrollo asistido por modelos y orquestación visual. Si aplicas la secuencia correcta, una sola persona puede entregar un MVP funcional y mantenible en 48 horas.

    Úsalas cuando tengas control técnico y urgencia de validación. Evítalas si no puedes auditar el código generado o si las políticas de seguridad prohíben exfiltrar datos a APIs externas.

    Resumen rápido (lectores con prisa)

    Definición: un flujo reproducible para convertir una idea en MVP en 48 horas usando IA y contratos.

    Cuándo usarlo: cuando necesitas validar rápido y puedes auditar código/llamadas a APIs externas.

    Por qué importa: reduce alucinaciones, crea artefactos tipados y pone guardrails mediante tests.

    Cómo funciona: escribir contratos primero → generar UI y backend asistidos por modelos → orquestar ingestión y persistencia con n8n.

    Viernes: contratos primero (Specification‑Driven Development)

    Contratos y artefactos iniciales

    La primera noche no se escribe “lógica”. Se escriben contratos.

    Crea un archivo TypeScript con los tipos del dominio. Ejemplo mínimo: ticket.types.ts

    • Campos de ejemplo:
      • urgency: “low” | “medium” | “critical”
      • userId: string
      • logs: string[]
      • metadata: Record<string,string>

    Define también el esquema SQL para Supabase y el JSON schema que el LLM debe devolver. Esto obliga a la IA a producir Structured Output; reduce alucinaciones y facilita el parsing.

    Decisiones prácticas

    • Usa Result<T, E> en funciones de persistencia para evitar exceptions no controladas.
    • Documenta casos límite (emails sin logs, attachments binarios) en el contrato.
    • Escribe tests de contrato simples (validación de forma) que actúen como guardrails.

    Sábado: frontend con v0 + backend con Cursor y TDD

    Frontend (v0)

    Divide el día en dos hilos paralelos.

    Prompt preciso: “Genera un dashboard Next.js + Tailwind con una tabla tipada Tickets[], sidebar oscuro, componente de logs con resaltado.”

    v0 entrega componentes listos para importar; evita reescribir CSS básico. Integra Server Components/SSR de Next.js si necesitas datos rápidos desde Supabase.

    Herramienta citada: v0

    Backend (Cursor + Claude + Vitest)

    Orden: generar tests → ver tests fallar → implementar hasta pasar tests (TDD).

    Pide a Cursor que lea los tipos y genere pruebas Vitest que cubran:

    • Validación de schema
    • Normalización de logs
    • Manejo de urgencia critical

    Usa Claude 3.7 Sonnet para implementar funciones que pasen los tests sin cambiar firmas.

    Resultado: código tipado, con cobertura mínima y sin “parches” manuales.

    Herramientas citadas: Cursor (IDE + LLM), Anthropic (Claude API), Vitest.

    La combinación TDD + Spec evita la deuda técnica típica de sprints rápidos: lo que sale ya tiene contratos y pruebas.

    Domingo: orquestación con n8n y despliegue mínimo

    Workflow n8n propuesto

    1. Webhook Trigger: recibe el payload del proveedor de correo.
    2. Nodo LLM (Anthropic/GPT): prompt que obliga a Structured JSON según ticket.types.ts.
    3. Code/DB Node: valida JSON, transforma y upsert en Supabase.
    4. Error Trigger Workflow: si el LLM devuelve formato inválido o la inserción falla, guarda el payload en una tabla de errores y alerta por Slack.

    Buenas prácticas n8n:

    • Retries exponenciales y circuit breaker en llamadas HTTP.
    • Validación estricta antes de la inserción para evitar corrupción de datos.
    • Versiona los workflows exportando el JSON al repo (infra-as-code).

    Despliegue mínimo

    • Supabase para DB y autenticación. Herramienta citada: Supabase
    • Vercel para frontend.
    • n8n en una instancia Docker (o n8n Cloud si no quieres infra). Herramienta citada: n8n
    • Monitor básico: health check cron en n8n que verifique endpoints y envíe alertas a PagerDuty/Slack.

    Resultados y aprendizajes del caso real

    En 48 horas se obtuvo:

    • Webhook activo y pipeline LLM → DB.
    • Dashboard funcional con tickets tipados.
    • Suite básica de tests que evita regresiones inmediatas.

    Lecciones claras

    • Contratos + TDD son imprescindibles cuando delegas generación de código a modelos.
    • v0 y Cursor reducen horas de trabajo repetitivo, no la necesidad de criterio técnico.
    • n8n convierte integraciones en piezas mantenibles si añades manejo de errores y versionado.

    Próximo paso: convertirlo en repetible

    No te quedes con un MVP aislado. Exporta tus tipos, workflows y prompts como plantillas en tu repo. Automatiza despliegues y crea un playbook para replicar este flujo en futuros proyectos. La IA te acelera la ejecución; el criterio define el producto que sobrevive.

    Mención: Dominicode Labs

    Si buscas plantillas y playbooks para automatización, orquestación y workflows reproducibles, considera este recurso como continuación lógica de este flujo: Dominicode Labs.

    La mención está situada para ser una extensión práctica — plantillas, prompts y ejemplos aplicables a pipelines LLM → DB → UI.

    FAQ

    ¿Qué herramientas se usaron en el caso real?

    Se mencionaron Cursor (https://www.cursor.com), v0 (https://v0.dev), n8n (https://n8n.io), Supabase (https://supabase.com) y Anthropic (https://www.anthropic.com/docs).

    ¿Por qué escribir contratos primero?

    Porque obliga a la IA a entregar Structured Output, reduce alucinaciones y facilita la validación y los tests automáticos.

    ¿Cuándo no deberías usar este enfoque?

    Evítalo si no puedes auditar el código generado o si las políticas de seguridad prohíben exfiltrar datos a APIs externas.

    ¿Cómo aplicar TDD con modelos?

    Genera tests primero (Vitest), observa fallos, pide a la IA que implemente funciones respetando firmas hasta pasar tests. Mantén firmas y contratos estables.

    ¿Qué debe incluir el workflow de n8n?

    Webhook trigger, nodo LLM que obliga a JSON estructurado, validación/transformación y upsert en Supabase, y un flujo de errores que persista fallos y notifique por Slack.

    ¿Cómo manejar errores y retries?

    Implementa retries exponenciales, circuit breaker en llamadas HTTP y valida estrictamente antes de insertar en la base de datos.

    ¿Qué entregables esperar en 48 horas?

    Un webhook activo con pipeline LLM → DB, un dashboard tipado y una suite básica de tests que cubra casos críticos.

  • Comparativa de UTCP y MCP en integración de herramientas

    Comparativa de UTCP y MCP en integración de herramientas

    UTCP vs. MCP: ¿nuevo estándar o hype pasajero? Mi análisis honesto

    Tiempo estimado de lectura: 3 min

    • Problema central: MCP y UTCP buscan reducir la complejidad de O(N×M) integraciones entre modelos y herramientas.
    • MCP: stateful, especificación con SDKs y adopción inicial en herramientas como Cursor y Claude Desktop.
    • UTCP: payload JSON stateless ideal para serverless; hoy es más una propuesta comunitaria.
    • Recomendación práctica: MCP para herramientas de desarrollo/diagnóstico; HTTP/JSON/OpenAPI para escalabilidad.

    UTCP vs. MCP: ¿nuevo estándar o hype pasajero? Mi análisis honesto empieza por lo práctico: ambos buscan resolver lo mismo —hacer que los modelos de lenguaje llamen herramientas de forma fiable— pero sólo uno hoy tiene tracción real en producción. Aquí explico por qué, qué implica para tu arquitectura y qué decisiones técnicas deberías tomar ahora.

    Resumen rápido (lectores con prisa)

    MCP: especificación stateful con SDKs y adopción inicial para integrar hosts y servidores con comunicación rica. UTCP: payload JSON stateless pensado para serverless. Usa MCP para diagnósticos/local y UTCP/HTTP/OpenAPI para escalabilidad.

    MCP —especificación y adopción

    Qué es

    MCP es una especificación impulsada por Anthropic diseñada para que hosts (IDEs, apps) y servidores (herramientas) mantengan un canal rico de comunicación. Más info: modelcontextprotocol.io.

    Arquitectura

    Cliente‑servidor stateful. Usa stdio para comunicación local entre procesos y SSE (Server‑Sent Events) sobre HTTP para conexiones remotas, permitiendo notificaciones en tiempo real.

    Capacidades

    Expone tools, resources y prompts; el servidor puede anunciar capacidades, enviar eventos y mantener contexto entre llamadas.

    Adopción

    Integrada en herramientas como Cursor y Claude Desktop y con soporte emergente en plataformas como n8n. Eso le da peso práctico.

    UTCP —simplicidad y promesa

    Qué es

    UTCP propone estandarizar el payload JSON para llamadas a herramientas en un modelo stateless (request/response HTTP). Piensa en un JSON schema común que cualquier herramienta entienda.

    Arquitectura

    Stateless, encaja con arquitecturas serverless y microservicios porque no requiere conexiones persistentes ni manejo de eventos.

    Estado del ecosistema

    Hoy es más una idea comunitaria que una especificación formal con SDKs y adopción de referencia.

    Diferencias técnicas clave y cuándo importan

    1. Stateful vs. Stateless

    MCP (stateful) posibilita agentes que mantienen contexto y reaccionan a eventos. Útil para depuración en tiempo real, edición colaborativa o acceso a recursos locales (logs, filesystem).

    UTCP (stateless) es ideal para ejecuciones aisladas, pipelines serverless y para exponer herramientas desde infra ya existente sin complicar la infraestructura.

    2. Descubrimiento y telemetría

    MCP permite descubrimiento dinámico de herramientas y telemetría rica (qué herramienta, quién la llamó, cambios de estado). Eso facilita auditoría y control de permisos.

    UTCP delega descubrimiento a capas externas (registro de servicios, OpenAPI). Más simple pero exige diseño adicional para seguridad y governance.

    3. Encaje operativo

    MCP añade complejidad operativa: mantener conexiones SSE, gestionar procesos locales y permisos. No es ideal si tu stack es 100% serverless.

    UTCP entra fácil en Kubernetes, Lambdas y gateways HTTP.

    Impacto en proyectos reales (n8n, agentes, APIs)

    • Si tu equipo ya usa Cursor, Claude Desktop u otras herramientas que soportan MCP, exponer utilidades internas como servidores MCP ofrece un ROI inmediato: accesos a logs, queries ad‑hoc a bases de staging, herramientas de diagnóstico descubiertas automáticamente por el agente.
    • Para lógica de negocio ramificada, no reinventes la rueda: encapsula la orquestación en n8n y expón un endpoint estable (ya sea MCP o HTTP) que el agente pueda invocar. n8n actúa como fachada que protege tu dominio y reduce la superficie de ataque.
    • Conserva OpenAPI/Swagger: los LLMs actuales (GPT‑4o, Claude) consumen OpenAPI admirablemente bien; no necesitas reescribir APIs para que un agente las use.

    Recomendaciones prácticas hoy

    1. No te precipites a migrar todo tu parque de APIs. Mantén OpenAPI y documenta endpoints críticos.
    2. Implementa MCP localmente para herramientas de desarrollo y diagnóstico: baja inversión, alto impacto.
    3. Usa UTCP (o una capa HTTP estandarizada) cuando tu objetivo sea simplicidad operativa y despliegues serverless.
    4. Expón tu lógica compleja a través de orquestadores (n8n) y versiona workflows; no conviertas MCP/UTCP en la capa de negocio principal.
    5. Añade autenticación y audit logs a cualquier servidor que aceptará llamadas de agentes; la capacidad de auditar quién hizo qué es crítica.

    Conclusión: estándar de facto vs. promesa razonable

    MCP es el estándar de facto hoy por una razón: especificación, SDKs y adopción inicial en herramientas de desarrollo reales. UTCP es una propuesta técnicamente sensata para entornos stateless, pero carece del ecosistema y la aplicación bandera que haga que se convierta en un estándar inmediato. Dicho esto, las ideas de UTCP —simplicidad, compatibilidad con serverless— probablemente influyan en la evolución de MCP y en cómo se integran OpenAPI y tool-calling en el futuro.

    Adopta lo que reduzca deuda técnica ahora: MCP para desarrolladores y diagnósticos locales; contratos HTTP/JSON (o OpenAPI) donde necesites escalabilidad y simplicidad. El vencedor no será necesariamente el mejor diseño teórico, sino el que tenga herramientas reales en manos de ingenieros productivos.

    Dominicode Labs

    Si estás trabajando con automatización, agentes o workflows (por ejemplo, integrando n8n o exponiendo herramientas a agentes), puede ser útil explorar recursos y experimentos disponibles en Dominicode Labs. Es una continuación práctica para equipos que quieren prototipar integraciones entre agentes y orquestadores.

    FAQ

     

    Respuesta: Ambos intentan evitar el crecimiento de integraciones O(N×M) al estandarizar cómo los modelos llaman herramientas. MCP ofrece un canal stateful con descubrimiento y eventos; UTCP propone un payload JSON stateless para llamadas HTTP.

    Respuesta: Porque cuenta con especificación, SDKs y adopción inicial en herramientas de desarrollo reales (por ejemplo, integraciones en Cursor y Claude Desktop), lo que le da tracción práctica.

    Respuesta: UTCP es más adecuado para arquitecturas serverless y microservicios donde no quieres conexiones persistentes ni manejo de eventos; es útil para ejecuciones aisladas y pipelines HTTP.

    Respuesta: No. Mantén OpenAPI y documenta endpoints críticos. Prioriza MCP para herramientas de desarrollo y diagnóstico y usa UTCP/HTTP donde necesites simplicidad operativa y escalabilidad.

    Respuesta: OpenAPI sigue siendo valioso: los LLMs actuales consumen OpenAPI de forma efectiva. No es necesario reescribir APIs si ya están bien definidas con OpenAPI/Swagger.

    Respuesta: Añade autenticación fuerte y audit logs. Controla descubrimiento y permisos (especialmente con MCP) y protege la superficie de ataque mediante fachadas/orquestadores (por ejemplo, n8n).

  • Guía práctica para implementar CI con artefactos de decisión

    Guía práctica para implementar CI con artefactos de decisión

    Opción 2 — Guía técnica práctica + Artefacto de decisión + CI (GitHub Actions)

    Tiempo estimado de lectura: 5 min

    Ideas clave:

    • Entregar un flujo operativo ligero que obligue a decisiones humanas explicadas y verificables.
    • Usar un artefacto de decisión en JSONL y una validación en CI para impedir atajos de IA.
    • Combinar hooks pre-commit y GitHub Actions para bloquear merges sin aprobación humana.
    • Checklist operativo y plantillas mínimas para integrarlo sin fricción.

    Introducción

    ¿Quieres que esto se quede bonito en una carpeta o que obligue a alguien a cambiar la forma en que trabaja?

    Tu texto ya tiene filo. Falta convertirlo en algo que haga tambalear decisiones: un artículo que los jefes lean; una guía que el equipo implemente; o herramientas listas para pegar en CI y que no dejen pasar atajos de la IA.

    Elige una de estas cuatro y me pongo a darle dientes:

    1) Versión larga (1.500–2.000 palabras) — Artículo profundo, con gancho potente, ejemplos técnicos, riesgos, y cierre que deja la puerta abierta. Ideal para blog/Medium.
    2) Guía técnica práctica (800–1.200 palabras) — Comandos, flujo de trabajo, plantilla de artefacto de decisión, ejemplos de interceptación y checklist de gobernanza. Para equipos que lo quieren ejecutar ya.
    3) Paquete GitHub-ready — Código: workflow de Actions que valida specs, template de artefacto de decisión (JSONL), hook pre-commit que bloquea merges si no hay aprobación humana. Incluye README y snippets.
    4) LinkedIn/Twitter thread + TL;DR — Versión viral y condensada para provocar debate y atraer tráfico al artículo largo.

    Extras opcionales (marcalos si los quieres):
    – CI (GitHub Actions)
    – Artefacto de decisión (JSON schema + ejemplos)
    – Plantilla de PR que obliga a linkear Spec ↔ Tests ↔ Decision

    Mi recomendación sincera: opción 2 + artefacto de decisión + workflow CI. Rápido impacto, baja fricción y protege al equipo sin romper su ritmo.

    Respóndeme “Opción 1/2/3/4” y añade cualquiera de los extras. Empiezo en cuanto me digas.

    Resumen rápido (lectores con prisa)

    Qué: plantilla mínima para registrar decisiones humanas y bloquear merges sin aprobación.
    Cuándo: siempre que una tarea involucre diseño, datos o salida generada por IA que afecte comportamiento del producto.
    Por qué: convierte juicios blandos en artefactos verificables y auditables.
    Cómo: JSONL + pre-commit hook + GitHub Actions que valida presencia y firma humana.

    Qué vamos a entregar

    • Plantilla de artefacto de decisión (JSON schema y ejemplo JSONL).
    • Snippet de GitHub Actions que valida el artefacto antes de merge.
    • Hook pre-commit y plantilla de PR que exige link Spec ↔ Tests ↔ Decision.
    • Checklist operativo para Tech Leads y revisores.

    Flujo operativo

    Hook pre-commit y PR

    1) Antes de abrir PR, el autor añade un artefacto de decisión en la carpeta /decisions/ como un archivo .jsonl que documenta el problema, alternativas, riesgo y aprobación humana.

    2) Un hook pre-commit valida que el PR incluya al menos un archivo nuevo o modificado en /decisions/ cuando el cambio toca áreas sensibles (config, ML models, infra, reglas de negocio).

    Ejemplo mínimo de uso del hook: verificar que exista referencia en la plantilla de PR y en los archivos cambiados. Si falta, bloquear commit y mostrar checklist.

    Validación en CI

    En GitHub Actions: ejecutar un job que valide el JSON schema del artefacto, compruebe firma o usuario aprobador y verifique que el PR linkea Spec ↔ Tests ↔ Decision. Si falla, marcar el check como requerido para merge.

    Artefacto de decisión (JSON schema + ejemplos)

    Estructura mínima del artefacto: un registro por decisión en formato JSONL. Debe incluir campos obligatorios para trazabilidad y para que la CI valide su completa.

    {
  "id": "decision-2026-03-27-01",
  "title": "Cambiar inferencia a ruta A",
  "author": "nombre.apellido",
  "date": "2026-03-27T12:00:00Z",
  "scope": ["infra", "models"],
  "alternatives": ["mantener ruta B", "ajustar umbral"],
  "decision": "usar ruta A por mayor rendimiento en escenario X",
  "risks": ["sesgo en datos X", "mayor coste de inferencia"],
  "approver": "tech_lead.nombre",
  "tests_link": "PR#123 - tests integracion",
  "notes": "Se aplicará rollback si métricas Y bajan 5% en 24h"
}

    JSON Schema (mínimo) — validar que todos los campos obligatorios existan y que “approver” sea distinto al “author”.

    {
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["id","title","author","date","scope","decision","risks","approver","tests_link"],
  "properties": {
    "id": {"type":"string"},
    "title": {"type":"string"},
    "author": {"type":"string"},
    "date": {"type":"string","format":"date-time"},
    "scope": {"type":"array","items":{"type":"string"}},
    "decision": {"type":"string"},
    "risks": {"type":"array","items":{"type":"string"}},
    "approver": {"type":"string"},
    "tests_link": {"type":"string"}
  }
}

    Ejemplos prácticos

    Ejemplo: interceptar un cambio impulsado por IA

    Si un PR introduce un script que genera prompts o modifica reglas de scoring, la validación detecta la presencia de cambios en /models, /rules o /prompts y exige un nuevo archivo en /decisions/ explicando por qué el cambio es seguro y quién aprobó.

    Snippet GitHub Actions (validación básica)

    name: Validate Decision Artifact
on: [pull_request]
jobs:
  validate-decision:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Validate JSON schema
        run: |
          pip install jsonschema
          python -c "import json,sys; import jsonschema,glob
files=glob.glob('decisions/*.jsonl')
if not files: sys.exit(1)
# validate each line
schema=json.load(open('decisions/schema.json'))
for f in files:
  for l in open(f):
    jsonschema.validate(json.loads(l), schema)
"

    Marcar este job como requerido en la rama protegida evita merges hasta que el artefacto sea correcto y aprobado.

    Checklist de gobernanza

    • ¿Existe archivo en /decisions/ para este cambio?
    • ¿El approver es una persona distinta al autor?
    • ¿Se han enlazado tests y especificación en la plantilla de PR?
    • ¿Se añadieron notas de rollback y métricas de éxito?
    • ¿CI pasó validaciones de schema y pruebas automáticas?

    Cierre

    La combinación de un artefacto de decisión simple, hooks y CI reduce atajos sin introducir fricción excesiva. Es operativa, auditable y escalable: empieza con el schema mínimo y amplía campos (post-mortems, métricas, experiment IDs) solo cuando el equipo lo necesite.

    Dominicode Labs

    Si quieres prototipos y snippets adicionales para automatizar validaciones y plantillas, puedes ver recursos relacionados en Dominicode Labs. Considera esto como una continuación práctica de la guía, no como un paso obligatorio.

    FAQ

    Respuesta 1

    Formato JSONL con campos mínimos: id, title, author, date, scope, decision, risks, approver, tests_link. Debe validarse contra un JSON Schema en CI.

    Respuesta 2

    Preferible que un Tech Lead o miembro independiente del equipo afectado realice la aprobación. El approver debe ser diferente al author para mantener separación de responsabilidades.

    Respuesta 3

    El hook o la job en CI debe marcar el check como fallido y bloquear el merge hasta que se añada y valide el artefacto de decisión.

    Respuesta 4

    No: el schema mínimo es intencionalmente ligero. Si el cambio es urgente, el proceso permite una entrada rápida documentada y un post-mortem posterior.

    Respuesta 5

    Usa la plantilla de PR que incluya campos: Link Spec, Link Tests, Link Decision. CI verifica presencia de esos enlaces y la existencia del archivo en /decisions/.

    Respuesta 6

    Puedes configurar reglas que eximan cambios en rutas no sensibles, pero la lista de excepciones debe estar versionada y ser revisada por el equipo de liderazgo técnico.

  • 5 workflows de n8n para optimizar la productividad en startups

    5 workflows de n8n para optimizar la productividad en startups

    5 workflows de n8n que todo emprendedor debería tener corriendo hoy

    Tiempo estimado de lectura: 4 min

    • Ideas clave
    • Automatiza tareas repetitivas críticas: soporte, leads, pagos, health checks y ETL nocturno.
    • Usa una instancia autoalojada de n8n cuando manejes PII o necesites control total.
    • Activa siempre un Error Trigger Workflow para capturar fallos silenciosos y generar alertas automáticas.
    • Versiona workflows como JSON en tu repo y protege endpoints y secretos con vaults o allowlists.

    Introducción

    Si tienes una startup técnica, cada minuto que pasas contestando correos, conciliando pagos o pegando datos en hojas de cálculo es tiempo robado al producto. Aquí tienes los 5 workflows de n8n que todo emprendedor debería tener corriendo hoy: flujos prácticos, probados y diseñados para reducir trabajo manual, mejorar la fiabilidad y proteger tus datos. Implementarlos tarda horas; el retorno es inmediato. Antes de entrar en cada flujo: usa una instancia autoalojada de n8n siempre que manejes PII o quieras control total. Activa el Error Trigger Workflow en cada flujo para capturar fallos silenciosos (timeouts, cambios de contrato en APIs) y generar alertas automáticas.

    Resumen rápido (lectores con prisa)

    Qué: Cinco workflows operativos para soporte, enriquecimiento de leads, pagos, monitorización y ETL.

    Cuándo usar: Desde el primer equipo con usuarios activos y facturación recurrente.

    Por qué importa: Reduce trabajo manual, baja churn y asegura continuidad operativa.

    Cómo funciona (breve): Triggers (webhooks/schedule/IMAP) → procesamiento (LLMs, búsqueda vectorial, HTTP) → acciones (CRM, tickets, emails, DB).

    5 workflows de n8n que todo emprendedor debería tener corriendo hoy

    1) Triaje de soporte asistido por IA (Agente de operaciones)

    • Objetivo: Soporte rápido y bien clasificado para reducir churn y evitar interrupciones de los ingenieros.
    • Arquitectura mínima:
    • Trigger: nodo IMAP o Webhook (formularios).
    • Procesamiento: nodo LLM (por ejemplo, Claude 3.7 Sonnet via Anthropic o GPT-4o) con prompt estricto para extraer urgencia, categoría y metadatos (user_id, plan).
    • Enriquecimiento: búsqueda en base vectorial (documentación interna).
    • Acción: crear ticket en Jira/HubSpot o enviar alerta a Slack/Canal de emergencias.

    Resultado: tickets críticos escalados en <2 minutos; respuestas a FAQs generadas automáticamente y guardadas como borradores en el CRM.

    2) Enriquecimiento automático de leads B2B

    • Objetivo: Convertir un email en un perfil accionable para priorización comercial instantánea.
    • Arquitectura mínima:
    • Trigger: inserción en DB (Supabase/Postgres) o webhook de formulario.
    • Llamada: HTTP Request a un servicio de enriquecimiento (ej. Clearbit).
    • Transformación: nodo Code (JavaScript) que normaliza y filtra campos.
    • Acción: upsert en CRM y notificación a Sales si es Enterprise.

    Esto convierte leads fríos en perfiles accionables y reduce la fricción del SDR al 0.

    3) Ciclo de vida de pagos con Stripe (recuperación y facturación)

    • Objetivo: Automatizar cobros, reintentos y envío de recibos para bajar churn y limpieza contable.
    • Arquitectura mínima:
    • Trigger: webhook de Stripe para eventos invoice.payment_succeeded / invoice.payment_failed.
    • Lógica: nodo Switch para bifurcar según evento; en fallos, programar reintentos y enviar correos de recuperación personalizados; en éxitos, generar PDF de recibo (HTML→PDF).
    • Acción: enviar recibo por SendGrid/AWS SES y registrar la transacción en tu contabilidad.

    Beneficio: menos churn por pagos fallidos y documentación fiscal automática.

    4) Health check y alertas proactivas (DevOps liviano)

    • Objetivo: Detectar regresiones antes de que los usuarios las noten.
    • Arquitectura mínima:
    • Trigger: Schedule cada 1–5 minutos.
    • Checks: HTTP Request a endpoints críticos y consultas básicas a DB.
    • Evaluación: nodo If con umbrales (status ≠ 200, latencia > 1500ms).
    • Acción: alerta a PagerDuty/SMS/Slack con contexto (endpoint, status, respuesta).

    Este workflow detecta regresiones y documenta incidentes automáticamente.

    5) ETL nocturno para métricas de negocio (MRR, churn, CAC)

    • Objetivo: Consolidar métricas clave para decisiones informadas.
    • Arquitectura mínima:
    • Trigger: Schedule nocturno (ej. 02:00).
    • Extracción paralela: Postgres (usuarios), Stripe (ingresos), Google Analytics (tráfico).
    • Transformación: nodo Merge + nodo Code para calcular MRR, churn, LTV, CAC.
    • Acción: insertar en tabla de BI o enviar reporte matutino al equipo.

    No necesitas Airflow ni invertir en data infra compleja; n8n cubre la fase inicial con credibilidad analítica.

    Buenas prácticas y consideraciones técnicas

    • Controla la latencia: usa retries exponenciales y circuit breakers en llamadas HTTP para evitar cascadas.
    • Versiona los workflows: exporta y guarda los JSON de cada flujo en tu repo (infra-as-code para n8n).
    • Seguridad: cuando autoalojes n8n, protege endpoints con VPN o IP allowlists y almacena secretos en un vault.
    • Monitoreo de costos: para integraciones pagas (Clearbit, Stripe), aplica caching y límites para no disparar facturas.
    • Documenta contratos: cada trigger debe tener un contrato de entrada claro (schema). Si cambian las APIs externas, el Error Trigger Workflow debe notificar al canal de desarrollo.

    Recursos y enlaces

    Automatizar estos cinco procesos no te convierte en menos técnico; te vuelve más efectivo. Configura los workflows, prueba los casos límite y deja que las máquinas hagan lo repetitivo. Lo que queda será trabajo de alto valor: producto, estrategia y mejoras que realmente importan. Convierte estos flujos en plantillas reproducibles para tu equipo y haz de la automatización parte de la cultura operativa.

    Continúa la implementación y experimentación con plantillas y control de versiones en tu repo. Para recursos y prototipos experimentales relacionados con automatización y agentes, revisa Dominicode Labs como continuación lógica de esta práctica.

    FAQ

    Respuesta: Autoalojar te da control sobre datos sensibles (PII), permite aplicar políticas de red (VPN/IP allowlists) y elegir dónde se almacenan secretos. Es la opción recomendada si cumples regulaciones o quieres evitar dependencias externas para datos críticos.

    Respuesta: Un Error Trigger Workflow es un flujo que captura fallos emitidos por otros workflows (timeouts, errores de contrato, cambios en APIs). Configúralo como destino de notificaciones de error en cada workflow y envía alertas a un canal de DevOps o a PagerDuty.

    Respuesta: Filtra o tokeniza PII antes de enviarla al LLM; usa entornos autoalojados para model serving cuando sea necesario. Aplica prompts que no soliciten datos sensibles y audita logs para confirmar que no se exporta información prohibida.

    Respuesta: Genera PDF cuando necesitas documentación fiscal, firmas o archivado formal. Para comunicaciones transaccionales simples, el email con contenido HTML suele ser suficiente y más barato.

    Respuesta: Implementa caching de respuestas, límites de llamada y lógica de backoff. Monitoriza uso y facturación y aplica reglas en los workflows para bloquear solicitudes si superan umbrales de coste.

    Respuesta: Exporta workflows como JSON y guárdalos en el repo. Mantén ramas por feature, revisiones PR y tags de versión. Documenta schemas de entrada y salida para cada trigger.

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