O que é o Kiro e o spec-driven development na prática

TL;DR

• Kiro é o IDE agêntico da AWS (lançado em 14/jul/2025), construído sobre Code OSS — a mesma base do VS Code, com atalhos, temas e plugins Open VSX. Vem em quatro sabores com a mesma assinatura: IDE, CLI, web e via ACP em outros editores.
• O diferencial não é o autocomplete: é o spec-driven development — estruturar a intenção em arquivos versionados (.kiro/specs/), não só na janela de chat.
• Toda spec gera três arquivos: requirements.md (com critérios EARS), design.md (arquitetura + mermaid) e tasks.md (tarefas rastreáveis).
• “Run all Tasks” monta um grafo de dependências e executa tarefas independentes em waves paralelas.
• Specs brilham em features complexas e bugs caros; Vibe brilha em exploração rápida. Saber quando usar cada um é metade do jogo.

A dor do “prompt-prompt-prompt até produção”

Você conhece o roteiro. Abre o assistente, descreve a feature, recebe um bloco de código quase certo. Ajusta o prompt. Recebe outro bloco, agora com um bug diferente. Pede pra corrigir. Ele corrige e quebra outra coisa. Três horas depois você tem 400 linhas que “funcionam”, ninguém sabe exatamente por quê, e a única documentação da decisão de arquitetura é um histórico de chat que vai sumir quando você fechar a aba.

Isso é vibe coding levado longe demais. Funciona lindamente para um protótipo de fim de semana. Mas quando a feature é complexa, quando uma regressão custa caro, ou quando outra pessoa vai manter o código, a conversa efêmera vira dívida técnica silenciosa. A intenção — por que o sistema faz o que faz — nunca foi escrita em lugar nenhum durável.

O Kiro parte de uma premissa diferente: a intenção precisa morar no repositório, ao lado do código. Não numa thread de chat, não na cabeça de quem escreveu o prompt. É essa mudança de lugar que o time do Kiro resume como “ir além do vibe coding”.

A conversa é volátil. O repositório é durável. O spec-driven development move a intenção do primeiro para o segundo.

O que é o Kiro

Kiro é um IDE agêntico da AWS. “Agêntico” aqui significa que ele não só completa linhas — ele lê o codebase, planeja, escreve arquivos, roda comandos e itera, com você no comando das aprovações.

Alguns fatos que definem o produto:

• Base Code OSS. Kiro é construído sobre Code OSS, a fundação open source do VS Code. Na prática, seus atalhos, temas e boa parte da sua muscle memory continuam valendo. As extensões vêm do Open VSX.
• Muitas linguagens. Python, Java, JavaScript, TypeScript, C#, Go, Rust, PHP, Ruby, Kotlin, C, C++, shell, SQL, Scala, além de JSON, YAML e HCL. Não é uma ferramenta de nicho para uma stack só.
• Quatro interfaces, a mesma assinatura. Kiro IDE, Kiro CLI, Kiro na web e via ACP (Agent Client Protocol) dentro de JetBrains, Eclipse, Zed e outros. Os créditos consumidos independem da interface — você não paga a mais por usar o CLI no CI e o IDE na sua máquina.
• Agente Auto. O modelo padrão é o agente Auto, que mistura modelos de fronteira com modelos especializados, mais cache e roteamento por intenção. Também dá para escolher explicitamente Sonnet 4.5/4.6, Haiku 4.5 ou Opus 4.5 a 4.8 (a disponibilidade varia por região). A ideia do Auto é você não precisar microgerenciar qual modelo resolve qual tarefa.

Tudo isso é infraestrutura de conforto. O que muda o jogo de verdade é a camada de specs.

Spec-driven development: intenção estruturada no repositório

Uma spec no Kiro vive em uma pasta previsível:

.kiro/
└── specs/
    └── sistema-de-avaliacoes/
        ├── requirements.md
        ├── design.md
        └── tasks.md

Esses três arquivos representam três fases de um fluxo deliberado:

Requirements → Design → Tasks.

Cada fase tem um propósito distinto e produz um artefato durável:

1. requirements.md — user stories mais critérios de aceitação escritos em notação EARS. É o “o quê” e o “por quê”.
2. design.md — arquitetura do sistema, diagramas de sequência, fluxo de dados, tratamento de erros e estratégia de testes. É o “como”.
3. tasks.md — tarefas discretas e rastreáveis, que você roda uma a uma ou todas de uma vez. É o “fazer”.

O Kiro oferece variantes desse fluxo. Feature Specs vêm em sabores Requirements-First e Design-First, dependendo de por onde você prefere começar. O Quick Plan gera os três artefatos de uma vez, sem os approval gates entre fases — útil quando você já sabe o que quer e só precisa da estrutura. E há Bugfix Specs, que geram um bugfix.md documentando o comportamento current, expected e unchanged — ótimo justamente para os bugs onde uma regressão sai cara.

