Spec executável para agentes de código é uma especificação que já nasce com critério de aceite, fronteira de arquivos, comandos de verificação e regra de parada. Ela não tenta convencer o agente por texto. Ela cria um contrato que Codex, Claude Code, subagentes e CI conseguem executar, falhar e repetir.

Em 2026, a GitLab relatou que 85% dos respondentes concordam que a IA deslocou o gargalo da escrita para revisão e validação de código (GitLab, "AI Accountability Report", 2026, consultado em 2026-07-07). A resposta prática não é escrever prompts maiores. É escrever specs que viram prova.

Resumo prático

  • Um agente obedece melhor quando a spec define aceite, escopo e teste.
  • A issue deve apontar arquivos, riscos, comandos e evidência esperada.
  • O CI precisa cobrar a spec, não só rodar a suíte genérica.
  • Subagentes ajudam quando cada um valida uma parte pequena do contrato.

Diagrama abstrato mostra uma especificação virando um fluxo de agente de código com validação visual sem texto.

Por que spec executável virou prioridade?

Em 2026, a GitLab também relatou que 82% veem código gerado por IA como risco de uma nova forma de dívida técnica que a organização ainda não sabe gerenciar (GitLab, "AI Accountability Report", 2026, consultado em 2026-07-07). Spec executável virou prioridade porque o custo mudou da criação para a verificação.

O erro comum é tratar a issue como conversa. Uma conversa permite ambiguidade, suposição e justificativa depois do fato. O agente preenche buracos com padrões do repositório, e isso pode funcionar em tarefas pequenas. Em tarefas reais, o buraco vira difusão de escopo.

Uma spec executável muda a forma do pedido. Ela diz qual comportamento deve mudar, onde o agente deve procurar, quais comandos precisam passar e que risco exige parada. O agente ainda pode errar. A diferença é que o erro deixa rastro verificável.

Esse recorte complementa o post sobre evals de PR para agentes no CI. O eval mede a mudança depois. A spec executável define, antes da primeira edição, que evidência vai contar como sucesso.

Cápsula citável: Spec executável reduz dívida técnica de agentes porque troca intenção solta por contrato verificável. A GitLab relatou 82% de preocupação com dívida técnica gerada por IA; por isso, cada tarefa delegada precisa trazer aceite, escopo, comando e evidência antes do patch.

O que entra numa spec para Codex ou Claude Code?

Em 2025, a DORA encontrou que 90% dos profissionais de tecnologia já usam IA no trabalho, e mais de 80% acreditam que ela aumentou sua produtividade (DORA, "Balancing AI tensions", 2026, consultado em 2026-07-07). Essa adoção só vira entrega sustentável quando a spec descreve o sistema, não apenas o desejo.

A estrutura mínima tem seis partes. Primeiro, comportamento esperado em linguagem testável. Segundo, arquivos ou módulos prováveis. Terceiro, comandos obrigatórios. Quarto, riscos e limites. Quinto, evidência que deve aparecer no PR. Sexto, regra de parada quando a prova falha.

Addy Osmani resume o mesmo padrão como seis áreas centrais: comandos, testes, estrutura do projeto, estilo de código, fluxo de git e fronteiras (Addy Osmani, "How to write a good spec for AI agents", 2026, consultado em 2026-07-07). Eu adiciono um detalhe operacional: cada área precisa virar um item que o CI ou o revisor consiga negar.

objetivo: "corrigir renovação de sessão expirada"
aceite:
  - "token revogado não renova sessão"
  - "token válido preserva comportamento atual"
arquivos_provaveis:
  - "src/auth/session.service.ts"
  - "tests/auth/session-renewal.spec.ts"
comandos_obrigatorios:
  - "npm run test -- session-renewal"
  - "npm run typecheck"
limites:
  - "não alterar schema de banco sem migração"
  - "não relaxar regra de expiração"
evidencia_no_pr:
  - "teste que falhava antes"
  - "saída dos comandos obrigatórios"
parar_se:
  - "falha exigir acesso a segredo"
  - "correção tocar autenticação fora do módulo"

Cápsula citável: Uma spec boa para Codex ou Claude Code precisa cobrir comportamento, contexto, comando, limite e evidência. DORA mediu adoção de IA por 90% dos profissionais; sem contrato executável, essa adoção amplia tanto produtividade quanto fragilidade operacional.

Como ligar spec, TDD e CI sem burocracia?

Em 2026, o GitHub afirmou que o Copilot code review processou mais de 60 milhões de revisões e que mais de uma em cada cinco revisões no GitHub envolve um agente (GitHub, "Agent pull requests are everywhere. Here's how to review them", 2026, consultado em 2026-07-07). TDD com agentes precisa caber nesse volume.

