Spec driven development na prática com Spec Kit e Kiro

O objetivo não é produzir mais documentação. É chegar a um acordo enxuto que permita ao fundador rejeitar um comportamento inadequado, ao engenheiro questionar o desenho técnico e a quem revisa identificar as evidências necessárias para aprovar o merge.

Na primeira tentativa, escolha uma funcionalidade de escopo bem definido no repositório que você já usa. Uma exportação, uma regra de aprovação ou uma preferência de notificação deixa o valor do método mais claro do que pedir a um agente que especifique uma aplicação inteira.

O que é spec driven development?

Desenvolvimento orientado a especificações com agentes de IA significa usar uma descrição revisada do comportamento desejado para orientar o planejamento, a criação de tarefas, a implementação e a verificação. A especificação define o que deve acontecer e por quê. O plano explica como a aplicação existente vai fazer isso acontecer. As tarefas dividem o plano em entregas que podem ser verificadas.

Antes da IA, práticas relacionadas já usavam especificações como testes executáveis, como no desenvolvimento orientado a comportamento, ou BDD. Essa tradição é compatível com o fluxo apresentado aqui, mas uma especificação em Markdown, por si só, não é um teste executável. Documentação de BDD do Cucumber.

A mudança prática é que os agentes de programação podem consultar esses documentos ao longo da implementação. O GitHub Spec Kit, um kit de ferramentas de código aberto para organizar o trabalho de um agente, fornece o processo ao redor dele. O Kiro, ambiente de programação da AWS, incorpora ao produto um fluxo baseado em especificações. Nenhum dos dois dispensa a decisão sobre o que o cliente deve vivenciar.

Documentação verificada em 13 de outubro de 2026: os nomes de comandos, caminhos de arquivos e recursos abaixo vêm da documentação atual do GitHub, do Kiro, da Anthropic e da OpenAI. O passo a passo da funcionalidade é um exemplo ilustrativo; não representa uma implantação em produção nem um teste com resultados de produtividade medidos.

Para quem desenvolve, o efeito é um escopo de implementação menor: o agente deve reaproveitar a aplicação ao redor da funcionalidade, em vez de redesenhá-la. Para quem opera o negócio e para fundadores, a revisão mais valiosa acontece antes: decida quem pode exportar dados antes de revisar o botão de exportação. Para quem contrata as ferramentas, adotar o método não exige migrar todos os desenvolvedores para outro editor. Comece com o agente que você já tem; invista em mais estrutura quando manter os documentos passar a ser o problema.

Tutorial de spec driven development: o fluxo na prática

Mantenha os documentos separados, porque cada um responde a uma pergunta diferente. Um diagrama de arquitetura não resolve uma regra de produto que ninguém definiu, e uma lista de tarefas não comprova que a funcionalidade funciona.

O fundador ou responsável pelo produto decide o comportamento. A liderança de engenharia responde pela adequação do desenho técnico ao sistema. O agente pode redigir as duas propostas, mas um texto bem escrito não comprova o acerto de qualquer uma dessas decisões.

Ferramentas de spec driven development: de quanta estrutura você precisa?

Escolha a ferramenta pelo ponto em que a coordenação falha. O GitHub Spec Kit atende a repositórios em que se busca um processo repetível com um agente já em uso. O Kiro atende a quem quer requisitos, desenho técnico e execução de tarefas dentro do ambiente de programação. Arquivos simples bastam para uma primeira funcionalidade ou para uma equipe que já tem uma rotina confiável de revisão.

GitHub Spec Kit: comandos e arquivos

O GitHub Spec Kit oferece instruções reutilizáveis, modelos e scripts de apoio; quem executa o trabalho é o agente de programação escolhido. O README atual explicita a sequência central: estabelecer os princípios do projeto, especificar a funcionalidade, planejá-la, criar tarefas, implementar e verificar o que ainda falta.

O README atual exige Python 3.11 ou mais recente, uv (um instalador de pacotes Python) e um agente compatível. O exemplo de configuração usa o GitHub Copilot, assistente de programação do GitHub. Execute no terminal:

uv tool install specify-cli
specify init my-project --integration copilot
cd my-project

Em seguida, inicie o agente de programação nesse diretório. Execute cada instrução do fluxo no chat do agente e revise o resultado antes de continuar. Essas instruções não são comandos de shell.

