Una spec ejecutable para agentes de código es una especificación que ya incluye criterios de aceptación, límites de archivos, comandos de verificación y reglas de parada. No intenta convencer al agente con más prosa. Crea un contrato que Codex, Claude Code, subagentes y CI pueden ejecutar, fallar y repetir.

En 2026, GitLab informó que 85% de los encuestados está de acuerdo en que la IA movió el cuello de botella desde escribir código hacia revisarlo y validarlo (GitLab, "AI Accountability Report", 2026, consultado en 2026-07-07). La respuesta práctica no son prompts más largos. Son specs que se convierten en prueba.

Resumen práctico

  • Un agente obedece mejor cuando la spec define aceptación, alcance y pruebas.
  • La issue debe apuntar a archivos, riesgos, comandos y evidencia esperada.
  • CI necesita exigir la spec, no solo ejecutar la suite genérica.
  • Los subagentes ayudan cuando cada uno valida una parte pequeña del contrato.

Diagrama abstracto muestra una especificación convertida en flujo validado de agente de código sin texto visible.

¿Por qué la spec ejecutable se volvió urgente?

En 2026, GitLab también informó que 82% ve el código generado por IA como riesgo de una nueva forma de deuda técnica que la organización aún no sabe gestionar (GitLab, "AI Accountability Report", 2026, consultado en 2026-07-07). La spec ejecutable se volvió urgente porque el costo pasó de crear a verificar.

El error común es tratar una issue como conversación. Una conversación permite ambigüedad, suposiciones y justificación posterior. El agente rellena huecos con patrones del repositorio, y eso puede funcionar en tareas pequeñas. En trabajo real, el hueco se convierte en deriva de alcance.

Una spec ejecutable cambia la forma del pedido. Dice qué comportamiento debe cambiar, dónde debe mirar el agente, qué comandos deben pasar y qué riesgo exige detenerse. El agente todavía puede equivocarse. La diferencia es que el error deja evidencia verificable.

Este enfoque complementa el artículo sobre evals de PR para agentes en CI. El eval mide el cambio después. La spec ejecutable define, antes de la primera edición, qué evidencia contará como éxito.

Cápsula citable: La spec ejecutable reduce deuda técnica de agentes porque reemplaza intención suelta por contrato verificable. GitLab informó 82% de preocupación por deuda técnica generada por IA; por eso cada tarea delegada necesita aceptación, alcance, comando y evidencia antes del patch.

¿Qué entra en una spec para Codex o Claude Code?

En 2025, DORA encontró que 90% de los profesionales de tecnología ya usa IA en el trabajo, y más de 80% cree que aumentó su productividad (DORA, "Balancing AI tensions", 2026, consultado en 2026-07-07). Esa adopción solo se vuelve entrega sostenible cuando la spec describe el sistema, no solo el deseo.

La estructura mínima tiene seis partes. Primero, comportamiento esperado en lenguaje comprobable. Segundo, archivos o módulos probables. Tercero, comandos obligatorios. Cuarto, riesgos y límites. Quinto, evidencia que debe aparecer en el PR. Sexto, reglas de parada cuando la prueba falla.

Addy Osmani resume el mismo patrón como seis áreas centrales: comandos, pruebas, estructura del proyecto, estilo de código, flujo de git y fronteras (Addy Osmani, "How to write a good spec for AI agents", 2026, consultado en 2026-07-07). Yo agrego un detalle operativo: cada área debe convertirse en algo que CI o un revisor pueda negar.

objetivo: "corregir renovación de sesión expirada"
aceptacion:
  - "token revocado no renueva sesión"
  - "token válido preserva comportamiento actual"
archivos_probables:
  - "src/auth/session.service.ts"
  - "tests/auth/session-renewal.spec.ts"
comandos_obligatorios:
  - "npm run test -- session-renewal"
  - "npm run typecheck"
limites:
  - "no cambiar schema de base sin migración"
  - "no relajar regla de expiración"
evidencia_en_pr:
  - "prueba que fallaba antes"
  - "salida de comandos obligatorios"
parar_si:
  - "la falla exige acceso a secreto"
  - "la corrección toca autenticación fuera del módulo"

Cápsula citable: Una buena spec para Codex o Claude Code debe cubrir comportamiento, contexto, comando, límite y evidencia. DORA midió adopción de IA por 90% de profesionales; sin contrato ejecutable, esa adopción amplifica productividad y fragilidad operacional.

¿Cómo conectar spec, TDD y CI sin burocracia?

En 2026, GitHub afirmó que Copilot code review procesó más de 60 millones de revisiones y que más de una de cada cinco revisiones en GitHub involucra a un agente (GitHub, "Agent pull requests are everywhere. Here's how to review them", 2026, consultado en 2026-07-07). TDD con agentes necesita caber en ese volumen.