Comece pequeno: transforme cada critério de aceite em pelo menos uma checagem. Pode ser teste unitário, contrato de API, snapshot visual, migração reversível, typecheck ou script de lint. A regra é simples: se o critério não pode ser testado, ele precisa ser reescrito.

Loop abstrato mostra especificação, implementação, validação e retorno sem qualquer texto visível.

Não peça ao agente apenas para "criar testes". Peça para criar o teste que falha antes da correção, executar o teste, aplicar o patch e repetir a verificação. Quando o agente não consegue mostrar a falha inicial, ele deve explicar por que aquele critério precisa de outro tipo de prova.

OpenAI descreve o loop do Codex como uma sequência em que o modelo decide, usa ferramentas, observa resultado e tenta novamente até concluir (OpenAI, "Unrolling the Codex agent loop", 2026, consultado em 2026-07-07). A spec executável dá ao loop uma função objetivo menor: passar nos contratos certos, não agradar ao prompt.

Experiência prática: quando eu deixo um agente mexer em backend, o primeiro arquivo que quero ver no diff é teste, contrato ou fixture. Se o primeiro diff é implementação ampla sem prova, eu paro o loop e peço uma spec menor.

Cápsula citável: TDD com agente funciona melhor quando a spec vira checklist de CI. GitHub relatou mais de 60 milhões de revisões com Copilot code review; nesse volume, o revisor precisa receber falha reproduzível, teste novo e comando executado, não apenas resumo convincente.

Onde o contexto entra sem inflar tokens?

Em 2026, a OpenAI escreveu que runs de Codex podem trabalhar por mais de seis horas em uma única tarefa e que contexto é um dos maiores desafios em tarefas grandes (OpenAI, "Harness engineering: leveraging Codex in an agent-first world", 2026, consultado em 2026-07-07). Spec executável também é economia de contexto.

Uma spec ruim cola documentação inteira no prompt. Uma spec boa aponta caminhos. Ela diz qual arquivo indexa arquitetura, qual contrato é canônico, qual teste representa o comportamento e qual diretório é proibido. O agente lê sob demanda.

Esse é o mesmo princípio de context engineering para agentes de código: mapa primeiro, detalhe depois. Quando o fluxo envolve Claude Code e Codex por muitas etapas, eu uso o RemoteCode para manter continuidade de contexto em fluxos agentic sem despejar todo o histórico no prompt principal; é uma ferramenta minha, então a menção aqui é editorial e ligada a custo de contexto.

A spec também deve limitar MCP. Se o agente precisa buscar ticket, log ou documentação viva, registre qual servidor MCP pode ser usado e que ações continuam bloqueadas. Contexto externo ajuda investigação, mas não deve autorizar escrita, shell ou rede por conta própria.

Cápsula citável: Spec executável economiza contexto porque aponta fontes canônicas em vez de carregar tudo. OpenAI relatou runs longos de Codex e tratou contexto como desafio central; por isso, a spec deve funcionar como mapa, com leitura progressiva e limites explícitos.

Como subagentes validam uma spec sem virar ruído?

Em 2025, o estudo "What Makes a GitHub Issue Ready for Copilot?" analisou 3.180 PRs associados a issues e propôs 32 critérios para medir prontidão de issues para agentes (arXiv, "What Makes a GitHub Issue Ready for Copilot?", 2025, consultado em 2026-07-07). Subagentes funcionam melhor quando cada critério vira uma revisão estreita.

Um subagente pode validar testes. Outro pode olhar fronteira de segurança. Outro pode comparar o diff com os arquivos-alvo. Outro pode checar risco de migração. O agente principal não precisa receber logs completos; precisa receber achado, severidade, prova e ação.

OpenAI documenta que Codex só cria subagentes quando você pede explicitamente e consolida os resultados quando todos terminam (OpenAI Developers, "Subagents", 2026, consultado em 2026-07-07). Isso favorece fan-out de leitura e merge de decisão, não vários autores editando o mesmo módulo.

Matriz abstrata mostra sinais de aceite, risco e evidência para revisão por subagentes sem texto visível.

Use retorno curto e padronizado:

area: testes
status: bloquear
arquivo: tests/auth/session-renewal.spec.ts
prova: não há caso para token revogado
acao: criar caso negativo antes de alterar implementação

Cápsula citável: Subagentes são úteis quando a spec separa critérios verificáveis. O estudo sobre issues prontas para Copilot avaliou 32 critérios em 3.180 PRs; na prática, cada subagente deve validar uma fatia do contrato e devolver prova curta.

