Specs no Kiro: como aplicar spec-driven development do requisito à tarefa revisada

Spec-driven development é a prática de escrever e revisar uma especificação versionada (requisitos, desenho e tarefas) antes do código e de usá-la como o contrato do incremento que o agente de IA vai implementar. No Kiro, a IA agêntica da AWS para desenvolvimento de software, esse contrato vive em três arquivos Markdown dentro do repositório: requirements.md (ou bugfix.md), design.md e tasks.md. A revisão humana acontece em cada um deles, e o código começa quando o time aprova o que vai ser construído.

Verificado contra a documentação de specs e de hooks do Kiro na atualização de 15/10/2026. A disponibilidade por superfície (IDE, CLI e web) muda entre versões: confira na versão instalada.

O ganho de método está na ordem das decisões. O time discute comportamento e arquitetura num documento que cabe numa revisão de pull request, e o agente executa tarefas pequenas, cada uma rastreável até o requisito que a originou. Para a visão geral do produto e de como adotá-lo no time, o ponto de partida é o guia do Kiro; aqui o foco é a spec, do primeiro critério de aceitação à tarefa revisada.

O que é spec-driven development?

Spec-driven development (SDD), ou desenvolvimento orientado a especificação, é a abordagem em que a especificação escrita é o artefato principal do trabalho. Ela descreve o comportamento esperado, as restrições e o plano de implementação; o código é derivado dela e verificado contra ela.

A ideia vem da engenharia de requisitos. O que muda com agentes de IA é quem implementa: quando o agente escreve o código, a especificação passa a ser o ponto de controle do time sobre o que entra no repositório.

Na conversa por prompts soltos, o requisito fica espalhado pelo histórico do chat, cada turno reinterpreta o anterior e a decisão de arquitetura acontece de forma implícita, dentro do código gerado. Com a spec, requisito, desenho e plano ficam em arquivos versionados, legíveis por quem não participou da conversa e reaproveitáveis na próxima sessão do agente.

A spec compensa quando a mudança tem:

• Regra de negócio: cálculo, elegibilidade, preço, rateio. Erro aqui passa em teste superficial e aparece no fechamento.
• Integração: contrato com outro sistema, tratamento de erro, reprocessamento e idempotência.
• Dado pessoal ou sensível: base legal, minimização, retenção e o que nunca pode ir para log, exigências da LGPD que precisam estar escritas antes do código.
• Caminho crítico: correção onde uma regressão custa caro ou já aconteceu antes.

Para descoberta, protótipo descartável ou ajuste trivial, um spike curto resolve. O Kiro oferece o chat para isso e também o Plan mode, um planejador somente leitura que explora o código e produz um plano no contexto da conversa, sem gerar os documentos formais. Quando o protótipo responder à dúvida, a instrução "Generate spec" no chat inicia uma sessão de spec com o contexto acumulado, conforme as boas práticas de specs.

O trade-off é explícito. Escrever e revisar a spec consome tempo de pessoa sênior antes de qualquer linha de código. Pular essa etapa transfere o custo para o retrabalho, que aparece depois, na revisão do PR, em bug de produção ou numa decisão de arquitetura tomada pelo agente sem que ninguém perceba. Uma regra prática: se a mudança tem um critério de aceitação que alguém vai cobrar, ela merece spec.

Os três arquivos de uma spec no Kiro

Cada spec fica numa pasta própria em .kiro/specs/, dentro do repositório e ao lado do código que descreve, como mostram as boas práticas de specs e as páginas de Quick Spec e de Plan mode. A página de specs define o conteúdo de cada arquivo; cada item abaixo traz também o que a revisão precisa encontrar nele.

• requirements.md: user stories e critérios de aceitação. Revisável quando cada critério tem gatilho, resposta observável e existe pelo menos um critério negativo para cada entrada externa.
• bugfix.md (no lugar do anterior, em Bugfix Specs): comportamento atual, comportamento esperado e comportamento que não pode mudar, segundo a documentação de Bugfix Specs. Revisável quando a terceira seção lista de fato o que precisa continuar funcionando.
• design.md: arquitetura técnica, diagramas de sequência, fluxo de dados, tratamento de erro e estratégia de teste. Revisável quando cada decisão cita de onde veio (ADR, steering, requisito) e os contratos e erros estão escritos.
• tasks.md: plano de implementação em tarefas discretas e rastreáveis, com dependências e a marcação de tarefas opcionais ou obrigatórias. Revisável quando cada tarefa cabe num PR, tem teste e aponta os requisitos que atende.