O ponto crucial: as specs ficam sincronizadas com o código conforme ele evolui. Não é documentação que apodrece. É um artefato vivo que caminha junto.

Mão na massa: um sistema de avaliações de ponta a ponta

Vamos construir uma feature real — um sistema de avaliações de produtos — passando pelas três fases. Isso torna concreto o que cada arquivo carrega.

Fase 1 — requirements.md com EARS

Aqui está o coração da primeira fase. Repare que cada critério de aceitação é uma frase testável, não uma vaga “o sistema deve ser seguro”:

# Requisitos — Sistema de Avaliações de Produtos

## User Story 1: Criar avaliação
Como cliente autenticado, quero avaliar um produto que comprei,
para ajudar outros compradores.

### Critérios de aceitação (EARS)
- WHEN um cliente autenticado envia uma avaliação com nota de 1 a 5,
  THE SYSTEM SHALL persistir a avaliação e associá-la ao produto e ao usuário.
- IF o usuário não comprou o produto,
  THEN THE SYSTEM SHALL rejeitar a avaliação com HTTP 403.
- WHILE o texto da avaliação exceder 2.000 caracteres,
  THE SYSTEM SHALL bloquear o envio e exibir mensagem de validação.
- WHERE a avaliação contém linguagem sinalizada pelo filtro,
  THE SYSTEM SHALL marcá-la como "pendente de moderação".

Entendendo EARS

EARS é a sigla de Easy Approach to Requirements Syntax. É uma gramática mínima para escrever requisitos que não deixam margem para interpretação. Em vez de “o sistema deve validar avaliações”, você usa quatro palavras-gatilho que definem quando uma regra vale:

Palavra-chave	Significa	Exemplo do nosso sistema
WHEN	um evento/gatilho ocorre	WHEN um cliente envia uma nota de 1 a 5 → persistir
IF / THEN	uma condição (muitas vezes um caso de erro)	IF o usuário não comprou o produto → 403
WHILE	um estado contínuo é verdadeiro	WHILE o texto excede 2.000 caracteres → bloquear
WHERE	uma característica/feature está presente	WHERE há linguagem sinalizada → pendente de moderação

Cada frase segue o padrão <gatilho> ... THE SYSTEM SHALL <comportamento>. Três benefícios concretos:

• Testabilidade. Cada critério vira quase que diretamente um caso de teste. O IF o usuário não comprou → 403 é um teste de integração óbvio.
• Ausência de ambiguidade. “SHALL” é uma obrigação, não uma sugestão. Não há espaço para “deveria talvez”.
• Cobertura de casos. O ato de escrever em EARS força você a pensar nos gatilhos negativos (o 403, o limite de caracteres) que você esqueceria num prompt corrido.

EARS não é burocracia. É a diferença entre “faça algo tipo validação” e uma especificação que o agente — e o próximo humano — conseguem executar sem adivinhar.

Fase 2 — design.md com mermaid

Com o “o quê” acordado, a fase de design responde ao “como”. O design.md costuma trazer um diagrama de sequência para deixar o fluxo explícito:

sequenceDiagram
    participant U as Cliente
    participant API as Review API
    participant DB as PostgreSQL
    U->>API: POST /products/{id}/reviews
    API->>DB: verifica compra (orders)
    DB-->>API: compra confirmada
    API->>DB: INSERT review (status=published)
    API-->>U: 201 Created

E, junto, o modelo de dados que sustenta os critérios. Note como o campo rating (1..5), o limite de body (<= 2000 chars) e o status como enum são reflexos diretos dos critérios EARS da fase anterior:

## Modelo de dados
| Campo       | Tipo | Nota                              |
|-------------|------|-----------------------------------|
| id          | uuid | PK                                |
| product_id  | uuid | FK products                       |
| user_id     | uuid | FK users                          |
| rating      | int  | 1..5                              |
| body        | text | <= 2000 chars                     |
| status      | enum | published \| pending \| rejected  |

flowchart LR
    I["💬 Intenção"] --> R["📋 Requirements<br/>requirements.md · EARS"]
    R --> D["🏗️ Design<br/>design.md · diagramas"]
    D --> T["✅ Tasks<br/>tasks.md · plano"]
    T --> C["⚙️ Código rastreável"]

Repare na rastreabilidade: o WHERE ... pendente de moderação do requirements vira o estado pending no enum de status, que aparece no design, que vira uma task. Cada decisão tem uma linhagem.

Fase 3 — tasks.md

Por fim, o plano de implementação. Cada tarefa referencia o requisito que a originou (Req 1), fechando o ciclo de rastreabilidade:

# Plano de implementação

- [ ] 1. Criar migration da tabela reviews (Req 1)
- [ ] 2. Implementar ReviewRepository com verificação de compra (Req 1)
  - [ ] 2.1 Testes unitários do repositório
- [ ] 3. Endpoint POST /products/{id}/reviews (Req 1)
  - [ ] 3.1 Teste de integração (403 sem compra)