Empieza pequeño: convierte cada criterio de aceptación en al menos una comprobación. Puede ser prueba unitaria, contrato de API, snapshot visual, migración reversible, typecheck o script de lint. La regla es simple: si el criterio no puede probarse, debe reescribirse.

Bucle abstracto muestra especificación, implementación, validación y retorno sin texto visible.

No le pidas al agente solo "crear pruebas". Pídele crear la prueba que falla antes de la corrección, ejecutar la prueba, aplicar el patch y repetir la verificación. Cuando el agente no puede mostrar la falla inicial, debe explicar por qué ese criterio necesita otro tipo de prueba.

OpenAI describe el loop de Codex como una secuencia donde el modelo decide, usa herramientas, observa el resultado e intenta de nuevo hasta concluir (OpenAI, "Unrolling the Codex agent loop", 2026, consultado en 2026-07-07). La spec ejecutable le da al loop una función objetivo menor: pasar contratos correctos, no agradar al prompt.

Experiencia práctica: cuando dejo que un agente toque backend, el primer archivo que quiero ver en el diff es una prueba, contrato o fixture. Si el primer diff es implementación amplia sin prueba, detengo el loop y pido una spec menor.

Cápsula citable: TDD con agente funciona mejor cuando la spec se vuelve checklist de CI. GitHub reportó más de 60 millones de revisiones con Copilot code review; a ese volumen, el revisor necesita falla reproducible, prueba nueva y comandos ejecutados, no resúmenes persuasivos.

¿Dónde entra el contexto sin gastar tokens?

En 2026, OpenAI escribió que runs de Codex pueden trabajar más de seis horas en una sola tarea y que el contexto es uno de los mayores desafíos en tareas grandes (OpenAI, "Harness engineering: leveraging Codex in an agent-first world", 2026, consultado en 2026-07-07). La spec ejecutable también es economía de contexto.

Una mala spec pega documentación completa en el prompt. Una buena spec apunta rutas. Dice qué archivo indexa arquitectura, qué contrato es canónico, qué prueba representa el comportamiento y qué directorio está prohibido. El agente lee bajo demanda.

Es el mismo principio de context engineering para agentes de código: mapa primero, detalle después. Cuando el flujo involucra Claude Code y Codex durante muchas etapas, uso RemoteCode para mantener continuidad de contexto en flujos agentic sin volcar todo el historial en el prompt principal; es una herramienta mía, así que esta mención es editorial y ligada al costo de contexto.

La spec también debe limitar MCP. Si el agente necesita leer ticket, log o documentación viva, registra qué servidor MCP puede usarse y qué acciones siguen bloqueadas. El contexto externo ayuda a investigar, pero no debe autorizar escritura, shell o red por sí solo.

Cápsula citable: La spec ejecutable ahorra contexto porque apunta fuentes canónicas en vez de cargar todo. OpenAI relató runs largos de Codex y trató el contexto como desafío central; por eso la spec debe funcionar como mapa, con lectura progresiva y límites explícitos.

¿Cómo validan subagentes una spec sin crear ruido?

En 2025, el estudio "What Makes a GitHub Issue Ready for Copilot?" analizó 3.180 PRs asociados a issues y propuso 32 criterios para medir preparación de issues para agentes (arXiv, "What Makes a GitHub Issue Ready for Copilot?", 2025, consultado en 2026-07-07). Los subagentes funcionan mejor cuando cada criterio se vuelve una revisión estrecha.

Un subagente puede validar pruebas. Otro puede mirar la frontera de seguridad. Otro puede comparar el diff con los archivos objetivo. Otro puede revisar riesgo de migración. El agente principal no necesita logs completos; necesita hallazgo, severidad, prueba y acción.

OpenAI documenta que Codex solo crea subagentes cuando lo pides explícitamente y consolida resultados cuando todos terminan (OpenAI Developers, "Subagents", 2026, consultado en 2026-07-07). Eso favorece fan-out de lectura y merge de decisión, no varios autores editando el mismo módulo.

Matriz abstracta muestra señales de aceptación, riesgo y evidencia para revisión por subagentes sin texto visible.

Usa una salida corta y estandarizada:

area: pruebas
estado: bloquear
archivo: tests/auth/session-renewal.spec.ts
prueba: no hay caso para token revocado
accion: crear caso negativo antes de cambiar implementación

Cápsula citable: Los subagentes son útiles cuando la spec separa criterios verificables. El estudio sobre issues listas para Copilot evaluó 32 criterios en 3.180 PRs; en la práctica, cada subagente debe validar una parte del contrato y devolver prueba corta.

¿Cuál es el mínimo viable para usar esta semana?

En 2026, GitLab informó que apenas 28% dice tener herramientas de ciclo de desarrollo totalmente integradas con datos y flujos compartidos (GitLab, "AI Accountability Report", 2026, consultado en 2026-07-07). El mínimo viable debe caber en el repositorio que ya tienes.

