Desenvolvimento orientado por especificação com IA

Desenvolvimento orientado por especificação (spec-driven development) é um jeito de trabalhar com agentes de código com IA em que uma spec escrita vem antes de qualquer código. Você descreve o que construir, por que e como vai saber que está pronto. O agente transforma essa spec num plano técnico, divide o plano em tarefas pequenas, implementa uma de cada vez e o resultado é verificado contra os critérios de aceitação da spec. Spec, plano e tarefas são arquivos no seu repositório, não mensagens perdidas num chat, então sobrevivem à sessão e podem ser revisados como código.

Este guia explica o ciclo, compara as ferramentas que o suportam em outubro de 2026 (GitHub Spec Kit, specs do Kiro, OpenSpec e os plan modes do Claude Code e do Codex), percorre um exemplo pequeno com um arquivo de spec real e os prompts, e lista as armadilhas. Os dados de cada ferramenta foram conferidos em outubro de 2026 na documentação oficial e no repositório de cada projeto.

Por que a spec importa mais com agentes

Um desenvolvedor que recebe um ticket vago faz perguntas. Um agente que recebe um prompt vago geralmente chuta, escreve um código plausível e diz que terminou. A distância entre “o código foi escrito” e “a funcionalidade faz o que você queria” é de onde vem quase todo o retrabalho.

Uma spec fecha essa distância de três formas:

• Obriga a decidir antes. Casos extremos, estados de erro e o que fica de fora vão para o papel antes que o agente escolha por você.
• Dá a cada etapa a mesma fonte de verdade. Plano, tarefas e revisão apontam para um arquivo, não para o que você lembra de uma conversa.
• Torna “pronto” verificável. Critérios de aceitação transformam a revisão de “parece ok” em “o critério 3 passa, este é o teste”.

Nada disso é novo: documentos de requisitos e testes de aceitação são ideias antigas. O que mudou é que os agentes são tão rápidos que escrever a spec virou a parte lenta e valiosa, e o código, a parte barata.

O ciclo: spec, plano, tarefas, implementação, verificação

Duas regras fazem o ciclo funcionar. Primeira: a spec fala de comportamento e o plano, de implementação. “Usuários podem redefinir a senha por e-mail” vai na spec; “criar uma tabela reset_tokens” vai no plano. Segunda: pare e revise a cada etapa. Todas as ferramentas abaixo foram feitas em torno dessa pausa; se você pula, o desenvolvimento orientado por especificação volta a ser um prompt comprido.

Ferramentas para desenvolvimento orientado por especificação

GitHub Spec Kit

O Spec Kit é o kit do GitHub para desenvolvimento orientado por especificação. Chegou à 1.0 este ano e, em outubro de 2026, a versão mais recente é a v1.2.4. Ele não substitui o seu agente: a CLI specify instala modelos e comandos no projeto, e você roda as etapas no chat do agente. Exige Python 3.11 ou mais recente, uv e um agente compatível no macOS, Linux ou Windows.

uv tool install specify-cli
specify init my-project --integration claude
# num repositório existente:
specify integration install claude

A lista de integrações cobre mais de 40 agentes, entre eles Claude Code (claude), Codex CLI (codex), Gemini CLI (gemini), GitHub Copilot (copilot), Cursor (cursor-agent), Kiro CLI (kiro-cli), opencode, Qwen Code e Amp. A documentação escreve os comandos como /speckit.specify e assim por diante; como você digita depende do agente. No Claude Code eles são instalados como skills em .claude/skills/ e chamados como /speckit-specify; no Codex, como $speckit-specify.

O caminho curto é specify → plan → tasks → implement → converge. Para funcionalidades que vão para produção, a documentação recomenda o caminho completo:

1. /speckit-constitution, uma vez por projeto, para princípios como regras de teste.
2. /speckit-specify escreve a spec da funcionalidade a partir de uma descrição simples.
3. /speckit-clarify faz até cinco perguntas direcionadas e grava as respostas na spec.
4. /speckit-plan escreve o plano técnico a partir do seu stack e das suas restrições.
5. /speckit-checklist gera “testes unitários para os seus requisitos”.
6. /speckit-tasks produz um tasks.md ordenado por dependência.
7. /speckit-analyze é uma checagem de consistência somente leitura entre spec, plano e tarefas.
8. /speckit-implement executa as tarefas em ordem.
9. /speckit-converge compara o código com a spec e acrescenta ao tasks.md o que faltou.

Você repete implement e converge até o converge responder Converged. A documentação recomenda rodar cada comando separadamente e revisar o resultado antes do próximo.

Specs do Kiro