- [ ] 4. Filtro de moderação (Req 1 - WHERE)

Você pode executar essas tarefas uma a uma — revisando cada diff — ou mandar rodar todas. E é aqui que entra o detalhe mais interessante da execução.

Waves: paralelismo por grafo de dependências

Quando você escolhe “Run all Tasks”, o Kiro não sai executando de cima para baixo cegamente. Ele constrói um grafo de dependências entre as tarefas e agrupa as que são independentes em waves (ondas).

A Wave 1 contém todas as tarefas que não dependem de nenhuma outra — elas podem rodar em paralelo. Conforme uma wave termina, a próxima destrava as tarefas que dependiam dela.

No nosso exemplo, a leitura das dependências poderia ser:

Wave 1 (sem dependências, rodam juntas):
  • Task 1  — migration da tabela reviews
  • Task 4  — filtro de moderação (lógica isolada)

Wave 2 (dependem da tabela existir):
  • Task 2   — ReviewRepository
    └ 2.1    — testes unitários do repositório

Wave 3 (depende do repositório):
  • Task 3   — endpoint POST /products/{id}/reviews
    └ 3.1    — teste de integração (403 sem compra)

O ganho é duplo: velocidade, porque tarefas independentes não esperam umas às outras à toa; e segurança, porque o grafo impede que o endpoint (Task 3) seja implementado antes do repositório (Task 2) que ele consome. A ordem correta emerge das dependências reais, não de um palpite.

Specs vs Vibe: quando usar cada um

Specs custam mais esforço inicial. Isso é real e é honesto admitir. A pergunta certa não é “specs são melhores?”, e sim “esse trabalho merece uma spec?”.

Situação	Use Specs	Use Vibe
Feature complexa, com múltiplas regras de negócio	✅
Bug onde uma regressão sai cara	✅
Código que o time vai manter / precisa de documentação	✅
Requisitos e design que ainda vão iterar	✅
Exploração rápida de uma ideia		✅
Protótipo sem meta clara / descartável		✅

A regra prática que eu sigo:

• Vibe para descobrir o que você quer construir. É o modo de exploração — rápido, barato, sem cerimônia.
• Specs para construir o que você já sabe que precisa e que vai durar. É o modo de engenharia — deliberado, rastreável, sincronizado com o código.

Os dois convivem. Muitas vezes eu começo em vibe para entender o problema e, quando a forma da solução fica clara, promovo aquilo para uma spec antes de escrever a versão que vai para produção.

Armadilhas comuns

• Escrever requisitos vagos e culpar o agente. Se o critério não é testável, o resultado não vai ser. EARS existe justamente para forçar precisão — use as palavras-gatilho.
• Pular o design. É tentador ir de requirements direto pra tasks. Mas o design.md é onde você percebe que faltou uma tabela ou um caso de erro antes de escrever código errado.
• Tratar spec como documento morto. A spec fica sincronizada com o código; deixe-a evoluir junto em vez de escrever uma vez e abandonar.
• Usar spec para tudo. Protótipo descartável não precisa de três fases. Reserve o esforço para o que merece.

Principais aprendizados

• O valor central do Kiro não é gerar código mais rápido — é estruturar a intenção dentro do repositório, onde ela dura e permanece rastreável.
• Uma spec é sempre três arquivos em .kiro/specs/<nome>/: requirements.md, design.md, tasks.md, seguindo o fluxo Requirements → Design → Tasks.
• EARS (WHEN / IF-THEN / WHILE / WHERE … THE SYSTEM SHALL) transforma requisitos vagos em critérios testáveis e sem ambiguidade.
• Waves aceleram a execução com paralelismo seguro, derivado de um grafo de dependências real entre as tarefas.
• Specs para o que dura e é complexo; Vibe para explorar. Escolher errado desperdiça esforço nos dois sentidos.
• Sendo Code OSS por baixo, com Open VSX e quatro interfaces, a curva de adoção é baixa — o que muda é o método, não a ferramenta que você já conhece.

Referências

• Introducing Kiro (blog oficial): https://kiro.dev/blog/introducing-kiro/
• Specs — documentação: https://kiro.dev/docs/specs/
• Feature Specs: https://kiro.dev/docs/specs/feature-specs/
• Quick Plan: https://kiro.dev/docs/specs/quick-plan/
• Modelos (Auto e premium): https://kiro.dev/docs/models/
• Perguntas frequentes: https://kiro.dev/faq/

---

Este artigo foi publicado originalmente no Medium. Preços, nomes de modelos e detalhes de produto refletem o estado do Kiro em meados de 2026 e podem mudar — confirme em kiro.dev antes de tomar decisões. Este é um conteúdo educacional independente, sem vínculo oficial com a AWS.

Tags: kiro, spec-driven-development, aws, ai-coding, software-engineering

Publicado originalmente em prompt.victorbatistax.com. Se você chegou por outra plataforma, esta é a versão canônica.