A diferença na nomenclatura importa. O README usa a sintaxe padrão de skills do Copilot, /speckit-specify. A referência detalhada de comandos usa a forma com ponto, /speckit.specify. A integração de skills do Codex usa $speckit-specify. Use a sintaxe da integração instalada; os sinais de pontuação não são intercambiáveis. Referência de integrações.

Esses nomes e funções seguem a referência de Agentic SDD do GitHub. Clarify, checklist e analyze são etapas adicionais de controle de qualidade. A constituição estabelece regras permanentes do projeto; não a reescreva a cada pequena funcionalidade.

No exemplo de exportação, a instrução de specify deve descrever quem pode exportar, quais registros entram no arquivo, seu conteúdo e o comportamento em caso de falha. Informe a stack existente e as restrições do repositório na etapa de planejamento. Peça explicitamente testes de aceitação: o comando de tarefas documenta a geração de testes quando solicitada, portanto uma lista de tarefas gerada não comprova que os testes adequados foram incluídos.

Os arquivos que precisam de revisão são:

• .specify/memory/constitution.md: princípios do projeto. Modelo de constituição.
• specs/<feature-directory>/spec.md: comportamento da funcionalidade. Os diretórios de funcionalidades normalmente ficam em specs/; o nome do diretório é gerado ou configurado. Modelo de especificação.
• plan.md e tasks.md nesse diretório: desenho da implementação e divisão do trabalho. O planejamento também gera research.md, data-model.md e quickstart.md, além de contracts/ para interfaces externas quando aplicável. Modelo de plano, referência de tarefas.

Depois da implementação, converge compara a base de código com a especificação, o plano e as tarefas. Se encontrar lacunas, acrescenta trabalho a tasks.md; ele não corrige o código por conta própria. Implemente o trabalho adicionado e verifique novamente. Um resultado “Converged” ajuda na revisão, mas não substitui seus testes nem sua aprovação.

Para uma aplicação existente, o guia de adoção do GitHub começa com a preservação do estado de referência e inicializa o kit no próprio projeto. O comando é specify init --here --force --integration <key>, substituindo <key> pela chave de integração documentada, como claude ou codex. O guia alerta que --force pode substituir arquivos gerenciados que estejam em conflito. Revise o diff resultante. Não é necessário reconstruir as especificações da aplicação inteira antes de especificar a próxima mudança.

O limite: o Spec Kit pode revelar contradições entre documentos e, ainda assim, aceitar uma regra de negócio errada que apareça de forma consistente em todos eles. Seus arquivos extras justificam o custo de manutenção quando várias pessoas ou sessões precisam consultar o mesmo acordo.

Desenvolvimento orientado a especificações no Kiro: specs, steering e hooks

O Kiro separa a intenção da funcionalidade, as orientações permanentes do projeto e as ações automáticas. Use specs para a funcionalidade em questão, steering para convenções de todo o repositório e hooks para verificações repetíveis.

No IDE, o editor de código do Kiro, clique em + na seção Specs, ou selecione Spec no chat. Escolha Feature e depois Requirements-First. Revise os requisitos antes de aceitar o desenho técnico e a divisão em tarefas. O diretório gerado para a funcionalidade contém .kiro/specs/<feature-name>/requirements.md, design.md e tasks.md. Depois de revisá-las, execute as tarefas pela interface correspondente. Documentação de specs do Kiro.

O Kiro usa EARS, sigla de Easy Approach to Requirements Syntax, para expressar uma condição e o comportamento esperado do sistema. Neste exemplo: “Quando um membro solicitar uma exportação, o sistema deverá negar a solicitação e não retornar nenhum arquivo de exportação.” A formulação é concreta o suficiente para virar um teste. Especificações de funcionalidades.

O Kiro também oferece Design-First e Quick Spec. Design-First parte do desenho técnico; Quick Spec cria os documentos sem as etapas intermediárias de aprovação. Se você é fundador e seu agente insiste em interpretar mal a intenção, escolha Requirements-First e aproveite essas revisões. Retirar os pontos de revisão eliminaria justamente a parte do processo que resolve esse problema.

Steering fornece contexto permanente em Markdown dentro de .kiro/steering/. Os arquivos básicos são product.md, tech.md e structure.md, que cobrem o produto, a stack e a organização do repositório. No IDE, Generate Steering Docs cria esse contexto inicial. Confira se ele corresponde ao repositório. Coloque aqui “reutilizar a política existente de autorização de membros” quando a regra valer para várias funcionalidades; já “somente proprietários podem exportar” pertence à especificação da exportação. Documentação de steering.

