DOMINICODE

Category: Spec Driven Development

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