Crea un template de issue llamado agent-task.yml. Debe exigir comportamiento esperado, archivos probables, comandos, riesgos y evidencia de PR. Si el equipo usa AGENTS.md, pon ahí la regla de que los agentes no empiezan implementación sin esos campos.

Luego crea un script pequeño, como scripts/check-agent-spec.mjs, para validar presencia de campos y bloquear PR sin evidencia. No intentes automatizar todo el juicio el primer día. Primero impide el peor caso: agente trabajando en tarea ambigua sin prueba, alcance ni evidencia.

Por último, conéctalo al PR. El cuerpo del PR debe mostrar comandos ejecutados, prueba nueva, riesgo residual y cualquier desvío de la spec. Si el agente cambió el alcance, el PR debe pedir revisión humana antes de continuar.

Campo de la spec Quién lo exige Bloquea cuando
Criterio de aceptación Prueba o revisor No hay evidencia ejecutada.
Archivos probables Script de diff El patch toca frontera sin justificación.
Comandos CI El comando falla o no se ejecutó.
Riesgo Code owner Área sensible cambia sin revisión.
Evidencia Template de PR El resumen no muestra salida verificable.

Cápsula citable: El mínimo viable es un template de issue, un checker de campos y un template de PR con evidencia. Como solo 28% reporta SDLC totalmente integrado, la spec ejecutable debe empezar como archivo simple y evolucionar hacia gate.

Preguntas frecuentes sobre spec ejecutable

¿La spec ejecutable reemplaza producto o arquitectura?

No. En 2026, GitLab informó que 85% ve revisión y validación como cuello de botella, y eso incluye juicio humano. La spec ejecutable elimina ambigüedad repetible, pero producto, arquitectura y riesgo de negocio siguen exigiendo decisión de personas responsables.

¿Toda tarea de agente necesita TDD formal?

No. En 2026, GitHub informó que más de una de cada cinco revisiones involucra a un agente, así que el proceso debe ser proporcional. Bug y regla de negocio piden prueba que falla antes. Refactor puede pedir typecheck, snapshot, comparación de contrato o análisis de diff.

¿La spec debe vivir en el prompt, la issue o el repositorio?

Usa los tres en capas. En 2026, OpenAI recomienda que Codex reciba pruebas, checks y revisión como parte de lo que significa "bien". La issue define la tarea; el repositorio guarda reglas estables; el prompt apunta solo a la parte necesaria.

¿Cómo medir si la spec mejoró al agente?

Mide retrabajo. En 2025, el estudio sobre issues listas para Copilot usó 3.180 PRs y asoció issues bien delimitadas con mayor probabilidad de merge. En tu equipo, compara PRs reabiertos, comentarios repetidos, fallas posmerge y tiempo hasta evidencia suficiente.

Cierre

La spec ejecutable es el antídoto contra requisito suelto en flujos agentic. No vuelve al agente "más inteligente". Vuelve el trabajo más pequeño, verificable y exigible. Eso es ingeniería de software aplicada a agentes.

Empieza por la próxima issue. Escribe aceptación, archivos probables, comandos, límites y evidencia. Pídele al agente que pruebe antes de explicar. Si la prueba falla, la spec cumplió su función: impidió que una narrativa pulida se convirtiera en deuda silenciosa.

Fuentes consultadas

  • GitLab, "AI Accountability Report", consultado en 2026-07-07, https://ir.gitlab.com/news/news-details/2026/GitLab-Research-Reveals-Organizations-Are-Generating-AI-Code-Faster-Than-They-Can-Control-It/default.aspx
  • DORA, "Balancing AI tensions: Moving from AI adoption to effective SDLC use", consultado en 2026-07-07, https://dora.dev/insights/balancing-ai-tensions/
  • GitHub, "Agent pull requests are everywhere. Here's how to review them", consultado en 2026-07-07, https://github.blog/ai-and-ml/generative-ai/agent-pull-requests-are-everywhere-heres-how-to-review-them/
  • OpenAI, "Unrolling the Codex agent loop", consultado en 2026-07-07, https://openai.com/index/unrolling-the-codex-agent-loop/
  • OpenAI, "Harness engineering: leveraging Codex in an agent-first world", consultado en 2026-07-07, https://openai.com/index/harness-engineering/
  • OpenAI Developers, "Subagents", consultado en 2026-07-07, https://developers.openai.com/codex/subagents
  • OpenAI Developers, "Best practices", consultado en 2026-07-07, https://developers.openai.com/codex/learn/best-practices
  • Addy Osmani, "How to write a good spec for AI agents", consultado en 2026-07-07, https://addyosmani.com/blog/good-spec/
  • arXiv, "What Makes a GitHub Issue Ready for Copilot?", consultado en 2026-07-07, https://arxiv.org/html/2512.21426v1