Hooks executam comandos de shell ou prompts de agente quando ocorre um evento. Os arquivos de hooks do projeto atualmente ficam em .kiro/hooks/<id>.json; PostFileSave é um dos gatilhos documentados. Um hook específico poderia executar os testes de exportação existentes quando o código relevante mudasse. Mantenha as mesmas verificações na integração contínua — as verificações automatizadas das mudanças de código propostas — para que o hook local não seja o único lugar onde elas rodam. A tabela atual de recursos do Kiro oferece suporte a hooks no IDE e na CLI, mas não na Web nem no Mobile. Documentação de hooks.

O limite: um requisito gerado automaticamente pode formalizar uma premissa que ninguém aprovou. Revise permissões, resultados vazios e comportamentos de falha antes do desenho técnico. O modo de especificações acrescenta estrutura; ele não toma as decisões de produto que ficaram faltando.

Como usar spec driven development com Claude Code

O Claude Code, agente de programação da Anthropic, pode seguir esse processo com uma especificação de funcionalidade e o Plan Mode. Não é preciso instalar um framework de especificações para experimentar o método.

Crie o arquivo specs/workspace-export/spec.md por conta própria ou revise um rascunho do agente. Depois, inicie a sessão de terminal em modo de planejamento:

claude --permission-mode plan

Peça ao Claude que leia o arquivo, examine o código existente relacionado à exportação e proponha um plano de implementação vinculado aos critérios de aceitação. Antes de aprovar a implementação, solicite as perguntas ainda sem resposta e a lista exata das verificações que ele pretende executar.

O Plan Mode foi feito para investigação e proposta de abordagem. A Anthropic documenta uma exceção em sessões interativas de terminal nas quais há permissões de bypass disponíveis: nesse caso, os bloqueios de edição do modo de planejamento não são aplicados. Inicie sem bypass habilitado quando quiser garantir que a implementação dependa de aprovação. Documentação dos modos de permissão.

Depois de revisar a proposta, salve a abordagem aprovada em specs/workspace-export/plan.md e seu checklist em tasks.md; então autorize a implementação. Esses caminhos são uma convenção sugerida neste artigo, não arquivos que o Plan Mode promete criar automaticamente. O guia de Plan Mode do Claude Code explica os controles e a transição para a implementação aprovada.

Mantenha as instruções permanentes do repositório em CLAUDE.md, seguindo o guia de memória da equipe, e o comportamento específico da funcionalidade na especificação. Caso contrário, um requisito temporário de exportação pode virar uma instrução permanente que afeta trabalhos sem relação com ele.

O limite: um plano que existe apenas na conversa pode se perder ou ser contradito com facilidade. Salvá-lo só ajuda se a implementação e a revisão posteriores recorrerem explicitamente a ele.

Codex: Plan Mode com o mesmo arquivo de especificação

O Codex, agente de programação da OpenAI, permite a mesma passagem simples da especificação para o planejamento. Em um chat da CLI sem execução em andamento, /plan inicia o planejamento e pode trazer o pedido na mesma mensagem. Documentação oficial dos comandos.

Um pedido útil seria: “Leia specs/workspace-export/spec.md. Examine a política existente de membros, a consulta de tarefas e os testes. Proponha o menor plano de implementação que atenda a todos os requisitos. Identifique as decisões pendentes antes da implementação.”

Revise o plano, salve os arquivos combinados e então peça ao Codex que implemente as tarefas e entregue um relatório de conclusão relacionando cada requisito ao teste correspondente. Use AGENTS.md para as instruções permanentes do repositório; /init pode gerar sua estrutura inicial. O guia de configuração da CLI do Codex cobre a preparação do ambiente.

A OpenAI também documenta o uso de Markdown para manter especificações, planos e registros de progresso em trabalhos mais longos. A vantagem é permitir que uma sessão posterior reabra o acordo. O limite: o Plan Mode não mantém uma especificação separada de funcionalidade atualizada por conta própria. Inclua essa atualização na revisão das mudanças. Fluxo documentado pela OpenAI.

Exemplo de spec driven development: exportar um workspace para CSV

Uma pequena exportação CSV — o download de registros em valores separados por vírgulas — mostra por que definir o comportamento primeiro pode evitar retrabalho em vários arquivos. “Adicionar exportação CSV” obriga o agente a adivinhar o perfil de usuário, o escopo dos dados, a paginação e o formato do arquivo. Um botão bonito pode esconder uma resposta errada para cada uma dessas questões.