O Kiro traz as specs para dentro do produto. Cada spec tem três arquivos em .kiro/specs/<nome>/: requirements.md (ou bugfix.md para um bug), design.md e tasks.md. Os requisitos são escritos na notação EARS, no formato “WHEN [condição] THE SYSTEM SHALL [comportamento]”. Specs de funcionalidade podem começar pelos requisitos ou pelo design, e o Quick Spec gera os três arquivos de uma vez, sem as paradas de aprovação no meio.

Na CLI do Kiro você começa com /spec new <nome> e roda as tarefas com /spec run <nome>. Quando você roda todas as tarefas, o Kiro monta um grafo de dependências a partir do tasks.md e executa as tarefas independentes em ondas paralelas. Em outubro de 2026, o Kiro tem um plano gratuito com 50 créditos e planos pagos a partir de US$ 20 por usuário por mês.

O Kiro é a melhor escolha se você quer o fluxo de specs com uma interface de revisão embutida e não se importa de trabalhar dentro do Kiro. Se prefere continuar no Claude Code ou no Codex, o Spec Kit ou o OpenSpec se encaixam melhor.

OpenSpec

O OpenSpec é uma alternativa mais leve, com licença MIT, organizada em torno de mudanças. /opsx:propose add-dark-mode cria openspec/changes/add-dark-mode/ com proposal.md, uma pasta specs/ de requisitos e cenários, design.md e tasks.md. /opsx:apply executa as tarefas, e /opsx:archive move a mudança para o arquivo e atualiza as specs. /opsx:explore é uma etapa para pensar antes de se comprometer com uma proposta.

npm install -g @fission-ai/openspec@latest   # exige Node.js 20.19.0+
cd your-project
openspec init

Também há um binário independente e uma fórmula do Homebrew. A grafia dos comandos muda conforme o agente, por exemplo $openspec-propose no Codex; o openspec init mostra a forma certa para as ferramentas que você escolher. Em outubro de 2026, a versão mais recente é a v1.15.0.

Plan mode no Claude Code e no Codex

Os plan modes cobrem uma etapa do ciclo: o plano. No plan mode do Claude Code o agente lê arquivos, explora e depois propõe um plano; as edições continuam bloqueadas até você aprovar. Você ativa com Shift+Tab, com /plan antes de um prompt ou com claude --permission-mode plan.

A CLI do Codex tem /plan, que passa o chat para plan mode e aceita o primeiro pedido na mesma linha, por exemplo /plan Propose a migration plan for this service. O Codex também tem /goal, que define um objetivo persistente para uma tarefa maior e pode ser pausado, retomado ou apagado.

Os plan modes funcionam bem num fluxo orientado por specs sem ferramenta extra. O que falta é persistência: peça ao agente para gravar o plano aprovado e as tarefas em arquivos, para que a próxima sessão comece deles e não do zero.

Um exemplo prático: um arquivo de spec e quatro prompts

Esta é a versão faça-você-mesmo, que funciona com Claude Code, Codex ou qualquer agente que leia arquivos. A funcionalidade: limitar logins com falha num pequeno app web.

1. Escreva a spec

Salve isto como specs/login-rate-limit/spec.md:

# Login rate limiting

## Goal
Slow down password guessing on POST /login without bothering normal users.

## Non-goals
- No CAPTCHA.
- No change to how passwords are stored.

## Acceptance criteria
1. WHEN an IP has 5 failed logins within 15 minutes,
   THE SYSTEM SHALL answer further attempts with HTTP 429 for 15 minutes.
2. WHEN a login succeeds, THE SYSTEM SHALL reset that IP's failure count.
3. The 429 response SHALL include a Retry-After header in seconds.
4. Limits SHALL be configurable through LOGIN_MAX_FAILS and LOGIN_WINDOW_MIN.
5. Existing login tests SHALL still pass, and new tests SHALL cover 1–4.

## Constraints
- Use the existing Redis connection; no new services.

## Open questions
- Should the limit be per IP, per account, or both?

Não passe de uma tela. A seção de perguntas em aberto está ali de propósito: dá ao agente um lugar para questionar antes de planejar. Você também pode escrever a spec em português; os agentes leem os dois idiomas.

2. Esclareça e planeje

Comece em plan mode e aponte o agente para o arquivo:

Read specs/login-rate-limit/spec.md and the auth code.
First, ask me about anything ambiguous, starting with the open questions.
Then write a plan to specs/login-rate-limit/plan.md: files to change,
data stored in Redis and its expiry, how each acceptance criterion
will be tested, and risks. Don't edit any source files.

Responda às perguntas e depois leia o plano. Conteste tudo o que ignorar uma restrição.

3. Divida em tarefas

Turn plan.md into specs/login-rate-limit/tasks.md: a numbered checklist
of tasks small enough to review in one diff. For each task, list the
files it touches and the test that proves it. Order them by dependency.

4. Implemente uma tarefa por vez

