DOMINICODE

Category: Spec Driven Development

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

  • Cómo utilizar OpenSpec para documentar APIs de forma efectiva

    Cómo utilizar OpenSpec para documentar APIs de forma efectiva

    Qué es OpenSpec y como empezar a usarlo?

    Tiempo estimado de lectura: 4 min

    Ideas clave:

    • OpenSpec (típicamente OpenAPI) es un contrato interoperable para describir APIs RESTful en YAML o JSON.
    • Buenas especificaciones reducen errores, permiten generación de SDKs y mejoran el comportamiento de agentes IA.
    • Empieza con un openapi.yaml válido, centraliza esquemas en components/schemas y valida con linters en CI/CD.
    • Decide una única fuente de la verdad: la spec o el código; sincronízalos para evitar drift.
    • Usa herramientas como Spectral, openapi-generator, Orval y n8n para integrar la spec en tu stack.

    Tabla de contenidos

    ¿Quieres que tus APIs hablen claro con humanos, herramientas y agentes de IA? Entender qué es OpenSpec y como empezar a usarlo es el primer paso para dejar de parchear integraciones y empezar a diseñar sistemas que realmente escalan.

    Resumen rápido (lectores con prisa)

    OpenSpec (normalmente OpenAPI) es un contrato en YAML/JSON que describe endpoints, parámetros y respuestas. Usarlo permite generación de clientes, validación automática y que agentes IA descubran y llamen funciones. Empieza con un openapi.yaml, centraliza esquemas en components/schemas y valida con Spectral en CI/CD.

    Qué es OpenSpec (breve y sin rodeos)

    OpenSpec = OpenAPI (típicamente). Repositorio oficial: OpenAPI Spec repo.

    Es un estándar agnóstico al lenguaje para describir APIs RESTful en YAML o JSON. No es solo “documentación bonita”: es un artefacto interoperable que potencia generación de clientes, validación en CI/CD y, hoy en día, el comportamiento de agentes IA que realizan tool-calling.

    Si lo haces bien, reduces preguntas, errores y tiempo de debugging. Si lo haces mal, tus integraciones sufrirán en silencio.

    Por qué importa ahora (sí, de verdad)

    • Los modelos de lenguaje consumen especificaciones para descubrir capacidades y ejecutar llamadas: mejores especificaciones = agentes más útiles.

    • Herramientas como n8n pueden mapear rutas desde una OpenSpec y reducir el trabajo manual en flujos.

    • Generadores como openapi-generator o Orval crean SDKs y hooks tipados: menos errores y builds que fallan temprano.

    • Linters como Spectral te permiten bloquear cambios que rompan contratos en CI/CD.

    Si tu arquitectura usa automatizaciones, agentes o consumidores externos, OpenSpec deja de ser “opcional” y pasa a ser infraestructura.

    Cómo empezar a usar OpenSpec en 5 pasos prácticos

    1) Elige formato: YAML por defecto

    YAML es más legible en PRs, permite comentarios y evita ruido. JSON es válido, pero menos humano.

    2) Crea el archivo base openapi.yaml con metadatos

    Ejemplo mínimo:

    openapi: 3.1.0
info:
  title: API de Gestión de Usuarios
  version: 1.0.0
servers:
  - url: https://api.midominio.com/v1

    3) Modela endpoints y componentes reutilizables

    Centraliza esquemas en components/schemas. Usa operationId en cada operación: es la referencia estable que usan generadores y agentes.

    Ejemplo:

    paths:
  /usuarios:
    get:
      operationId: getUsuarios
      summary: Lista usuarios activos
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Usuario'