O exemplo a seguir detalha uma funcionalidade em uma aplicação existente de gestão de tarefas. Os caminhos, identificadores de requisitos e testes propostos são exemplos didáticos; não representam um repositório testado nem mudanças que passaram por merge para este artigo.

A especificação em uma página

Salve o conteúdo a seguir como spec.md da funcionalidade ou coloque a mesma descrição de comportamento no requirements.md do Kiro:

Observe a decisão contida em R2: “todos os resultados que correspondem aos filtros” é diferente de “a página visível”. Resolver isso antes da implementação muda imediatamente a consulta e o plano de testes. Resolver depois da demonstração pode exigir refazer os dois.

R4 explicita de propósito uma decisão que precisa de exemplos concretos. Antes de aprovar a especificação, defina como tratar entradas que possam virar fórmulas de planilha e registre esses exemplos. Uma frase como “tornar as exportações seguras” deixaria o agente escolher a política por você.

O plano: encaixar a mudança na aplicação existente

O plano deve reutilizar a política existente de sessão e de membros, extrair ou reaproveitar a lógica dos filtros da lista de tarefas e adicionar uma resposta de exportação sem alterar a resposta da lista. Faça a exportação passar pelo controle de autorização do servidor. Determine o acesso ao workspace a partir do vínculo autenticado do usuário e só então aplique os filtros solicitados dentro desse escopo.

Use o serializador de CSV já adotado pelo repositório, se houver. Especifique os cabeçalhos de conteúdo e download, a política de segurança dos campos, o comportamento em caso de erro e os testes. Adicione o botão usando os estados de carregamento e erro atuais da aplicação.

O plano também precisa comparar o volume esperado de resultados com as restrições de requisição e memória da aplicação. Se a exportação de todos os resultados não couber nesses limites, leve o conflito de volta ao responsável pela funcionalidade. Decidam entre uma exportação limitada ou um escopo separado para processamento em segundo plano. O agente não deve inventar silenciosamente um limite máximo nem adicionar um sistema de jobs que contrarie R6.

As tarefas: tornar cada mudança verificável

Transforme o plano em trabalho que a pessoa responsável pela revisão consiga reconhecer:

1. Registre o comportamento existente da lista de tarefas e as regras compartilhadas de filtragem em verificações de regressão.
2. Adicione testes de autorização de requisições para proprietário, membro, antigo proprietário removido e outro workspace.
3. Implemente a consulta restrita ao escopo e a resposta CSV com a política de campos acordada.
4. Adicione o controle de exportação, o estado de carregamento e a apresentação de falhas.
5. Conclua as verificações de aceitação e examine o diff em busca de mudanças fora do escopo da funcionalidade.

Essa divisão em tarefas pertence ao exemplo. Um kit de ferramentas pode gerar outra lista; avalie se ela cobre o que foi combinado.

Em uma aplicação TypeScript, a mudança de código a revisar poderia incluir server/exports/tasks.ts para autorização, filtragem e resposta; ui/tasks/ExportButton.tsx para a interação; e tests/task-export.test.ts para os casos de aceitação. São caminhos ilustrativos, não convenções obrigatórias de um framework. Um novo worker de fila ou uma migração de banco de dados indicaria uma mudança de escopo a resolver antes do merge.

Dos critérios de aceitação à decisão de fazer o merge

Exija evidências do comportamento, não uma lista dos arquivos que o agente editou. A descrição do pull request deve relacionar os requisitos a verificações como estas:

Quem revisa deve comparar essas verificações com a especificação, examinar o código de autorização e consulta e experimentar o fluxo de usuário acordado no ambiente habitual de revisão do projeto. Se o agente escreveu tanto a implementação quanto os testes, revise os resultados esperados de forma independente. Um teste pode confirmar fielmente a mesma premissa errada do código.

Suponha, por exemplo, que a revisão revele que o endpoint lê apenas a página atual. Mantenha R2 se o responsável ainda quiser todos os resultados que correspondem aos filtros; corrija a consulta e adicione um teste com resultados além daquela página. Se o responsável mudar o escopo, atualize R2, o plano e os testes juntos antes da aprovação.

Faça o merge quando as evidências corresponderem ao que foi combinado: inclua a especificação revisada, o plano final, o registro das tarefas concluídas, a implementação e os testes no mesmo pull request. Registre ali qualquer mudança de escopo aceita. Depois do merge, mantenha a especificação como contrato vigente ou identifique-a como registro histórico da funcionalidade. Deixar uma especificação antiga com aparência de referência oficial prepara a próxima rodada de confusão.