Do task 1 from specs/login-rate-limit/tasks.md only. Run the tests,
tick the task in tasks.md, and stop. Tell me if the spec or plan
turned out to be wrong.

Uma tarefa por prompt mantém os diffs pequenos e dá a você um ponto natural de revisão. Se uma tarefa mostrar que a spec estava errada, corrija a spec primeiro e depois continue.

5. Verifique contra a spec

Com as tarefas prontas, confira o resultado contra a spec, de preferência numa sessão nova ou com outro agente, para que quem revisa não seja quem escreveu o código:

Read specs/login-rate-limit/spec.md. For each acceptance criterion,
find the code and the test that cover it, run the tests, and report
PASS or FAIL with evidence. Don't change any code.

Esse é o ciclo inteiro. Faça commit da pasta specs/ junto com o código, para que a próxima pessoa, ou o próximo agente, entenda por que o código é assim. Para escrever bem os prompts em si, veja prompts para agentes de código com IA.

Armadilhas

• Specs que na verdade são planos. Se a spec cita tabelas e funções, o agente não consegue propor um design melhor e quem revisa não separa comportamento de implementação. Deixe o “como” no plan.md.
• Specs longas demais. Uma spec de dez páginas consome o contexto e ninguém lê, nem o agente. Uma tela por funcionalidade é um bom limite; divida as maiores.
• Aprovar sem ler. Uma spec ou um plano que ninguém leu é só um prompt mais lento. A pausa para revisão é o ponto central.
• Tarefas grandes demais. Se uma tarefa gera um diff que você não consegue revisar de uma vez, divida.
• Deixar a spec desatualizar. Quando o código ensinar algo, atualize a spec. Uma spec que contradiz o código é pior que nenhuma.
• Deixar o autor verificar. O agente que escreveu o código tende a aprovar o próprio trabalho. Use uma sessão nova, um segundo modelo ou uma pessoa na checagem final.
• Usar para tudo. Uma correção de uma linha não precisa de spec. Guarde o processo para funcionalidades com casos extremos ou vários arquivos.
• Misturar regras do projeto em cada spec. Regras fixas, como comandos de teste e estilo de código, vão no CLAUDE.md ou AGENTS.md ou numa constitution do Spec Kit, não em cada spec de funcionalidade.

Desenvolvimento orientado por especificação no AgentVera

O AgentVera é um app desktop para macOS, Windows e Linux que roda Claude Code, Codex, Kiro e outras CLIs de código lado a lado. Cada painel é a CLI de verdade, então os comandos do Spec Kit, os do OpenSpec, o /spec do Kiro e o plan mode funcionam ali como funcionam sozinhos. Alguns recursos do AgentVera seguem o mesmo formato de spec, plano, construção e verificação:

• Linha de tarefas: uma linha fixa de agentes de Análise, Plano, Construção e Revisão. Cada tarefa recebe critérios de aceitação, a Análise grava 01-analiz.md, o Plano grava 02-plan.md e o revisor marca cada critério com evidência. Uma tarefa rejeitada volta para a Construção com os apontamentos.
• AgentVera Verify: extrai os critérios de aceitação da mensagem que você envia a um agente e, quando o turno dele termina, um verificador separado lê o diff, roda os comandos de teste permitidos e marca cada critério como aprovado ou reprovado. O verificador não pode editar arquivos.
• Equipe paralela: um agente divide um trabalho grande em até 8 partes, cada uma com seu prompt, critérios de aceitação, arquivos esperados e dependências, roda as partes em worktrees separadas e junta tudo numa branch e num PR.
• Kanban de equipe: um card pode ir para um agente de código como tarefa, e a resposta do agente volta como comentário. Veja kanban para agentes de IA.
• Revisão de código automática: quando um turno termina, o modelo Claude que você escolher revisa o código e lista os apontamentos com links arquivo:linha.

Linha de tarefas, Verify, equipe paralela e kanban de equipe estão nos planos Pro e Team. Se você só precisa dos arquivos de spec e dos comandos, o Spec Kit e o OpenSpec são gratuitos e funcionam em qualquer terminal; o AgentVera ajuda quando vários agentes trabalham com specs ao mesmo tempo.

Concluindo

Desenvolvimento orientado por especificação é escrever o “o quê” e o “como vou saber que está certo” antes de o agente escrever código, e amarrar cada etapa seguinte a esse arquivo. Comece com um spec.md de uma tela e o plan mode. Passe para o Spec Kit ou o OpenSpec quando quiser modelos e checagens de consistência, ou para o Kiro se quiser o fluxo dentro do editor. Seja qual for a escolha, revise a cada etapa e verifique contra os critérios, não contra o resumo do agente.

Leia também:

• Plan mode do Claude Code
• Prompts para agentes de código com IA
• Linha de tarefas

Para experimentar o AgentVera, baixe aqui.