O exemplo abaixo, usado no restante do texto, é uma funcionalidade de FinOps: ratear a fatura mensal de inferência de IA entre centros de custo para showback, isto é, mostrar a cada time o próprio custo sem cobrá-lo internamente. Ele tem regra de cálculo, idempotência e restrição de LGPD, o perfil que justifica uma spec.

# Requisitos: rateio do custo de IA por centro de custo

## Requisito 1: rateio proporcional

**User story:** Como analista de FinOps, quero ratear a fatura mensal de
inferência entre centros de custo pelo peso de uso, para que cada time
veja o próprio custo (showback).

### Critérios de aceitação
1. WHEN o fechamento mensal é disparado com o total da fatura em centavos
   e a lista de centros com peso, THE SYSTEM SHALL atribuir a cada centro
   um valor inteiro em centavos proporcional ao seu peso.
2. THE SYSTEM SHALL garantir que a soma dos valores atribuídos seja igual
   ao total da fatura.
3. WHEN a divisão deixar centavos residuais, THE SYSTEM SHALL distribuí-los
   pelo método do maior resto, com empate resolvido pela ordem alfabética
   do identificador do centro.
4. IF a lista de centros estiver vazia ou algum peso for menor ou igual
   a zero, THEN THE SYSTEM SHALL rejeitar o fechamento com erro de
   validação e não gravar nenhum valor.
5. WHEN o fechamento do mesmo mês for executado de novo com a mesma
   entrada, THE SYSTEM SHALL produzir o mesmo resultado sem duplicar
   registros.
6. THE SYSTEM SHALL registrar em log apenas identificadores de centro e
   valores, sem dado pessoal.

Nota de precisão sobre a notação. A página geral de specs fala em critérios escritos em notação estruturada; a página de Feature Specs nomeia essa notação: EARS (Easy Approach to Requirements Syntax), no padrão WHEN [condição ou evento] THE SYSTEM SHALL [comportamento esperado]. A EARS foi criada por Alistair Mavin e colegas na Rolls-Royce e publicada pela primeira vez em 2009. Além do padrão orientado a evento (When), ela define o ubíquo (sem palavra-chave, como o critério 2), o orientado a estado (While), o de funcionalidade opcional (Where) e o de comportamento indesejado (If/Then, como o critério 4). O exemplo mantém as palavras-chave em inglês, como na documentação, e o conteúdo em português.

O mesmo formato aparece no baseline de segurança DevSecOps para o Kiro publicado no blog da AWS Brasil: um hook disparado na criação de um requirements.md em .kiro/specs/ garante uma seção de requisitos de segurança escrita em EARS, cobrindo validação de entrada por allowlist, autenticação antes de autorização, segredos em cofre, criptografia em trânsito e em repouso, tratamento de erro sem vazamento de informação, log e auditoria e limite de taxa.

O design.md da mesma spec registra as decisões e de onde cada uma vem:

## Decisões
- Valores monetários em centavos, tipo inteiro (steering: tech.md).
  Ponto flutuante fica fora do cálculo.
- Centavos residuais pelo método do maior resto (requisito 1.3).
- Persistência na tabela DynamoDB existente, chave MES#<aaaa-mm> e
  CENTRO#<id>, com gravação condicional para idempotência
  (requisito 1.5). Decisão de persistência no ADR vigente em docs/adr/.

## Tratamento de erro
- Entrada inválida: erro de validação, nenhuma gravação (requisito 1.4).
- Falha parcial de gravação: reexecução segura pela gravação condicional.

## Estratégia de teste
- Função de rateio pura, coberta por testes baseados em propriedades.
- Handler coberto por teste de integração com DynamoDB Local.

Feature, Bugfix, Requirements-First, Design-First ou Quick Spec?

O Kiro tem dois tipos de spec: Feature Specs, para funcionalidade nova, e Bugfix Specs, para defeito com análise de causa raiz. A Feature Spec tem dois fluxos, Requirements-First (requisitos, depois desenho, depois tarefas) e Design-First (desenho, depois requisitos, depois tarefas). O Quick Spec gera os três artefatos de uma vez, sem portões de aprovação entre as fases. Um detalhe que pesa na escolha: segundo as boas práticas, o fluxo é escolhido na criação e não pode ser trocado depois; mudar de abordagem exige uma spec nova.

Os critérios de cada linha seguem a documentação de Feature Specs, de Bugfix Specs e de Quick Spec. Para correção simples, como um erro de digitação, a própria documentação considera o ajuste pelo chat suficiente. E bug e funcionalidade nova ficam em specs separadas: a conversão de Bugfix Spec em Feature Spec não é suportada.