components:
  schemas:
    Usuario:
      type: object
      required: [id, nombre]
      properties:
        id:
          type: string
          format: uuid
        nombre:
          type: string

    4) Valida y lintea en CI/CD

    Instala Spectral y córrelo en tus pipelines:

    npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml

    Configura reglas propias para estilo y seguridad. Esto evita que la IA actúe sobre un contrato erróneo.

    5) Conecta la especificación a tu stack

    • n8n: importa la spec para mapear rutas en nodos HTTP.

    • Frontend: usa Orval para generar hooks React/Next o servicios Angular.

    • Backend: genera SDKs con openapi-generator.

    • Agentes IA: pasa el YAML como “capability file” al sistema prompt o úsalo con LangChain para que los agentes sepan qué funciones pueden invocar.

    Decisiones prácticas: cuándo autogenerar y cuándo escribir

    • Si tu API cambia rápido o es grande: genera la OpenSpec desde código fuente o desde un DSL (ej. TypeSpec de Microsoft TypeSpec). Mantener un YAML manual de miles de líneas es fuego lento.

    • Si tu API es estable y pequeña: editar manualmente puede ser más rápido y explícito.

    • Regla simple: la fuente de la verdad debe ser única. O el código genera la spec, o la spec manda al código. No ambos sin sincronización.

    Riesgos y límites a considerar

    • Verbosidad: OpenAPI 3.x puede crecer mucho. Divide specs por dominios si hace falta.

    • Ambigüedad semántica: un buen schema evita que agentes “adivinen” parámetros. Sé explícito con required, tipos y ejemplos.

    • Seguridad: nunca publiques specs con credenciales ni ejemplos sensibles.

    Herramientas clave (rápido)

    Si tu trabajo incluye automatización, agentes o workflows, puede interesarte explorar recursos adicionales en Dominicode Labs como una continuación práctica para integrar especificaciones en pipelines y agentes. La mención apunta a material y experimentos que complementan las prácticas aquí descritas.

    FAQ

    ¿Qué diferencia hay entre OpenSpec y OpenAPI?

    OpenSpec, en el uso común, suele referirse a la OpenAPI Specification (OAS). Es el estándar para describir APIs RESTful en YAML o JSON.

    ¿Debo usar YAML o JSON?

    YAML es preferible para edición humana y PRs por su legibilidad y soporte de comentarios. JSON es igualmente válido pero menos práctico para revisión manual.

    ¿Cómo integro Spectral en CI/CD?

    Instala la CLI (npm install -g @stoplight/spectral-cli) y añade un paso en tu pipeline que ejecute spectral lint openapi.yaml. Configura reglas para estilo y seguridad para bloquear merges que rompan contratos.

    ¿Cuándo genero la spec desde código?

    Cuando el API cambia rápido o es grande: generar la spec desde el código o desde un DSL evita drift y reduce la carga de mantenimiento manual.

    ¿Puedo usar la spec con agentes IA?

    Sí. Puedes pasar el YAML como “capability file” en prompts o usar frameworks como LangChain para que los agentes conozcan las funciones disponibles.

    ¿Qué evitar al publicar una spec?

    No publiques credenciales ni ejemplos con datos sensibles. Evita ambigüedades en tipos y required; sé explícito para que consumidores y agentes no adivinen.

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

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

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

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

    Tiempo estimado de lectura: 4 min

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

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

    Resumen rápido (lectores con prisa)

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

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

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

    Spec-First + TDD combina:

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

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

    Flujo operativo paso a paso

    1) Escribir la especificación (Spec)

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

    Ejemplo (feature-spec.md):

    Feature: applyDiscount(order, coupon)

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

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

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

    2) Generar esqueletos de tests que fallen (Red)

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

    Ejemplo breve (applyDiscount.test.ts):

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

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

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

    3) Implementación: el agente repara hasta verde

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

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

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

    Beneficios reales y medibles

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

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

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

    Aplica Spec-First + TDD cuando:

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

    No lo uses para:

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

    Buenas prácticas y guardrails

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

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

    Dominicode Labs

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

    FAQ

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

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

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

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

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

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

  • Cómo evitar problemas al pedir código a la IA sin especificaciones

    Cómo evitar problemas al pedir código a la IA sin especificaciones

    ¿Quieres velocidad o quieres un desastre bonito en producción?

    Tiempo estimado de lectura: 6 min

    • Ideas clave:
    • Pedir código antes de una spec convierte velocidad aparente en deuda técnica real.
    • La spec funciona como el “system prompt” del repositorio: contratos, reglas y criterios de aceptación evitan improvisaciones.
    • Procesos concretos —plan, contratos, red teaming, tests— transforman las respuestas rápidas de IA en soluciones sostenibles.
    • El rol senior evoluciona hacia guardián de límites y políticas, no solo autor de código.

    Poca gente dice esto en las charlas con café gratis: pedir código antes de dar contexto es como contratar a un pintor y no decirle qué pared. Va a pintar rápido. Va a quedar espectacular al principio. Y al primer olor a humo descubrirás que pintó sobre el sistema eléctrico.

    Resumen rápido (lectores con prisa)

    La IA genera código probables según datos y prompts. Sin una spec que defina objetivos, stack, contratos y criterios de aceptación, las soluciones serán rápidas pero frágiles. Escribe SPEC.md, publica contratos, exige plan y tests; audita con red teaming. Conserva disciplina para convertir velocidad en sostenibilidad.

    Poca gente habla de esto: la IA no entiende tu negocio

    Los modelos de lenguaje son máquinas de probabilidades. No entienden SLAs, ni GDPR, ni las peleas internas por usar Next.js o Svelte. Responden con lo más probable según su entrenamiento y tu prompt. Si no les das reglas, toman decisiones por ti. Decisiones elegantes, pero improvisadas. Y la improvisación no escala.

    Lo que pasa cuando pides código demasiado pronto

    No es teoría. Es patrón repetido en equipos que adoptan IA rápido y disciplina lenta:

    Demo brillante en 48 horas. Integración rota, tokens expuestos, tests que fallan en producción. Dos semanas de refactor para rescatar el proyecto.

    Síntomas concretos

    • Componentes gigantes que hacen todo: UI, llamadas HTTP, validaciones y cambios en la base de datos. Un archivo de 500 líneas que asusta.
    • Mezcla de librerías por impulso: Fetch aquí, Axios allá, una dependencia vieja que “funcionaba” en un tutorial.
    • Flujos automatizados (n8n, Zapier) que fallan ante el primer timeout porque nadie pensó en idempotencia.
    • Tests que existen pero no validan casos reales. O peor: pruebas que pasan porque la spec nunca fue clara.

    Alucinación arquitectónica: la versión elegante del desastre

    No es solo que la IA invente funciones. Inventará abstracciones. Te propondrá un patrón porque en sus datos aparece muchas veces. Puede recomendarte Event Sourcing para una app de encuestas. Te entregará un PR perfecto. Y tú, encantado, lo mergeas.

    Hasta que llega la primera incidencia. Hasta que un miembro nuevo del equipo abre ese PR y no entiende nada. La IA actúa con convicción. Por eso hace falta liderazgo humano que coloque límites.

    La spec: no es burocracia. Es supervivencia

    Quien sigue llamando a la spec “ese PDF que nadie lee” está mirando el problema con los ojos cerrados. En la era de la IA la spec es la única forma de que la creatividad de la herramienta aterrice donde debe.

    Piensa en la spec como el System Prompt del repositorio. No es un texto largo que nadie abre; es la brújula del proyecto. Contiene: objetivos, stack, reglas innegociables, modelos de datos, respuestas ante fallos, y criterios de aceptación.

    Si la IA fuera un barco y tu equipo fuera la tripulación, la spec es la brújula. Sin ella, el barco navega rápido y choca.

    Cómo evitar pedir código demasiado pronto (pasos concretos)

    No es magia. Es disciplina con sentido. Haz esto antes del primer commit generado por IA.

    1) Escribe el objetivo en una frase

    ¿Qué problema resuelve este módulo? ¿Qué NO debe hacer? Si no puedes decirlo en una frase, no lo pidas. La IA no lo adivina.

    2) Define el stack y las reglas innegociables

    Next.js 14 OK. No usar SSR en X páginas. No introducir nueva dependencia sin CVE-check. ¿Postgres o Mongo? ¿Monolito o microservicios? Quítale opciones a la IA para que deje de improvisar.

    3) Publica contratos antes que código

    Interfaces TypeScript, esquemas Prisma, OpenAPI. Si la IA tiene contratos, genera lógica que encaje. Si no los tiene, generará sutilezas que rompen todo.

    4) Exige plan antes de ejecución

    Pide un plan en pasos. Repite: plan. No “hazlo tú ahora”. Pide la lista de entregables, aprobala y luego ejecuta cada paso con prompts acotados.

    5) Red Teaming desde el minuto cero

    Pídele a la IA que sea adversaria: “Rompe este diseño.” “¿Qué falla con 10k req/s?” “¿Qué pasa si el proveedor OAuth cae 30s?” Esto saca a la luz cuellos de botella y casos límite.

    6) Testes y ejemplos junto al contrato

    Cada endpoint debe venir con payloads válidos e inválidos y tests de aceptación. Si la IA genera código sin tests que validen la spec, recházalo.

    7) Guarda la spec en el repo (no en Google Docs)

    SPEC.md, .cursorrules, spec.json. Ponlo en la raíz. Que sea lo primero que lea el agente cuando genere código.

    Plantilla mínima de SPEC.md (pégala ya)

    No la copies sin adaptar, pero ten algo así en la raíz del repo:

    • Título en una frase: Objetivo del módulo.
    • Stack aprobado: Next.js 14, Node 20, Postgres 15.
    • Reglas innegociables:
      • No exponer secretos en frontend.
      • Mutaciones por Server Actions.
      • Máximo 2 dependencias nuevas sin revisión de seguridad.
    • Contratos principales:
      • /api/users POST -> CreateUserRequest, CreateUserResponse (interfaces TypeScript)
      • DB: users (id uuid, email text unique, password_hash text)
    • Criterios de aceptación:
      • Test de integración que crea usuario y valida hash.
      • Tiempo máximo respuesta: 500ms en endpoint crítico.
    • Política de secretos: usar Vault, nunca env vars en texto plano.
    • Responsables: Tech Lead: @ana, Owner: @carlos.

    Prompts que funcionan (ejemplos directos)

    Un buen prompt = contexto + restricciones + output esperado.

    Malo: “Hazme un CRUD de users.”

    Bueno: “Te doy la spec (inserta SPEC.md). Genera: 1) Interfaces TS 2) OpenAPI para /api/users 3) Tests de integración con ejemplos válidos/ inválidos. No uses librerías externas para hashing. Tiempo de respuesta <500ms.”

    Divide el trabajo en sprints cortos y verificables

    • Sprint A: Modelo de datos + contratos + tests.
    • Sprint B: Endpoints críticos + seguridad.
    • Sprint C: Observabilidad y despliegue.

    Aprobar cada sprint antes de pasar al siguiente.

    El nuevo rol del Senior: faro y guardián, no solo coder

    Antes bastaba con saber la sintaxis. Hoy el valor está en definir límites, auditar reglas y decidir qué complejidad merece implementarse. El senior no codifica menos; decide mejor. Su trabajo es preguntarse: ¿esta solución respeta la spec? Si no, veto.

    Historias que sirven como espejo

    Junior + Copilot = demo en 48h. Producción = caos. Reescritura 3 semanas.

    Mismo caso con spec: plan en 2 días + Claude para contratos + Copilot para implementación respetando interfaces = demo en 48h. Integración estable. Diferencia: disciplina.

    Metáfora corta y pegadiza

    La spec es el embudo; la IA es la manguera. Sin embudo, el agua corre por todos lados. Con embudo, llega donde debe.

    Cuándo no necesitas spec rígida

    Sí, hay espacio para improvisar. Para generar mocks, para prototipos exploratorios o pequeñas refactors locales. Pero regla práctica: si tocas contratos (APIs, DB, auth, infra), necesitas spec. Punto.

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

    • ¿Existe SPEC.md en la raíz?
    • ¿Hay interfaces/contractos definidos?
    • ¿Hay reglas de seguridad básicas?
    • ¿El prompt pide tests y ejemplos?
    • ¿Se solicitó plan paso a paso y fue aprobado?

    Si respondes no a cualquiera, NO pidas código aún.

    Urgencia real: deuda técnica multiplica costes

    Cada PR aceptado sin spec es una apuesta. Adivina quién paga si pierde la apuesta: tu equipo. La deuda técnica no se desintegra con buenas intenciones. Se compone. Actuar ahora cuesta horas. Rehacer después cuesta semanas, o clientes.

    CTA simple y directo

    Haz esto en los próximos 60 minutos: crea SPEC.md en la raíz con las seis secciones mínimas que te di. Respóndeme con “Quiero la plantilla” y te la mando lista para pegar en tu repo.

    Cierre que no cierra (a propósito)

    Si sigues pensando que la IA es una varita mágica, es tu opción. Tienes otra: gobernarla. La spec es la forma más barata de gobernarla. No es cómoda. Es efectiva. Y esto no acaba aquí: si quieres, te doy la plantilla, un prompt maestro listo para Claude y un .cursorrules de ejemplo. Dime cuál quieres y te lo envío ahora. Tus commits —y tu equipo dentro de seis meses— lo agradecerán.

    Dominicode Labs

    Si trabajas con automatización, agentes o workflows y quieres ejemplos prácticos de especificaciones y .cursorrules, revisa los recursos disponibles en Dominicode Labs. Es una continuación lógica para equipos que buscan convertir experimentos rápidos en procesos repetibles y seguros.

    FAQ

    ¿Qué es una SPEC.md y por qué es necesaria?

    Una SPEC.md es un archivo en la raíz del repositorio que define objetivo, stack, reglas innegociables, contratos y criterios de aceptación. Es necesaria para alinear generación de código automática con las restricciones del negocio y evitar decisiones improvisadas que generen deuda técnica.

    ¿Cuándo puedo pedir código sin spec?

    Para prototipos exploratorios, mocks o pequeños refactors locales. Si el cambio afecta APIs, DB, auth o infra, siempre usar spec. Esa es la regla práctica del artículo.

    ¿Cómo garantizo que la IA respete los contratos?

    Publica interfaces TypeScript, OpenAPI o esquemas en el repo antes de pedir código. Exige tests que validen esos contratos y revisa que las implementaciones pasen los tests de integración definidos en la spec.

    ¿Qué contiene un criterio de aceptación sólido?

    Entradas y salidas esperadas, límites de rendimiento (ej. tiempo máximo 500ms), condiciones de error y tests de integración que validen el comportamiento en casos válidos e inválidos.

    ¿Quién debe ser responsable de la spec?

    Responsables claros: Tech Lead y Product Owner. En el ejemplo: Tech Lead: @ana, Owner: @carlos. Debe estar versionada en el repo y ser lo primero que lea cualquier agente automatizado.

    ¿Cómo auditar seguridad en dependencias sugeridas por IA?

    No introducir nuevas dependencias sin revisión de seguridad: CVE-check, análisis de licencia y una prueba mínima en entorno aislado. La spec puede imponer un máximo de dependencias nuevas sin revisión.