Qual é o mínimo viável para usar nesta semana?

Em 2026, a GitLab relatou que apenas 28% dizem ter ferramentas de ciclo de desenvolvimento totalmente integradas com dados e fluxos compartilhados (GitLab, "AI Accountability Report", 2026, consultado em 2026-07-07). O mínimo viável precisa caber no repositório que você já tem.

Crie um template de issue chamado agent-task.yml. Ele deve exigir comportamento esperado, arquivos prováveis, comandos, riscos e evidência de PR. Se o time usa AGENTS.md, coloque ali a regra de que agentes não começam implementação sem esses campos.

Depois crie um script pequeno, como scripts/check-agent-spec.mjs, para validar presença dos campos e bloquear PR sem evidência. Não tente automatizar julgamento inteiro no primeiro dia. Primeiro impeça o pior caso: agente trabalhando em tarefa ambígua sem teste, sem escopo e sem prova.

Por fim, conecte ao PR. O corpo do PR precisa mostrar comandos rodados, teste novo, risco residual e qualquer desvio da spec. Se o agente mudou o escopo, o PR deve pedir revisão humana antes de continuar.

Campo da spec Quem cobra Bloqueia quando
Critério de aceite Teste ou revisor Não há prova executada.
Arquivos prováveis Script de diff O patch toca fronteira sem justificativa.
Comandos CI Comando falha ou não foi rodado.
Risco Code owner Área sensível muda sem revisão.
Evidência Template de PR O resumo não mostra saída verificável.

Cápsula citável: O mínimo viável é um template de issue, um checker de campos e um template de PR com evidência. Como só 28% relatam SDLC totalmente integrado, a spec executável precisa começar como arquivo simples e evoluir para gate.

Perguntas frequentes sobre spec executável

Spec executável substitui produto ou arquitetura?

Não. Em 2026, a GitLab relatou que 85% veem revisão e validação como gargalo, e isso inclui julgamento humano. A spec executável remove ambiguidade repetível, mas produto, arquitetura e risco de negócio continuam exigindo decisão de pessoas responsáveis.

Toda tarefa de agente precisa de TDD formal?

Não. Em 2026, o GitHub relatou mais de uma em cada cinco revisões envolvendo agente, então o processo precisa ser proporcional. Bug e regra de negócio pedem teste que falha antes. Refactor pode pedir typecheck, snapshot, comparação de contrato ou análise de diff.

A spec deve ficar no prompt, na issue ou no repositório?

Use os três em camadas. Em 2026, OpenAI recomenda que Codex receba testes, checks e revisão como parte do que "bom" significa. A issue define a tarefa; o repositório guarda regras estáveis; o prompt aponta só a fatia necessária.

Como medir se a spec melhorou o agente?

Meça retrabalho. Em 2025, o estudo sobre issues prontas para Copilot usou 3.180 PRs e associou issue bem escopada a maior chance de merge. No time, compare PRs reabertos, comentários repetidos, falhas pós-merge e tempo até prova suficiente.

Fechamento

Spec executável é o antídoto contra requisito solto em fluxo agentic. Ela não deixa o agente "mais inteligente". Ela deixa o trabalho menor, verificável e cobrável. Isso é engenharia de software aplicada a agentes.

Comece pela próxima issue. Escreva aceite, arquivos prováveis, comandos, limites e evidência. Peça ao agente para provar antes de explicar. Se a prova falhar, a spec fez seu trabalho: impediu que uma narrativa bonita virasse dívida silenciosa.

Fontes consultadas

  • GitLab, "AI Accountability Report", consultado em 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 em 2026-07-07, https://dora.dev/insights/balancing-ai-tensions/
  • GitHub, "Agent pull requests are everywhere. Here's how to review them", consultado em 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 em 2026-07-07, https://openai.com/index/unrolling-the-codex-agent-loop/
  • OpenAI, "Harness engineering: leveraging Codex in an agent-first world", consultado em 2026-07-07, https://openai.com/index/harness-engineering/
  • OpenAI Developers, "Subagents", consultado em 2026-07-07, https://developers.openai.com/codex/subagents
  • OpenAI Developers, "Best practices", consultado em 2026-07-07, https://developers.openai.com/codex/learn/best-practices
  • Addy Osmani, "How to write a good spec for AI agents", consultado em 2026-07-07, https://addyosmani.com/blog/good-spec/
  • arXiv, "What Makes a GitHub Issue Ready for Copilot?", consultado em 2026-07-07, https://arxiv.org/html/2512.21426v1