Como revisar uma spec antes de liberar o código

A aprovação de cada fase é o ponto em que o time assume a responsabilidade pelo que o agente vai construir. Um checklist que cobre os defeitos mais comuns:

• Requisito testável: cada critério tem gatilho e resposta observável. Toda entrada externa tem pelo menos um critério negativo no padrão IF/THEN.
• Termos vagos eliminados: "rápido", "seguro" e "amigável" viram critério com valor e origem, ou saem da spec.
• Requisitos não funcionais escritos: latência e vazão com a fonte do número (SLO acordado, contrato); LGPD (que dado pessoal entra, base legal, retenção, o que nunca vai para log); custo de IA quando a funcionalidade chama modelo, com limite por solicitação e por período (detalhado no post de FinOps de IA generativa); observabilidade (quais logs, métricas e traces provam que o requisito é cumprido).
• Desenho ancorado: o design.md cita os ADRs vigentes e respeita o steering. Decisão de arquitetura nova vira ADR antes de virar código.
• Tarefas pequenas: cada uma cabe num PR revisável, inclui o teste e indica os requisitos que atende.
• Rastreio completo: todo requisito tem pelo menos uma tarefa e toda tarefa aponta pelo menos um requisito.
• Dependências reais: o grafo do tasks.md reflete o que de fato depende do quê (detalhado na próxima seção).

Os pilares do AWS Well-Architected Framework funcionam como roteiro para não esquecer requisito não funcional; o post sobre a Well-Architected Review descreve os seis pilares.

Antes do desenho, vale rodar o Analyze Requirements. Ele examina o conjunto de requisitos em busca de requisitos impossíveis de cumprir juntos, termos vagos, conflito entre requisito funcional e não funcional, conceitos não definidos e casos de borda ausentes (modos de falha, limites, acesso concorrente). A documentação o recomenda para funcionalidades complexas, domínios sensíveis como serviços financeiros, saúde e conformidade, e para sessões de Quick Spec, e avisa que a análise leva minutos. Ela complementa a revisão humana; a aprovação continua com o time.

Por fim, a spec passa por pull request como qualquer código. As boas práticas de specs afirmam que specs foram desenhadas para ficar sob controle de versão e ser compartilhadas com o time. Um fluxo consistente: branch da funcionalidade, PR com os três arquivos, revisor de negócio no requirements.md, revisor técnico no design.md e no tasks.md, e execução das tarefas só depois da aprovação, no mesmo branch.

Execução das tarefas: waves (ondas) e paralelismo

Segundo a documentação de specs, o Kiro monta um grafo de dependências a partir do tasks.md e agrupa as tarefas independentes em waves (ondas). As waves rodam em sequência; as tarefas dentro de uma wave rodam em paralelo; a primeira wave reúne todas as tarefas sem dependência. O comando Run all Tasks executa as tarefas obrigatórias ainda incompletas, e as que têm dependência esperam a vez.

# Plano de implementação: rateio do custo de IA

- [ ] 1. Função pura ratear(totalCentavos, centros) em src/rateio/ratear.ts
  - Requisitos: 1.1, 1.2, 1.3
- [ ] 2. Validação da entrada do fechamento em src/rateio/validar.ts
  - Requisitos: 1.4
- [ ] 3. Repositório com gravação condicional em src/rateio/repositorio.ts
  - Requisitos: 1.5
- [ ] 4. Handler do fechamento mensal com log estruturado
  - Depende de: 1, 2, 3
  - Requisitos: 1.4, 1.5, 1.6
- [ ] 5. Testes de integração do handler com DynamoDB Local
  - Depende de: 4
  - Requisitos: 1.1 a 1.6

O Kiro gera o tasks.md no formato dele; o trecho mostra o conteúdo que a revisão precisa encontrar. Nesse plano, as tarefas 1, 2 e 3 formam a primeira wave, a 4 forma a segunda e a 5, a terceira. Três implicações práticas:

• Declare a dependência real. Se a tarefa 4 usa o contrato criado pela 1, isso precisa estar escrito. Dependência omitida coloca duas tarefas em paralelo sobre uma premissa falsa.
• Evite dependência defensiva. Encadear tudo serializa o plano e desperdiça o paralelismo que a separação em módulos permitiu.
• Uma tarefa por arquivo em cada wave. Duas tarefas paralelas editando o mesmo arquivo geram conflito e uma revisão difícil de ler. Separar por módulo, como no exemplo, evita o problema.

