Tag: Spec Driven Development

  • Cómo especificar un agente SDD antes de su implementación

    Cómo especificar un agente SDD antes de su implementación

    SDD + Agentes: cómo especificar un agente antes de construirlo

    Tiempo estimado de lectura: 5 min

    Ideas clave

    • Especificar antes de construir: define flujos de decisión, límites de herramientas y condiciones de parada antes de programar.
    • SDD para agentes ≠ SDD tradicional: los agentes requieren specs que formalicen libertad, herramientas y puntos de escalado humano.
    • Tres bloques críticos: topología de decisión, contratos de herramienta con schemas y guardrails cuantificables.
    • La spec debe ser ejecutable: tests automatizados, simuladores de fallo y verificación en CI/CD.

     

    Introducción

    SDD + Agentes: cómo especificar un agente antes de construirlo — dilo antes de teclear. Si no documentas la caja de arena cognitiva del LLM, lo que construyas será frágil, caro y peligroso. La especificación no es burocracia: es la diferencia entre un experimento que explota y un servicio que vive en producción.

    En las primeras líneas: especificar un agente significa definir flujos de decisión, límites de herramientas y condiciones de parada antes de escribir una sola línea de código. Hazlo así y reduces bucles infinitos, facturas de API descontroladas y escrituras destructivas en tus bases.

    Resumen rápido (lectores con prisa)

    Qué es: Una spec agéntica formaliza topología de decisión, contratos de herramientas y condiciones de parada.

    Cuándo usarla: Antes de implementar agentes que razonan o que pueden tocar recursos críticos.

    Por qué importa: Evita comportamientos estocásticos dañinos, costes inesperados y fallos de integridad de datos.

    Cómo se aplica: Define un patrón operativo único, schemas de entrada/salida para cada tool, y guardrails cuantificables con telemetría y pruebas.

    Por qué SDD para agentes no es lo mismo que SDD tradicional

    En apps CRUD, spec = modelos de datos + endpoints + contratos. Un 404 es un fallo leve. Un agente sin spec puede intentar cien variaciones de la misma consulta SQL, escribir datos corruptos o invocar herramientas fuera de scope. Aquí falla la arquitectura, no el prompt.

    Los agentes razonan de forma estocástica. Por eso la spec debe formalizar:

    • Qué libertad tiene el agente en cada punto.
    • Qué herramientas puede tocar y cómo.
    • Cuándo debe pararse y llamar a un humano.

    Anthropic recomienda priorizar flujos orquestados sobre autonomía total para casos críticos (ver: Anthropic — Building effective agents). Toma nota: la industria no apuesta por “agentes libres” en producción sin guardrails.

    Tres bloques que debe cubrir tu spec agéntica

    1) Flujos de decisión: topología y patrón operativo

    Decide uno (y solo uno) de estos patrones por caso de uso:

    • Enrutamiento semántico: el LLM clasifica intenciones y delega a código determinista.
    • Máquina de estados orquestada: el LLM elige transiciones entre nodos predefinidos (n8n, LangGraph, XState).
    • Bucle ReAct autónomo: pensamiento-observación-acción libre (solo para experimentos controlados).

    No mezcles sin regla. Define explícitamente qué patrón rige cada intent/endpoint y por qué.

    2) Límites de herramientas (Tool Boundaries)

    Una herramienta para un agente no es un endpoint cualquiera. Tu spec de herramienta debe incluir, al menos:

    • Contrato de datos (Zod o JSON Schema). No aceptes “any”.
    • Descripciones semánticas por campo: guía al LLM sobre qué producir exactamente.
    • Precondiciones de uso: cuándo está permitido invocar la tool.
    • Protocolo de fallo: ¿autocorrección (con el error serializado), retry con backoff, usar valor por defecto o abortar y escalar?

    Ejemplo mínimo (JSON Schema + fallback):

    {
      "name": "createUser",
      "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" } }, "required": ["email"] },
      "description": "Crea un usuario. email debe ser un correo válido. No inferir dominios.",
      "precondition": "email provisto por usuario",
      "onError": { "strategy": "abort_and_escalate", "max_retries": 0 }
    }

    Si dejas el onError en blanco, el agente decidirá por su cuenta —y lo hará mal.

    3) Guardrails y condiciones de parada

    Los guardrails no son sugerencias; son límites numéricos y verificables:

    • Max Steps: 5–10 iteraciones razonables por sesión antes de forzar cierre.
    • Retries por herramienta: típicamente 1–3, con backoff y registro.
    • Presupuesto operativo: tokens máximos por ejecución y tiempo máximo (p. ej. 30s wall clock).
    • Reglas de escalado humano: por ejemplo, tres fallos consecutivos de la misma tool o confianza del modelo < 0.6 → escalar.

    Documenta esos números en la spec. Implanta telemetría que lo verifique en tiempo real.

    Ingeniería práctica: plantilla rápida para tu spec agéntica

    Un documento mínimo y accionable debe contener:

    1. Directiva principal (system prompt base, objetivo inmutable).
    2. Fronteras negativas (anti-prompts: qué nunca debe hacer el agente).
    3. Contrato de memoria (qué guarda la memoria episódica y qué va a la semántica, p. ej. pgvector).
    4. Matriz de herramientas (schema, descripciones, precondiciones, fallback).
    5. Criterios de interrupción y política de escalado humano.
    6. Tests de comportamiento (simulaciones de fallo: error DB, timeout API, input malicioso).

    Incluye URLs en la spec para APIs críticas, contratos de datos y documentación de seguridad. Un equipo debe poder reproducir el flujo completo sin leer código.

    Trade‑offs y decisiones reales

    – Ventana de contexto gigante vs memoria estructurada: ventajas teóricas hay, pero en producción la memoria estructurada gana por latencia, coste y precisión (ver problema “lost in the middle”: arXiv:2307.03172).

    – Autonomía vs auditabilidad: cuanto más autónomo, menos auditable. Para negocios, prioriza auditabilidad.

    – Retry agresivo vs abort + humano: lo primero puede romper tu DB; lo segundo ralentiza workflows pero salva integridad.

    Cierre operativo: de la spec al CI/CD

    La spec no es un PDF muerto. Debe formar parte del pipeline:

    • Tests automatizados que validen precondiciones y fallbacks.
    • Simuladores que reproduzcan errores de herramientas.
    • Guardrails chequeados en staging y alertas de telemetría en producción.

    Si tu spec no se puede testear automáticamente, no es spec: es promesa. Y las promesas no pagan facturas.

    Define la caja de arena antes de soltar los músculos del agente. Es la única manera de que tus agentes actúen con intención, no con catástrofe.

    Dominicode Labs

    Para equipos que implementan pipelines y simuladores de fallo como parte de la spec, una referencia práctica y recursos complementarios están disponibles en Dominicode Labs. Considéralo como un recurso adicional para integrar tests y telemetría en tu CI/CD.

     

    FAQ

    ¿Por qué no vale con un buen prompt para controlar un agente?

    Un prompt no formaliza contratos ni límites verificables. Los agentes razonan de forma estocástica; sin schemas, precondiciones y guardrails numéricos, el prompt será frágil frente a inputs inesperados.

    ¿Qué es un contrato de herramienta y por qué usar JSON Schema?

    Un contrato de herramienta define tipos, formatos y campos requeridos. JSON Schema o Zod son formalismos que permiten validar entradas/salidas de forma determinista y evitar “any” que produzca comportamiento impredecible.

    ¿Cuántas iteraciones (Max Steps) son razonables?

    La guía práctica sugiere entre 5 y 10 iteraciones por sesión antes de forzar cierre. Ese rango reduce bucles infinitos y consumo excesivo de recursos.

    ¿Cómo debo manejar fallos recurrentes de una herramienta?

    Define un protocolo de fallo en la spec: retries limitados con backoff, registro y una estrategia de escalado (por ejemplo, abort_and_escalate tras N retries). No dejes el comportamiento en blanco.

    ¿Qué pruebas automatizadas son mínimas para una spec agéntica?

    Al menos: validación de precondiciones, simuladores de fallo de tools (DB error, timeout), y tests que verifiquen que los guardrails se activan (Max Steps, budget, retries).

    ¿Dónde documentar la política de escalado humano?

    La política de escalado debe estar en la spec principal, con reglas verificables (ej. tres fallos consecutivos de la misma tool o confianza < 0.6 → escalado) y enlaces a contactos/runbooks en tu repositorio de operaciones.

  • Cómo utilizar OpenSpec para gestionar especificaciones en Brownfield

    Cómo utilizar OpenSpec para gestionar especificaciones en Brownfield

    ¿Es OpenSpec la herramienta para las specs en Brownfield?

    Tiempo estimado de lectura: Calculando con ~220 palabras por minuto.

    Tiempo estimado de lectura: 3 min

    • OpenSpec acelera la obtención de una spec base desde comportamiento observable.
    • Su valor real aparece al combinar generación automática con revisión humana y guardrails en CI/CD.
    • No es una solución mágica: puede cristalizar deuda si se usa sin enriquecimiento semántico.
    • Proceso recomendado: discovery → human-in-the-loop → guardrails → evolución controlada.

    Introducción

    ¿Es OpenSpec la herramienta para las specs en Brownfield? Sí —pero no como solución mágica. OpenSpec (entendido como el ecosistema de herramientas que generan y mantienen OpenAPI/AsyncAPI automáticamente) es el punto de partida más práctico para recuperar contratos en sistemas heredados. Su valor real aparece cuando lo combinas con juicio humano, revisión semántica y guardrails en CI/CD.

    Resumen rápido (lectores con prisa)

    OpenSpec: conjunto de herramientas que generan especificaciones (OpenAPI/AsyncAPI) automáticamente desde tráfico o análisis estático. Útil para Brownfield cuando se usa como extractor inicial, no como fuente final sin revisión. Importante integrarlo con revisión humana y validaciones en pipelines.

    ¿Es OpenSpec la herramienta para las specs en Brownfield? — contexto y por qué importa

    Problema en Brownfield

    En Brownfield tienes código en producción, dependencias cruzadas y documentación que normalmente no refleja la realidad. El problema no es generar YAML: es detener el sangrado de cambios no esperados en producción. Aquí OpenSpec aporta dos cosas fundamentales:

    Qué aporta OpenSpec

    • Rapidez para obtener una línea base estructural a partir del comportamiento real del sistema.
    • Mecanismos para convertir una spec en infraestructura (drift detection, validación en pipelines).

    Herramientas de referencia: Optic, Akita, Specmatic. Para extracción desde código: Springdoc, tsoa. Consulta la especificación OpenAPI.

    Qué puede y qué no puede hacer OpenSpec en un Brownfield

    Lo que sí hace bien

    • Extrae la estructura observable de endpoints, métodos y esquemas de payloads.
    • Produce specs rápidamente desde tráfico en staging o desde análisis estático.
    • Habilita detección de deriva en CI: bloquea merges que cambian respuestas esperadas.

    Lo que no hace

    • No captura semántica de negocio: no sabe que status: 2 significa “Cuenta suspendida”.
    • No documenta edge cases que no aparecieron en el tráfico observado.
    • No corrige malos diseños: puede cristalizar inconsistencias si aceptas la spec sin filtrar.

    Si tratas la generación automática como la verdad absoluta, produces un contrato falso-seguro. Si la usas como un extractor inicial, reduces semanas de trabajo manual a horas.

    Estrategia práctica para implantar OpenSpec en Brownfield

    Implementarlo sin generar más deuda exige disciplina. Siguientes pasos probados en equipos técnicos:

    1. Generación de baseline (Discovery)

    • Captura tráfico en staging o usa análisis estático según el stack.
    • Herramientas: Optic para captura/visualización, Akita para inferencia basada en tráfico, Springdoc/tsoa para extracción desde código.
    • Objetivo: obtener un OpenAPI.yaml que represente el comportamiento observado, no la versión final.

    2. Enriquecimiento semántico (Human-in-the-loop)

    • Asigna a domain owners para revisar y documentar campos críticos, códigos de estado y reglas de negocio.
    • Corrige nombres ambiguos y elimina endpoints internos expuestos por accidente.
    • Añade ejemplos y descripciones para cada campo sensible.

    3. Control automático (Guardrails)

    • Integra la spec en CI: Specmatic u Optic pueden ejecutar contract tests o comparar contratos en PR.
    • Fallo en la spec = bloqueo del merge hasta revisión explícita.
    • Mantén logs de cambios automáticos y un proceso claro para aprobar modificaciones del contrato.

    4. Evolución controlada

    • No distribuyas la spec al consumidor externo hasta que se haya ratificado por el equipo.
    • Versiona la spec y comunica breaking changes con políticas (semver, fechas, deprecations).

    Ejemplo real y conciso

    Situación: monolito en Node que sirve APIs REST sin spec.

    • Paso 1: Instrumenta un proxy de captura en staging con Optic. Ejecuta suites de integración para generar tráfico representativo.
    • Paso 2: Optic genera un OpenAPI básico. Equipo revisa y detecta 3 endpoints con campos inconsistentes.
    • Paso 3: Ajustes manuales, se añaden descripciones de status y se documentan errores 422 y 503 que no aparecieron en tráfico.
    • Paso 4: Integra Specmatic en CI para validar que cambios en PR no alteren respuestas esperadas sin aprobación.

    Resultado: en semanas tienes una spec utilizable y protección automática contra cambios no controlados.

    Riesgos y mitigaciones operativas

    • Riesgo: cristalizar deuda técnica. Mitigación: obligar enriquecimiento semántico antes de promover spec a “source of truth”.
    • Riesgo: cobertura incompleta por tráfico insuficiente. Mitigación: complementar capture con tests orientados a edge cases y análisis estático.
    • Riesgo: falsa confianza en herramientas. Mitigación: auditorías periódicas de la spec por arquitectos y product owners.

    Conclusión — criterio técnico

    OpenSpec es la herramienta indicada para arrancar specs en Brownfield. No reemplaza la discusión humana sobre contratos ni el trabajo de diseño del dominio. Su fuerza está en reducir trabajo mecánico y convertir documentación en infraestructura verificable. Si tu equipo integra generación automática con revisión semántica y guardrails en CI, OpenSpec deja de ser una “herramienta” y pasa a ser una palanca que reduce riesgo y acelera refactors con seguridad.

    Para equipos que trabajan con automatización de workflows, captura de tráfico e integración CI, puede interesar explorar más recursos y experimentos en Dominicode Labs. Es una referencia complementaria para prototipos y pruebas de integración de herramientas OpenSpec en pipelines.

    FAQ

    • ¿Qué es exactamente OpenSpec en este contexto?

      OpenSpec se refiere al ecosistema de herramientas que generan y mantienen especificaciones OpenAPI/AsyncAPI automáticamente a partir de tráfico observado o análisis estático.

    • ¿Cuándo debería usar generación automática de specs?

      Úsala como punto de partida para recuperar la estructura real del API en un Brownfield: captura en staging o análisis estático, luego enriquece y valida antes de promoverla.

    • ¿Puede una spec generada automáticamente ser la fuente de verdad?

      No directamente. Sin revisión semántica y procesos de aprobación, la spec puede cristalizar inconsistencias y perder contexto de negocio.

    • ¿Qué herramientas son recomendables para empezar?

      Herramientas citadas: Optic, Akita, Specmatic, más extractores como Springdoc y tsoa.

    • ¿Cómo evito cristalizar deuda técnica al usar OpenSpec?

      Exige enriquecimiento semántico por domain owners antes de promover la spec a “source of truth” y mantén auditorías periódicas.

    • ¿Qué cubre la detección de deriva en CI?

      La detección de deriva compara respuestas observadas con la spec y puede bloquear merges que introduzcan cambios no aprobados en respuestas o contratos.

    • ¿Qué hago si el tráfico observado no cubre edge cases?

      Complementa la captura con tests orientados a edge cases y con análisis estático del código para aumentar cobertura.

  • Cómo implementar TDD y Spec-First para mejorar el uso de IA en desarrollo

    Cómo implementar TDD y Spec-First para mejorar el uso de IA en desarrollo

    TDD + Spec-First: el combo que cambia cómo trabajas con IA

    Tiempo estimado de lectura: 5 min

    • Ideas clave:
    • Spec-First define contratos claros (tipos, OpenAPI, GraphQL) antes de implementar.
    • TDD convierte esos contratos en especificaciones ejecutables: tests rojos → implementación → tests verdes.
    • Con LLMs, contrato + tests limitan alucinaciones y convierten a la IA en colaborador predecible.
    • Práctica: versiona specs, entrega solo interfaz + test al modelo, ejecuta CI y refactoriza con seguridad.

    TDD + Spec-First: el combo que cambia cómo trabajas con IA no es una moda. Es la forma práctica de convertir asistentes de código (Cursor, Copilot, Claude, etc.) en colaboradores fiables en lugar de generadores caóticos. Si quieres que la IA entregue código mantenible y predecible, primero le pones un contrato; después, le pones pruebas.

    Resumen rápido (lectores con prisa)

    Spec-First: define el contrato (types/OpenAPI/GraphQL) antes de implementar. TDD: escribe tests que describen comportamiento antes de la lógica. Juntos: contrato define el “qué”, los tests el “cuándo” y la IA queda confinada al “cómo”.

    TDD + Spec-First: el combo que cambia cómo trabajas con IA — qué es y por qué importa

    Qué es Spec-First

    Spec-First significa diseñar el contrato antes de implementar: tipos TypeScript, OpenAPI/Swagger o un esquema GraphQL (GraphQL). Definir la interfaz y errores esperados aclara responsabilidades y límites.

    Qué es TDD

    TDD (Test-Driven Development) obliga a escribir pruebas que expresen comportamiento antes de cualquier línea de lógica. Los tests actúan como una especificación ejecutable que guía la implementación y protege el diseño frente a regresiones.

    Flujo práctico: cómo aplicarlo día a día

    1) Define el contrato (Spec-First)

    • Escribe interfaces o un OpenAPI minimal.
    • Versiona ese archivo en el repo.
    • Hazlo lo más explícito posible: tipos, errores esperados, límites de paginación.

    Por qué? Cambiar una especificación es barato; cambiar la implementación ya entregada cuesta tiempo y bugs.

    2) Escribe los tests antes (Red)

    • Genera tests unitarios que describan casos reales: éxito, validaciones y fallos (timeouts, errores de red).
    • Usa frameworks previstos: Jest, pytest, etc.
    • Aísla dependencias con mocks para que el test sea una especificación ejecutable del comportamiento.

    3) Implementa con la IA (Green)

    • Entrega a la IA solo la interfaz y el test fallido. Nada de documentación amplia ni contexto innecesario.
    • Pide explícitamente: “Implementa X para que pase estos tests. No añadas métodos públicos que no estén en la interfaz.”
    • Ejecuta los tests; si fallan, pega el error en el prompt y haz que la IA itere.

    4) Refactoriza y repite (Refactor)

    Con tests en verde, pide mejoras estructurales (limpieza, reducción de complejidad) y deja que los tests validen que no hay regresiones.

    Ejemplo rápido (esquema)

    – Spec-First: IUserService { getById(id): Promise | throws NotFound }
    – Tests (Jest): caso exitoso, user no existe, DB timeout.
    – Implementación: la IA crea UserService respetando la interfaz; los tests pasan.

    Ese flujo evita que la IA invente un método “findUserOrCreate()” si no estaba en la spec.

    Ventajas reales en equipos técnicos

    • Arquitectura consistente: los tech leads definen límites arquitectónicos, la IA implementa sin salirse de ellos.
    • Documentación viva: specs + tests = documentación ejecutable.
    • Escalabilidad del trabajo: developers junior pueden entregar valor siguiendo contratos y tests claros.
    • Refactor seguro: la suite de tests permite que la IA haga cambios con garantía.

    Riesgos y cómo mitigarlos

    1. Tests tautológicos

    Riesgo: si la IA escribe spec, tests e implementación, todo estará autoconsistente pero puede no cubrir requerimientos reales.

    Mitigación: la spec inicial la define un humano con conocimiento del dominio. Revisa y aprueba los tests generados.

    2. Overfitting en tests

    Riesgo: tests que verifican la implementación concreta y no el comportamiento observable.

    Mitigación: escribe tests orientados a contratos (inputs/outputs/efectos observables), no a estructuras internas.

    3. Explosion de tests irrelevantes

    Riesgo: la IA puede generar multitud de casos triviales que aumenten la carga de mantenimiento.

    Mitigación: prioriza tests del Core Domain; define criterios claros de cobertura (p. ej. casos críticos y límites).

    Integración práctica y mejores prácticas

    • Prompts minimalistas y restrictivos: entrega solo interface + test. Menos contexto = menos alucinaciones.
    • Versiona prompts y ejemplos de tests en el repo para auditar cambios.
    • CI como guardián: exige que todos los PRs pasen la suite antes de merge.
    • Métricas: trackea flakiness de tests y tiempo medio hasta tests verdes cuando la IA implementa; son indicadores de calidad del flujo.

    Recursos y lectura recomendada

    Spec-First + TDD no es una camisa de fuerza; es un marco que transforma a la IA en una herramienta que ejecuta diseño, no que lo inventa. Si quieres resultados reproducibles y menos deuda técnica, deja de pedir “escribe esto” y comienza a exigir contratos y pruebas. El resto viene solo.

     

    FAQ

     

    ¿Por qué empezar por la spec en lugar de por el código?

    Porque la spec define límites y responsabilidades antes de que alguien implemente. Cambiar una spec es más barato y menos propenso a introducir bugs que ajustar implementaciones ya en producción.

    ¿Qué pruebas debería escribir primero?

    Empieza por casos críticos: caminos felices, validaciones y fallos esperados (timeouts, errores de red). Prioriza comportamiento observable sobre detalles de implementación.

    ¿Cómo evitar que la IA genere funciones fuera de la interfaz?

    Entrega al modelo sólo la interfaz y el test fallido; pide explícitamente que no añada métodos públicos que no estén en la spec. Usa revisión humana y CI para bloquear cambios no autorizados.

    ¿Qué frameworks de tests son recomendables?

    Depende del stack: Jest para JavaScript/TypeScript, pytest para Python, y frameworks nativos para otros lenguajes. Lo importante es que permitan mocks y pruebas aisladas.

    ¿Cómo integrar esto en CI?

    Configura la pipeline para ejecutar la suite completa en cada PR. Rechaza merges si hay tests fallidos. Versiona specs y prompts en el repo para auditar cambios.

    ¿Qué métricas debo trackear?

    Trackea flakiness de tests, tiempo medio hasta tests verdes cuando la IA implementa, y número de PRs que requieren intervención humana. Esos indicadores reflejan calidad y estabilidad del flujo.

  • Agentic Coding: Automatizando el Ciclo de Desarrollo con IA

    Agentic Coding: Automatizando el Ciclo de Desarrollo con IA

    Qué es el Agentic coding?

    Tiempo estimado de lectura: 4 min

    Ideas clave

    • Agentic coding es un paradigma donde un agente de IA recibe un objetivo de alto nivel y ejecuta el ciclo completo de implementación.
    • Combina planificación, uso de herramientas y un bucle de retroalimentación que incluye tests y correcciones iterativas.
    • Funciona bien para scaffolding, pruebas y tareas repetitivas; requiere documentación, TDD y revisión humana para evitar riesgos.

     

    Qué es el Agentic coding? Es el paradigma en el que un agente de IA recibe un objetivo de alto nivel y ejecuta el ciclo completo de implementación: planifica subtareas, escribe y modifica archivos, ejecuta tests y se autocorrige hasta cumplir el criterio de éxito. No es autocompletar: es automatizar el flujo de trabajo de desarrollo con bucles de razonamiento y acción.

    Resumen rápido (lectores con prisa)

    Agentic coding transforma LLMs en agentes que planifican, usan herramientas (editar archivos, ejecutar comandos, llamar APIs) y se corrigen mediante un bucle de feedback con tests. Es útil para scaffolding, pruebas y tareas repetitivas, pero requiere documentación, TDD y revisión humana por riesgos de seguridad, coherencia y alucinaciones.

    Qué es el Agentic coding? — definición y componentes técnicos

    Técnicamente, un sistema agéntico combina tres capacidades:

    • Planificación: el modelo descompone una tarea compleja en pasos ejecutables antes de tocar código.
    • Uso de herramientas (tool use): el agente puede leer/editar archivos, ejecutar comandos en la terminal, abrir el navegador o llamar APIs externas.
    • Bucle de retroalimentación (feedback loop): ejecuta tests o builds, analiza fallos (stack traces) y corrige el código iterativamente.

    Esa combinación transforma al LLM de generador de texto en un motor de ejecución: piensa, actúa, verifica, corrige. Ejemplo real: pedir “añade rate limiting al endpoint /api/auth y crea tests unitarios” y recibir, tras múltiples ejecuciones, un PR con código que pasa el pipeline de CI (o al menos repite intentos hasta que los tests locales pasan).

    Herramientas y ecosistema (URLs)

    Las herramientas que ya incorporan capacidades agénticas o facilitan su adopción son relevantes para entender el estado práctico del Agentic coding:

    Estas herramientas muestran dos enfoques: editores/CLI que actúan dentro del flujo de desarrollo, y orquestadores que integran agentes en pipelines y automatizaciones.

    Limitaciones prácticas y riesgos técnicos

    El Agentic coding funciona, pero con condiciones. No es una panacea.

    1. Context window y coherencia arquitectónica

    Los agentes pierden visión global en repositorios grandes. La ventana de contexto de los LLMs mejora, pero no sustituye el conocimiento arquitectónico humano. Técnicas como RAG (retrieval-augmented generation) ayudan a indexar documentación, pero no garantizan decisiones coherentes a nivel sistema.

    2. Seguridad y dependencias

    Un agente optimiza la entrega de la tarea, no la seguridad. Puede introducir dependencias vulnerables o atajos que rompen principios de Clean Architecture. La revisión humana sigue siendo obligatoria antes del merge.

    3. Alucinaciones técnicas

    Los modelos pueden generar llamadas a APIs inexistentes o usar firmas obsoletas. Sin ejecución automática de tests y análisis estático, esas alucinaciones pasan desapercibidas.

    4. Escalabilidad y mantenimiento

    Generar cambios rápidos aumenta la deuda técnica si no se adoptan reglas de estilo, ADRs o documentación que orienten al agente.

    Buenas prácticas para adoptar Agentic coding

    Si vas a integrar agentes en tu flujo, aplica estas reglas mínimas:

    • Documenta el contexto: RULES.md, guías de estilo y ADRs reducen ambigüedad y guían las decisiones del agente.
    • Adopta TDD como protocolo de interacción: escribir tests primero ofrece un criterio de éxito claro para el agente y reduce la supervisión humana.
    • Modula y desacopla: los agentes funcionan mejor en componentes pequeños; refactoriza monolitos antes de delegar tareas significativas.
    • Pipelines de CI como árbitro: ejecuta builds y análisis estático automáticamente en cada PR generado por un agente.
    • Revisión humana con checklist: seguridad, licencias de dependencias y arquitectura deben validarse manualmente antes del merge.

    Cuándo usar y cuándo no usar agentes

    Usa agentes para:

    • Scaffolding y generación de pruebas.
    • Refactorizaciones locales y tareas repetitivas.
    • Automatizar revisiones preliminares de PRs o generar PRs iniciales para revisión humana.

    Evítalos en:

    • Decisiones arquitectónicas críticas.
    • Código con requisitos regulatorios o de seguridad estrictos.
    • Repositorios legacy masivos sin documentación ni tests.

    Conclusión

    Qué es el Agentic coding? Es la evolución de la IA desde asistente pasivo a actor autónomo en el ciclo de desarrollo. Ofrece un multiplicador de productividad si se integra con disciplina: documentación explícita, tests como contrato de aceptación, CI robusto y revisión humana en los puntos críticos. Mal usado acelera la deuda técnica; bien usado multiplica la capacidad del equipo.

    Si exploras integración de agentes, pipelines y automatización en equipos de ingeniería, puede resultar útil revisar recursos y experimentos prácticos. Una continuación lógica para equipos interesados en estos temas es Dominicode Labs, que agrupa proyectos y guías sobre automatización e IA aplicada en flujos de desarrollo.

     

    FAQ

     

    ¿Qué distingue al Agentic coding de un asistente de autocompletar?

    Agentic coding implica que el agente planifique, ejecute cambios en archivos, ejecute tests y se autocorrija mediante bucles de feedback. Un autocompletador solo sugiere fragmentos de texto o código sin ejecutar ni verificar el resultado.

    ¿Qué componentes técnicos hacen falta para un agente agéntico?

    Planificación de tareas, capacidad de usar herramientas (editar archivos, ejecutar comandos, llamar APIs) y un bucle de retroalimentación con tests o builds son los componentes esenciales.

    ¿Cuáles son los riesgos principales al usar agentes?

    Riesgos clave: pérdida de coherencia arquitectónica en repositorios grandes, introducción de dependencias inseguras, alucinaciones técnicas y aumento de deuda si no hay reglas y documentación.

    ¿Cómo debo preparar un repo antes de delegar a un agente?

    Documenta contexto y reglas (RULES.md, ADRs), añade tests y adopta TDD, modula componentes y habilita pipelines de CI para validar PRs generados por agentes.

    ¿Qué herramientas son relevantes hoy para Agentic coding?

    Herramientas representativas incluyen Cursor — editor con modo Composer, Aider, Cognition.ai, OpenHands, n8n, OpenAI (APIs de LLM) y Anthropic (Claude).

    ¿Los agentes pueden reemplazar la revisión humana?

    No. La revisión humana sigue siendo obligatoria para validar seguridad, licencias y decisiones arquitectónicas críticas antes del merge.

    ¿Qué prácticas reducen alucinaciones técnicas?

    Practicas que ayudan: adoptar TDD, ejecutar tests y análisis estático en CI automáticamente, usar RAG para documentar contexto y contar con reglas y ADRs que guíen al agente.

  • Automatización de la Revisión de Código con IA en 2026

    Automatización de la Revisión de Código con IA en 2026

    Revisión de código con IA y validación automatizada de especificaciones (2026)

    Tiempo estimado de lectura: 4 min

    • Automatizar validaciones contra especificaciones convierte las specs en guardrails operativos, no en mera documentación.
    • Pipeline agentico: inyección de contexto (RAG), validación determinista en entornos aislados y bucle agentico con autocorrección controlada.
    • Riesgos reales: especificaciones ausentes/contradictorias, sesgo de automatización, límites de contexto y responsabilidades legales.
    • Checklist operativo para Tech Leads: versionar OpenAPI/ADRs, cobertura de tests, modularidad y políticas de autocorrección.

    La revisión de código con IA y validación automatizada de especificaciones (2026) ya no es un experimento: es una capa que muchos equipos productivos están integrando en sus pipelines. Escribir código dejó de ser el cuello de botella; ahora lo es verificar que ese código cumpla contratos, reglas de negocio y decisiones arquitectónicas. Este artículo explica cómo funciona hoy la automatización, qué riesgos reales merece tu atención y qué pasos prácticos debe ejecutar un Tech Lead antes de activar agentes en CI.

    Resumen rápido (lectores con prisa)

    La automatización combina RAG para extraer contexto del repo, entornos efímeros para ejecutar tests y validaciones deterministas contra OpenAPI/AsyncAPI. Se puede permitir autocorrección en cambios triviales y bloquear cambios de diseño para revisión humana. Requiere especificaciones versionadas, cobertura de tests y modularidad.

    Revisión de código con IA y validación automatizada de especificaciones: cómo funciona hoy

    El salto respecto a herramientas tradicionales (SonarQube, Semgrep) es que los agentes modernos cruzan el diff del PR con documentación estructurada y ejecutan validaciones deterministas:

    • Capturan contexto del repositorio (ADRs, OpenAPI, tests y convenciones).
    • Vectorizan y recuperan fragmentos relevantes vía RAG (retrieval‑augmented generation).
    • Levantan entornos efímeros para ejecutar tests y comprobar contratos OpenAPI/AsyncAPI.
    • Pueden proponer o aplicar parches automáticos y re‑ejecutar la suite antes de notificar al revisor humano.

    Herramientas y referencias relevantes

    El resultado: PRs más rápidos, menos fricción y menos errores de contrato que escapan a producción —siempre que el sistema esté bien montado.

    Arquitectura práctica: pipeline agentico y validación de especificaciones

    Implementarlo con seguridad implica estructurar el pipeline en tres bloques:

    1. Inyección de contexto (RAG para repositorios)

    • Indexa ADRs, OpenAPI, README, tests y convenciones del repo en un vector store (p. ej. Pinecone).
    • Cuando abre un PR, extrae el contexto específico del área afectada para construir prompts y reglas de validación.

    2. Validación determinista en entorno aislado

    • Levanta un contenedor efímero con la rama del PR.
    • Ejecuta tests unitarios, contract tests (Specmatic/Optic) y llamadas end‑to‑end contra la API.
    • Compara respuestas reales con la especificación OpenAPI versionada.

    3. Agentic loop (autocorrección controlada)

    • Si hay desviaciones menores (tipos, campos faltantes), el agente genera un parche y abre un commit automático.
    • Re‑ejecuta tests; si todo pasa, marca la verificación como “verde” y agrega una nota en el PR.
    • Las acciones que implican diseño (breaking changes, cambios semánticos) quedan bloqueadas para revisión humana.

    Este flujo convierte la spec en guardrail operativo, no en mera documentación.

    Límites reales y riesgos que no puedes ignorar

    • Especificaciones inexistentes o contradictorias: la IA solo puede validar lo que está formalizado. En Brownfield, primero escribe specs consumibles por máquinas.
    • Ventana de contexto: los modelos actuales pierden precisión al razonar sobre cambios transversales en monolitos enormes; la modularidad importa.
    • Automation bias: equipos que confían ciegamente en un “check verde” aceleran fallos operativos. El humano sigue siendo responsable.
    • Seguridad y liability: un agente puede aprobar un PR que introduce vulnerabilidad lógica; la responsabilidad legal recae en la organización.

    Checklist operativo para Tech Leads antes de activar agentes

    1. Mantén OpenAPI/AsyncAPI actualizados y versionados en el repo (source of truth).
    2. Versiona ADRs junto al código y define reglas claras en CONVENTIONS.md o .repo_rules.
    3. Asegura cobertura de tests: unitarios, contract tests (Specmatic/Optic) y un set mínimo de E2E para paths críticos.
    4. Modulariza dominios (DDD, bounded contexts) para acotar la precisión del agente.
    5. Implementa un entorno de staging efímero en CI donde el agente pueda ejecutar validaciones reales.
    6. Define políticas claras de autocorrección: qué puede commitear automáticamente y qué queda bloqueado.
    7. Añade auditoría y logging: cada parche automático debe tener trazabilidad y motivación textual.

    Cómo medir si te funciona

    Métricas accionables:

    • Reducción del tiempo medio de revisión (MTTR para PRs).
    • Porcentaje de PRs con fallos de contrato detectados en CI vs. en producción.
    • Número de commits automáticos revertidos por humanos (indicador de sobre‑autonomía).
    • Tiempo que el equipo destina a revisiones de criterio vs. a correcciones triviales.

    Conclusión técnica

    La revisión de código con IA y validación automatizada de especificaciones en 2026 es una palanca real: acelera ciclos y reduce errores de contrato si y solo si la organización invierte antes en especificación, tests y modularidad. Sin ese trabajo previo, la IA añade ruido y riesgo. Haz la inversión estructural primero; luego deja que los agentes hagan lo repetible. Así, tus ingenieros podrán dedicar su juicio a lo que realmente importa: arquitectura, impacto en el negocio y diseño de largo plazo.

    Para equipos que exploran flujos de automatización y agentes dentro de pipelines, una continuación natural de este trabajo es revisar proyectos y experimentos en Dominicode Labs, donde se documentan plantillas y patrones aplicables a pipelines agenticos.

    FAQ

    ¿Qué tipo de especificaciones debo versionar en el repo?

    Versiona OpenAPI/AsyncAPI como source of truth y mantén ADRs alineados con el código. Estas especificaciones deben ser consumibles por máquinas y estar en la misma rama o en rutas versionadas del repo.

    ¿Qué puede commitear automáticamente un agente?

    Cambios triviales y deterministas: correcciones de tipos, campos faltantes obvios o parches que no alteren la semántica. Las políticas deben definir límites claros: breaking changes y decisiones de diseño requieren revisión humana.

    ¿Cómo evito el automation bias en el equipo?

    Establece métricas de calidad, revisiones periódicas de commits automáticos revertidos y responsabilidades claras. Mantén a los revisores enfocados en criterio y diseño, no en correcciones triviales.

    ¿Qué pruebas son imprescindibles antes de activar agentes en CI?

    Cobertura de tests unitarios, contract tests (Specmatic/Optic) y un set mínimo de E2E para paths críticos. Además, entornos de staging efímeros donde el agente pueda ejecutar validaciones reales.

    ¿Cómo audito los parches automáticos?

    Registra trazabilidad y motivación textual para cada parche, conserva commits con mensajes generados por el agente y almacena logs completos de ejecución en un sistema de auditoría accesible al equipo de seguridad y arquitectura.

    ¿Qué límites de contexto tienen los modelos actuales?

    Los modelos pierden precisión en cambios transversales dentro de monolitos enormes debido a la ventana de contexto. La modularidad y bounded contexts reducen este problema y mejoran la precisión del agente.

  • Implementa Plum para Mejorar la Trazabilidad en tus Commits

    Implementa Plum para Mejorar la Trazabilidad en tus Commits

    ¿Te da pánico pensar que la IA pueda llenar tu repo de código que nadie entiende? Bienvenido a la nueva crisis del software.

    Tiempo estimado de lectura: 5 min

    • La velocidad de generación de código por IA supera la capacidad humana de registrar intención.
    • Plum captura decisiones en el momento del commit para mantener spec, tests y código sincronizados.
    • Sin checkpoints canónicos (hooks de Git) la intención se evapora y se pierde propiedad intelectual.

    Introducción

    Poca gente lo dice claro: ahora la IA escribe más rápido de lo que podemos entender. Y velocidad sin intención es solo ruido estructural.

    This is her code. This is what she was managing. This is her VS code. Margaret Hamilton tenía la plomada mental de la arquitectura. Hoy tenemos agentes que empiezan a escribir habitaciones enteras sin planos. ¿Quién firma eso cuando se cae el techo?

    Resumen rápido (lectores con prisa)

    Plum captura y versiona decisiones (humanas y de agentes) en el momento del commit mediante hooks de Git; obliga a validar intenciones y sincroniza spec ↔ tests ↔ código. Es un checkpoint canónico para trazabilidad y responsabilidad.

    ¿Qué hace Plum en una frase?

    Captura decisiones (humano + agente) en el momento del commit, te pide que las valides, las convierte en artefactos versionables y sincroniza spec ↔ tests ↔ código.

    ¿Por qué no puede ser simplemente “una skill” dentro del agente?

    Porque una skill es una sugerencia. Una sugerencia se ignora cuando el plazo aprieta. Necesitamos un checkpoint canónico que no puedas saltar: un hook de Git que detenga el commit hasta que la intención quede registrada. Eso es lo que hace Plum.

    Cómo se ve en la práctica (sin tecnicismos aburridos)

    • Instalas Plum.
    • Ejecutas plum init en la raíz del repo.
    • Plum crea una carpeta .plum, un .plumignore y agrega hooks a Git.
    • Haces cambios usando un agente.
    • Intentas git commit.
    • Plum analiza diffs + traces del agente.
    • Si hay decisiones detectadas, el commit falla hasta que las apruebes, edites o rechaces.
    • Si apruebas, Plum actualiza la spec (Markdown) y genera un registro en JSONL con la decisión, quién la aprobó, branch, timestamps y si el LLM sugirió o el humano decidió.

    Ventajas prácticas que notarás rápido

    • Un agente ya no “olvida” reglas que le dijiste hace semanas. El agente puede consultar el árbol de decisiones antes de actuar.
    • Cuando alguien pregunta “¿por qué esto está así?”, la respuesta no es “creo que lo discutimos en Slack”. Es un enlace a la decisión y su justificación.
    • El code review pasa de revisar sintaxis a revisar intención. Eso reduce regresiones silenciosas.

    Limitaciones honestas (sí, las tiene)

    • Hoy Plum enlaza pruebas vía Pytest. Si tu pipeline usa otro runner, la cobertura spec→tests no funcionará todavía.
    • Identificar decisiones no es perfecto. La deduplicación es fuzzy y repo-específica. Hay parámetros que ajustar.
    • Reversión automática al rechazar decisiones aún no es robusta. Si rechazaste una decisión en la CLI, el rollback con el agente es un flujo que requiere trabajo fino.
    • En proyectos extremadamente grandes sin spec previa (legacy), Plum no hace magia: necesita spec por delante para funcionar bien. Backfilling masivo aún está en la hoja de ruta.

    Diseños críticos que no puedes ignorar

    • Debe ser externa al LLM. Si la gobernanza vive dentro del agente, la gente la ignorará.
    • Debe fallar commits. Sin ese checkpoint, es teoría bonita y nadie la respeta.
    • Usa DSPy u otro framework para estructurar LLM calls cuando sea absolutamente necesario. Pero siempre que puedas, valida con código determinista: la verificación debe ser programable, repetible y testeable.
    • La experiencia humana importa. Si cada hotfix genera 5 decisiones triviales, la herramienta se vuelve molesta. Debe existir un umbral de interrupción configurable. Tú decides: banca cero tolerancia para banca; modo “dangerously approve all” para experimentos.

    Casos reales, concretos

    • PM cambia la regla de comisiones a las 3am. El agente aplica el hotfix. Plum detecta 3 decisiones: cambio de fórmula, invalidación de cache, ajuste de test. Te las muestra. Apruebas. Plum actualiza el spec y enlaza el test que cubre la nueva regla. Un auditor te lo agradece en el futuro.
    • Fix urgente en prod. Actúas rápido. Plum puede configurarse para no interrumpir decisiones triviales en ramas específicas. O puedes exigir aprobación humana para cambios en main o en módulos críticos.
    • Refactor mayor. Plum obliga a agrupar decisiones y a shardar la spec. El árbol de decisiones te ayuda a no romper invariantes.

    Checklist para empezar hoy (sin dramas)

    1. Poner spec en Markdown y versionarla. Sí, en el repo.
    2. Tener tests automatizados. Si usas Python: Pytest. Si no, prepara el adapter.
    3. pip install plum-dev
    4. plum init (apunta a tu carpeta de specs y al directorio de tests)
    5. Añade .plumignore para excluir archivos ruidosos
    6. Configura tolerancias: qué decisiones bloquean commit y cuáles no
    7. Empieza con una rama pequeña y haz dogfooding: úsenlo para gestionar el proyecto que desarrolla Plum. Si no duele, no funciona.

    Comportamientos que salvarán tu empresa (si los adoptas)

    • Nunca permitas que un cambio de negocio se quede solo en Slack.
    • No confíes en mensajes de commit como única fuente de intención.
    • Exige artefactos: decisión aprobada, spec actualizada, test que falla sin la decisión.

    Metáfora rápida porque las metáforas funcionan

    Tu repo es un edificio. Los agentes son obreros hiperactivos con taladros. Si no tienes planos actualizados y un inspector que firme cada cambio, terminarás con un edificio que parece Frankenstein. Plum es la plomada. No construye paredes. Te dice si las paredes están verticales.

    Lo práctico, ahora mismo

    • Sí, puedes pip install plum-dev y jugar en una rama de feature.
    • Sí, puedes ajustar el umbral para que no te moleste en hotfixes.
    • No, no es todavía plug-and-play para proyectos legacy gigantes.
    • Sí, si usas agentes en producción sin registrar decisiones, estás acelerando una deuda técnica que alguien pagará caro.

    ¿Quieres el template JSONL + flujo de PR listo para copiar en tu repo? Respóndeme este mensaje y te lo envío.
    Quieres algo más directo: pip install plum-dev, plum init, haz un commit con un agente y verás cómo el commit falla hasta que registras la intención. Prueba en una rama de sandbox.

    No es sexy. Es aburrido. Y es exactamente lo que separa equipos que escalan de equipos que heredarán un desastre técnico eterno.

    Dominicode Labs

    Si trabajas con automatización, agentes o workflows y quieres seguir explorando prácticas de gobernanza y trazabilidad, revisa Dominicode Labs como continuación lógica de estas ideas. Encontrarás recursos y experimentos sobre integración de agentes y control de intención.

    FAQ

    ¿Qué es Plum?

    Plum es una herramienta que captura decisiones (humanas y de agentes) en el momento del commit mediante hooks de Git, convierte esas decisiones en artefactos versionables y sincroniza spec, tests y código para mantener trazabilidad.

    ¿Por qué necesito un hook de Git para registrar decisiones?

    Porque un hook crea un checkpoint canónico que no se puede saltar: obliga a registrar intención antes de completar el commit. Sin ese mecanismo la gobernanza se vuelve opcional y se pierde trazabilidad.

    ¿Cómo integra Plum spec y tests?

    Plum analiza diffs y traces de agente, propone cambios en la spec (Markdown) y genera enlaces entre requisitos atómicos, tests y commits. Además crea un registro JSONL con las decisiones para auditoría.

    ¿Qué pasa en hotfixes de emergencia?

    Plum puede configurarse para reducir la interrupción en ramas específicas o para exigir aprobación humana en ramas críticas como main. También puedes ajustar umbrales para decisiones que no bloqueen el commit.

    ¿Funciona con pipelines que no usan Pytest?

    Hoy Plum enlaza pruebas vía Pytest por defecto. Si tu runner es otro, necesitarás un adapter: la cobertura spec→tests no funcionará hasta que exista soporte para tu runner.

    ¿Cómo evita Plum el ruido en cambios triviales?

    Plum usa un .plumignore para excluir archivos ruidosos y tiene parámetros configurables que definen umbrales de interrupción para que no genere decisiones por cada cambio menor.

    ¿Dónde están los registros de decisiones?

    Plum genera un archivo JSONL con entradas que incluyen la decisión, quién la aprobó, branch, timestamps y si fue sugerida por LLM o aprobada por humano. Es un fichero indexable y enlazable a PRs.

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

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

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

    Tiempo estimado de lectura: 6 min

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

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

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

    Resumen rápido (lectores con prisa)

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

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

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

    Modelos probabilísticos y decisiones

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

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

    1) Incoherencia estilística que mata el mantenimiento.

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

    2) Pérdida de contexto.

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

    3) Acoplamiento brutal.

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

    Esto tiene nombre: alucinación arquitectónica

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

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

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

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

    Una spec efectiva incluye:

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

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

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

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

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

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

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

    3) Usa archivos de reglas a nivel proyecto.

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

    4) Divide el trabajo en prompts modulares.

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

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

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

    Historias reales: el junior, el senior y la IA

    Imagínate esto.

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

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

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

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

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

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

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

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

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

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

    CTA simple y directo: haz esto ahora

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

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

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

    Urgencia real: la deuda técnica no espera

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

    Cierre que no cierra (a propósito)

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

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

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

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

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

    FAQ

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

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

    ¿Cuánto detalle necesita una spec?

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

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

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

    ¿Qué pasa si olvidamos actualizar la spec?

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

    ¿Cómo integro la spec en el CI?

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

    ¿Necesito una spec para prototipos?

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

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

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

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

    Tiempo estimado de lectura: 4 min

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

    Introducción

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

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

    Resumen rápido (lectores con prisa)

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

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

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

    Juntos funcionan así:

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

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

    Qué debe incluir una SDD práctica para agentes

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

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

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

    El ciclo TDD que hace verificable al agente

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

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

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

    Ejemplo práctico (resumen)

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

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

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

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

    Aplica SDD + TDD cuando:

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

    No lo apliques para:

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

    Lo que cambian estas prácticas en tu equipo

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

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

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

    Fuentes y lectura recomendada

    FAQ

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

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

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

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

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

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

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

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

    ¿Qué herramientas recomiendan para ejecutar el ciclo TDD?

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

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

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

    ¿Cuándo NO debo aplicar SDD + TDD?

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

  • 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

    ¿Qué es Spec-First Development?

    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.

    ¿Cuándo debo escribir una spec?

    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.

    ¿Qué diferencia hay entre spec y documentación tradicional?

    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.

    ¿Pueden los agentes usar la spec directamente?

    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.

    ¿Qué incluye una spec mínima?

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

    ¿Qué ocurre si no versiono la spec junto al código?

    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.