O benefício vem de resolver permissões e paginação antes que suas premissas se espalhem pela implementação. Assim, especificação, testes e código preservam a mesma decisão após o merge.

Quanto custa e quando o esforço compensa?

O custo do método é o tempo de revisão e manutenção, mais o trabalho do agente para redigir e implementar. O Spec Kit é de código aberto, mas o agente de programação conectado a ele continua sujeito às próprias condições de uso. Markdown puro dispensa uma assinatura separada de ferramenta de especificação; isso não torna gratuito o uso do modelo.

Os preços comerciais padrão do Kiro incluem Free por US$0 por mês com 50 créditos e Pro por US$20 por usuário por mês com 1,000 créditos, antes dos impostos aplicáveis. Assim, quatro assinaturas Pro custam 4 × US$20 = US$80 por mês, sem créditos adicionais nem impostos. Essa é a conta das licenças, não uma previsão de quantas funcionalidades você conseguirá entregar. Página de preços do próprio Kiro.

Créditos adicionais pagos custam US$0.04 cada. O Kiro informa que o refinamento de especificações, a execução de tarefas e a execução de hooks do agente consomem créditos, e que uma tarefa complexa de especificação pode consumir mais de um crédito. Não há como converter “créditos” em “funcionalidades concluídas” de forma defensável sem observar a carga real de trabalho. Definições de créditos do Kiro.

O critério econômico é simples: o custo adicional de especificar, revisar e manter a funcionalidade precisa ser menor que o retrabalho evitado. Acompanhe esses custos no seu processo. Um método que acrescenta documentos, mas deixa as mesmas decisões para a revisão do código, ainda não justificou o esforço extra.

Onde está o exagero e quando o método é demais?

A promessa exagerada é que um documento suficientemente detalhado torna o agente confiavelmente correto. Não torna. Uma especificação pode estar errada, a implementação pode ignorá-la e os testes podem repetir suas premissas equivocadas.

A distinção útil é entre intenção declarada e comportamento garantido por controles. Um requisito diz que membros não podem exportar; uma verificação no servidor e seus testes ajudam a fazer essa regra valer. Um checklist de requisitos avalia a descrição. Ele não executa a aplicação. Tratar as duas coisas como equivalentes cria uma falsa sensação de segurança.

Outro problema é a divergência entre documentos e código. Se um desenvolvedor mudar o comportamento das permissões, mas editar só o código, o próximo agente pode “corrigir” a aplicação para voltar à especificação desatualizada. Exija que mudanças de comportamento atualizem o acordo correspondente ou arquive esse acordo explicitamente. Mais contexto permanente só ajuda quando ele continua correto.

Comece agora se seu agente erra repetidamente permissões, casos de borda, integrações ou critérios de aceitação. Use o fluxo em uma funcionalidade cuja ambiguidade envolva vários componentes ou pessoas na revisão.

Adie a especificação formal se você ainda está descobrindo se alguém quer a funcionalidade. Primeiro, construa um protótipo descartável ou investigue o que ainda não sabe. Uma especificação bem-acabada para uma ideia não validada pode fazer o investimento errado parecer uma decisão já resolvida.

Mantenha as correções pequenas quando a mudança pretendida for óbvia e localizada: um erro de digitação, um ajuste que siga o estilo existente ou um bug pontual com teste de regressão claro. Declare o comportamento desejado e verifique-o. Um ciclo completo de constituição, plano e tarefas pode exigir mais atenção do que a mudança merece.

O critério de decisão não é a quantidade de linhas de código. É o número de premissas com consequências relevantes que, sem esse processo, o agente teria de assumir.

Spec driven development: como começar na primeira semana

Escolha uma funcionalidade pequena que já esteja no backlog. Peça ao responsável que aprove uma especificação de comportamento de uma página, incluindo o que fica de fora e os casos de falha. Use seu agente atual em modo de planejamento, ou o fluxo correspondente do Spec Kit ou do Kiro, para propor um plano baseado no repositório.

Revise as perguntas antes da implementação. Peça uma lista de tarefas vinculada aos requisitos. No pull request, confira as evidências contra o mesmo acordo e registre as decisões que mudaram. Dê ao processo apenas o peso que a ambiguidade justificar.

Assine a newsletter para conhecer formas práticas de desenvolver e operar com IA.