Os hooks Pre Task Execution e Post Task Execution disparam antes e depois de cada tarefa de spec, na IDE e na CLI V3, segundo a página de tipos de hook, que cita como caso de uso rodar testes ao fim de uma tarefa. O identificador no JSON é PostTaskExec, conforme a referência de triggers:

{
  "version": "v1",
  "hooks": [
    {
      "name": "testes-apos-tarefa",
      "trigger": "PostTaskExec",
      "action": {
        "type": "command",
        "command": "npm test --silent"
      }
    }
  ]
}

Ações do tipo command rodam na raiz do projeto e têm tempo limite padrão de 60 segundos, segundo a referência de campos da documentação de hooks; suíte mais longa pede o ajuste do campo timeout do hook, em segundos (o valor 0 desativa o limite, o que tira a proteção contra um teste travado). O desenho completo de hooks, com verificação antes de cada ferramenta e bloqueios, está no post sobre hooks no Kiro.

Testes baseados em propriedades

Um teste baseado em propriedade declara uma regra geral que precisa valer para qualquer entrada, em vez de listar exemplos um a um. O framework gera muitas entradas e, quando uma falha, reduz o caso ao menor contraexemplo que ainda reproduz a falha (shrinking).

Segundo a página de corretude, o Kiro extrai propriedades dos requisitos em EARS, identifica as que podem ser testadas e, diante de uma falha, apresenta o cenário para revisão, com a opção de corrigir a implementação, o teste ou a própria spec. Esses testes são opcionais por padrão, e a tabela da documentação de specs os lista como disponíveis só na IDE. Nas Bugfix Specs, eles confirmam que o bug se reproduz, que foi corrigido e que nada regrediu.

Para a regra de rateio, as propriedades saem direto dos critérios:

• Conservação (critérios 1.1 e 1.2): para qualquer total e qualquer lista válida de centros, a soma dos valores é igual ao total.
• Limites: todo valor é inteiro, maior ou igual a zero e menor ou igual ao total; total zero gera zero para todos.
• Ordem (critério 1.3): permutar a lista de centros não altera o valor de nenhum centro, porque o desempate usa o identificador e não a posição.
• Idempotência (critério 1.5): a mesma entrada produz sempre o mesmo resultado.

import fc from "fast-check";
import { ratear } from "./ratear";

const total = fc.integer({ min: 0, max: 100_000_000 }); // centavos
const centros = fc.uniqueArray(
  fc.record({
    id: fc.string({ minLength: 1, maxLength: 8 }),
    peso: fc.integer({ min: 1, max: 1_000 }),
  }),
  { minLength: 1, maxLength: 50, selector: (c) => c.id }
);

test("conservação: a soma das parcelas é o total", () => {
  fc.assert(fc.property(total, centros, (t, cs) => {
    const r = ratear(t, cs);
    return [...r.values()].reduce((a, b) => a + b, 0) === t;
  }));
});

test("limites: parcela inteira, entre zero e o total", () => {
  fc.assert(fc.property(total, centros, (t, cs) =>
    [...ratear(t, cs).values()].every(
      (v) => Number.isInteger(v) && v >= 0 && v <= t)));
});

test("ordem: permutar os centros não muda o valor de cada um", () => {
  fc.assert(fc.property(total, centros, (t, cs) => {
    const a = ratear(t, cs);
    const b = ratear(t, [...cs].reverse());
    return cs.every((c) => a.get(c.id) === b.get(c.id));
  }));
});

O exemplo usa a biblioteca fast-check, de TypeScript, apenas para ilustrar; a página de corretude do Kiro não nomeia framework. O ponto de método é a ligação: cada propriedade cita o critério que verifica, e o contraexemplo mínimo devolve a discussão para a spec quando a falha está no requisito e não no código.

Armadilhas e como evitar

• Spec grande demais. Uma spec para o sistema inteiro produz um tasks.md que ninguém revisa. A documentação recomenda uma spec por funcionalidade (autenticação, catálogo, checkout) e permite quantas specs forem necessárias no mesmo repositório. Divida por incremento entregável: se a revisão do conjunto não cabe numa sessão, são duas specs.
• Aprovar sem ler. Seguir para a próxima fase custa um clique. Defina um revisor nomeado por arquivo e use o checklist da seção anterior no PR.
• Desenho que contradiz o steering. O steering entra no contexto, mas o desenho ainda pode propor uma dependência nova ou outro padrão. Na revisão, ou o steering é atualizado por decisão consciente, ou o desenho volta. O post sobre steering no Kiro mostra como registrar essas convenções.
• Spec desatualizada. O escopo muda no chat e a spec fica para trás. No fluxo Requirements-First, edite os requisitos, atualize o desenho e use Sync Files, que cria tarefas para os requisitos novos e marca as já concluídas; no Design-First, peça ao Kiro para validar e regenerar os requisitos, conforme as boas práticas.
• Números e limites inventados. O agente preenche lacunas com valores plausíveis, como uma latência-alvo ou um limite de serviço. Exija a fonte de cada número: SLO acordado, contrato ou a documentação de Service Quotas para limites da AWS. Número sem origem sai da spec.

Spec, steering e ADR: quem guarda o quê

Os três artefatos convivem no repositório e cada um responde a uma pergunta diferente.

O fluxo entre eles é direto. Uma decisão com trade-off que surge no design.md vira ADR. Uma convenção que se repete em várias specs vira steering. E o steering pode apontar para o índice de ADRs com a referência de arquivo #[[file:caminho]], descrita na documentação de steering, para que todo desenho comece pelas decisões vigentes:

---
inclusion: always
---

# Decisões de arquitetura

Antes de propor um desenho, leia os ADRs vigentes:
#[[file:docs/adr/README.md]]

- Desenho que contradiz um ADR vigente exige um ADR novo que o substitua.
- Valores monetários sempre em centavos, tipo inteiro.
- Nenhum dado pessoal em log.

Esse encadeamento, com specs revisáveis no código e agentes em produção em seguida, aparece no exemplo de escopo do catálogo para software house com Kiro e Amazon Bedrock AgentCore. Para o uso de IA generativa em outras etapas do ciclo de desenvolvimento, o post sobre IA generativa no SDLC complementa este.

A primeira spec bem revisada ensina mais ao time do que qualquer documentação: mostra onde o requisito estava vago, onde o desenho dependia de uma decisão não registrada e onde o plano escondia uma dependência. É esse exercício que a oficina Kiro na Prática conduz.

Perguntas frequentes

O que é spec-driven development?

É a prática de escrever e revisar uma especificação versionada (requisitos, desenho e tarefas) antes do código e usá-la como o contrato do incremento. Quando um agente de IA implementa, a especificação vira o ponto de controle do time: o código é derivado dela e verificado contra ela.

Onde o Kiro guarda as specs?

Na pasta .kiro/specs/ do repositório, ao lado do código que descrevem, com os arquivos requirements.md (ou bugfix.md), design.md e tasks.md. As boas práticas de specs da documentação do Kiro afirmam que specs foram desenhadas para ficar sob controle de versão, o que permite revisá-las por pull request como qualquer código.

O Kiro usa a notação EARS nos requisitos?

Sim. A página de Feature Specs do Kiro descreve os critérios de aceitação no formato EARS (Easy Approach to Requirements Syntax), no padrão WHEN [condição ou evento] THE SYSTEM SHALL [comportamento esperado]. A notação EARS foi criada por Alistair Mavin e colegas na Rolls-Royce e publicada pela primeira vez em 2009.

Quando usar Quick Spec no Kiro?

Para funcionalidades bem conhecidas, em que o time confia no resultado gerado e não precisa iterar requisitos e desenho. O Quick Spec gera os três arquivos de uma vez, sem portões de aprovação entre as fases. Para trabalho sensível a conformidade ou de alto impacto, a documentação recomenda a Feature Spec padrão.

Os testes baseados em propriedades funcionam na Kiro CLI?

Segundo a tabela de disponibilidade da documentação de specs, a verificação de corretude com testes baseados em propriedades está disponível só na IDE. Feature Specs, Bugfix Specs, Quick Spec e execução paralela de tarefas aparecem disponíveis na IDE, na CLI e na web.

A spec substitui o ADR e o steering?

Cada um guarda uma coisa. O steering guarda as convenções perenes do repositório, a spec guarda o escopo de um incremento e o ADR guarda uma decisão arquitetural com contexto, opções e trade-off. A spec referencia os dois: o design.md cita os ADRs vigentes e respeita o steering.

Sobre o autor

Rodrigo Araújo

Arquiteto de Soluções, IA e Cloud | RFX Tecnologia

Arquiteto de Soluções, IA e Cloud na RFX Tecnologia, lidera projetos de migração, FinOps e IA aplicada na nuvem para empresas do Nordeste e de todo o Brasil. É também o idealizador da Jornada de Inovação AWS em João Pessoa, encontro que aproxima donos de negócio da região das aplicações reais de cloud e inteligência artificial.