Sua IA escreve o código. Quem é dono das decisões?

Seus agentes estão tomando decisões de arquitetura. Alguém está registrando isso?

Principais conclusões

• O problema das ferramentas de IA para código não é produzir código. É que, seis meses depois, ninguém sabe por que o código está daquele jeito. O Kiro é a tentativa mais direta de resolver isso.
• Desenvolvimento spec-driven adiciona overhead. A questão não é se é mais lento. É. A questão é se o seu time consegue arcar com a alternativa.
• Os modos de falha são reais: specs superficiais, falsa precisão da notação EARS, ADRs que parecem completos mas não são. O workflow só funciona se as etapas de revisão forem tratadas como etapas de verdade.

As ferramentas de IA para programar ficaram boas em produzir código. Muito boas. Frameworks multiagentes, assistentes agênticos, pipelines autônomos: se o problema é "transformar essa ideia em código funcional", as opções dão conta. Mas, se você desenvolve software em time, provavelmente já bateu na parede que aparece umas duas semanas depois da demo impressionante: o código funciona, ninguém sabe por que ele está daquele jeito e, quando alguém pergunta por que tal abordagem foi adotada, a resposta honesta é "deixei o agente decidir e não tenho total certeza."

Já vi isso acontecer em vários times. O problema não é que o agente tenha feito escolhas ruins. É que praticamente toda ferramenta de IA para código no mercado é otimizada para execução de tarefas, e poucas investem nos artefatos que mantêm o desenvolvimento em time coerente ao longo do tempo.

O Kiro, da Amazon, lançado em preview em julho de 2025, é a tentativa mais direta que vi de resolver essa lacuna. Isso aqui não é uma comparação "Kiro vs. Cursor"; em velocidade pura para tarefas individuais, Cursor, Claude Code e os frameworks multiagentes são imbatíveis. A pergunta de verdade é se o modelo de desenvolvimento spec-driven do Kiro, combinado com um workflow de Architecture Decision Record (ADR) configurável pelo sistema de Steering, oferece aos times algo que essas ferramentas não dão: um registro compartilhado e revisável por humanos de como o software foi projetado e por quê.

O cenário multiagente: poderoso, mas estruturalmente incompleto

A geração atual de frameworks multiagentes (CrewAI, LangGraph, AutoGen, MetaGPT) é madura. Empresas como DocuSign e PwC rodam pipelines multiagentes em produção e em escala. O argumento a favor do Kiro só faz sentido se você aceitar que a alternativa já é boa em produzir código.

Vale olhar o MetaGPT de perto — ele aparece menos em produção do que LangGraph ou CrewAI, mas é o que mais se sobrepõe ao que o Kiro promete. Dê a ele um requisito de uma linha e ele entrega artefatos estruturados: PRDs, documentos de design, especificações de interface, código de implementação. No papel, isso cobre o mesmo terreno do workflow spec-driven do Kiro.

A diferença estrutural não está na qualidade do output. Está em quem vê as decisões e quando.

No MetaGPT, os agentes produzem artefatos e passam para o próximo agente. O output é abrangente, mas o processo é opaco: as decisões tomadas pelo agente Architect não aparecem como registros revisáveis. Não existe uma etapa de aprovação em que seu time leia o documento de design e sinalize uma restrição antes de a implementação começar. Os artefatos são saídas para serem consumidas, não documentos colaborativos para serem revisados.

A mesma lacuna existe nos frameworks multiagentes em geral. Eles são engines de execução excelentes. Não foram projetados para gerar um entendimento compartilhado dentro do time sobre por que o software foi construído de uma certa forma. Isso é uma escolha de design, não uma falha. Esses frameworks otimizam para a conclusão de tarefas. O Kiro otimiza para legibilidade do time ao longo do tempo.

O que o Kiro faz de fato

O Kiro é um fork do VS Code com Claude Sonnet rodando no Amazon Bedrock. O ambiente familiar importa: nenhuma IDE nova para aprender, sem troca de contexto, e plugins, temas e configurações existentes do Open VSX migram sem dor. Por ser uma IDE de propósito geral, o Kiro funciona com várias linguagens e frameworks, embora o workflow spec-driven se demonstre mais naturalmente em desenvolvimento backend e full-stack, onde as decisões de arquitetura pesam mais.

O diferencial está no workflow que ele impõe.

Desenvolvimento spec-driven: artefatos antes da execução

Toda feature no Kiro começa com uma spec, um conjunto de arquivos Markdown estruturados, commitados no repositório antes de qualquer linha de código. O processo de três fases é deliberado:

Fase 1: Requisitos (requirements.md)

A primeira etapa é justamente a que a maioria dos times pula: requisitos escritos, revisados e aprovados antes de existir qualquer código. Você descreve o que quer em linguagem natural. O Kiro não começa a programar. Em vez disso, ele produz um documento formal de requisitos usando a notação EARS (Easy Approach to Requirements Syntax), um formato que força cada requisito a uma forma inequívoca e testável:

WHEN [trigger condition] THE SYSTEM SHALL [observable behavior]

A notação EARS expõe suposições que, de outra forma, ficariam implícitas. Se o Kiro gera um critério de aceitação que você não tinha em mente, você pega aqui — não no code review, não em produção. Os requisitos são revisados e aprovados por uma pessoa antes de qualquer outra coisa acontecer.

Fase 2: Design técnico (design.md)

Esta é a fase em que as discussões de arquitetura de verdade deveriam acontecer — e onde a maioria das ferramentas de IA já começou a escrever código. Com os requisitos aprovados, o Kiro analisa a base de código existente e gera um documento de design: hierarquias de componentes, diagramas de fluxo de dados, schemas de banco, contratos de API, interfaces TypeScript. O design reflete a arquitetura real do seu projeto.

Este é o documento que seu time revisa antes de uma única linha de código de produção ser escrita. Um arquiteto pode contestar um schema. Um engenheiro sênior pode levantar uma preocupação de escala. Um engenheiro em uma feature paralela pode verificar se o novo design cria conflitos de integração com o trabalho dele. Tudo isso acontece em cima de um artefato escrito, dentro de um pull request.

Fase 3: Tarefas de implementação (tasks.md)

Somente neste ponto a implementação começa. O Kiro gera uma lista de tarefas ordenada por dependência e mapeada de volta aos requisitos, com cada tarefa incluindo testes unitários e de integração relevantes e, quando aplicável, estados de loading e considerações de acessibilidade. As tarefas podem ser executadas uma a uma com aprovação humana explícita em cada passo, ou de forma autônoma em modo autopilot. Os diffs de código e o histórico de execução do agente ficam visíveis em cada etapa.

Os arquivos de spec ficam em .kiro/specs/<feature-name>/ dentro do repositório do projeto. Eles são commitados, versionados, revisáveis em pull requests e navegáveis pelo histórico do git. O time inteiro vê desde o momento em que existem.

Essa visibilidade muda como os engenheiros sêniores gastam o tempo. Em vez de serem puxados para a arqueologia de descobrir o que foi decidido e por quê, eles revisam um design escrito, contestam o que precisa ser contestado e aprovam antes de o trabalho começar. O julgamento deles é aplicado onde tem mais alavancagem.

A lacuna que ferramentas multiagentes não preenchem: o registro de decisões

É aqui que a comparação com frameworks multiagentes fica afiada, e onde a escolha da ferramenta tem consequências de longo prazo que você não enxerga numa demo curta.

Os arquivos de spec do Kiro documentam o que o sistema deve fazer e como ele foi projetado para fazer. Isso já é mais do que a maioria dos workflows com IA preserva. Mas o design.md vai dizer que o PostgreSQL foi escolhido e descrever o schema. Não vai dizer que o DynamoDB foi avaliado e rejeitado porque os seus padrões de acesso exigem filtragem por múltiplas colunas, algo que o modelo de query do DynamoDB não suporta sem desnormalização cara e caminhos de escrita duplicados. Não vai dizer que event sourcing foi considerado e descartado porque o time não tem experiência operacional com event stores e o orçamento de latência não comportaria consistência eventual.

Esse contexto — o que foi avaliado, por que foi rejeitado, quais trade-offs foram aceitos — é o que um Architecture Decision Record (ADR) captura. O conceito foi introduzido por Michael Nygard em 2011 e virou um pilar de arquitetura de software sustentável. A organização ADR no GitHub mantém uma boa visão geral do formato e das suas variantes, caso queira se aprofundar.

ADRs são uma prática bem estabelecida. O GOV.UK Digital Service publicou 39 deles durante a migração para a AWS, cobrindo decisões desde a escolha da plataforma de hospedagem até consolidação de banco de dados e arquitetura de DNS. Cada um é um Markdown curto: Status, Contexto, Decisão, Consequências. A coleção é o registro de decisões da migração inteira, versionado junto com a infraestrutura que descreve.

A razão pela qual a maioria dos times não mantém ADRs é fricção. Produzi-los compete com a pressão de entregar, a disciplina se desgasta depois de uma ou duas sprints e as decisões que efetivamente acabam capturadas são as feitas no início, no momento do design — e não as igualmente importantes que surgem no meio da implementação, quando uma restrição se mostra diferente do esperado.

O Kiro elimina essa fricção por dois mecanismos:

Geração automatizada de ADRs via Steering

O sistema Steering do Kiro permite commitar instruções persistentes em .kiro/steering/ que se aplicam a toda interação de agente em todo o time. Um único arquivo de steering torna a geração de ADR automática:

When generating or updating design.md for any spec, also create or update
a decisions/ subdirectory within the spec folder. For each significant
architectural choice — technology selection, data model, integration
pattern, security mechanism — create an ADR file following the naming
convention ADR-NNN-short-title.md.

Each ADR must include: Status, Context, Decision, and Consequences
(positive, negative, risks). Record options considered but not chosen
and the reasons they were rejected.

Uma vez commitada, essa instrução vale para o time inteiro. Os ADRs são produzidos sem ninguém precisar lembrar de produzi-los.

# ADR-001: Use PostgreSQL over DynamoDB for review storage

## Status
Accepted

## Context
The review system requires complex multi-column filtering (rating, date, product).
DynamoDB's query model requires denormalized duplicates per access pattern,
increasing storage and write complexity by an estimated 3-4x.
The team has existing PostgreSQL operational experience and monitoring tooling.
DynamoDB was the initial default assumption given existing AWS infrastructure.

## Decision
Use PostgreSQL with a normalized schema. Index the columns used in the four
most common filter combinations. Accept the horizontal scaling trade-off.

## Consequences
- Positive: Query logic is significantly simpler; existing tooling applies
- Negative: Horizontal scaling requires more coordination than DynamoDB
- Risk: Revisit if read throughput exceeds 20k RPS at peak; document threshold

Captura de decisões de meio de implementação via Hooks

As decisões tomadas no momento do design são as fáceis de capturar. As perigosas acontecem durante a implementação: uma biblioteca que se revela com um caso extremo quebrado, uma medição de performance que muda o padrão de acesso a dados. Essas se resolvem numa conversa ou numa alteração rápida de código, e nunca são registradas em lugar nenhum.

Um Kiro Hook em mudanças no design.md resolve isso. Quando uma modificação é feita no documento de design (por um engenheiro ou pelo Kiro durante a execução de tarefas), o Hook dispara um agente para avaliar se a mudança representa uma nova decisão de arquitetura e, se representar, rascunha um ADR para o time revisar. A spec e o registro de decisão ficam sincronizados ao longo da implementação, não só no momento do design inicial.

ADRs em pipelines multiagentes: uma abordagem complementar

ADRs automatizados não são exclusividade do Kiro; você pode adicionar um agente ADR Writer a um pipeline existente do CrewAI ou LangGraph. Mas se o ADR resultante chega ao time num formato revisável depende de como você conectou a saída do pipeline ao seu workflow de desenvolvimento. O Kiro embute o ADR num workflow em que o time vê, revisa e contesta antes de o código ser escrito.

Para times que já rodam pipelines multiagentes, os dois convivem naturalmente: o Kiro cuida do design, das specs e da captura de decisões; seu pipeline existente cuida das tarefas de execução delimitadas dentro das restrições que a spec estabeleceu. A spec vira o contrato entre a fase de design (onde o time tem supervisão) e a fase de execução (onde os agentes operam com mais autonomia).

Onde o modelo falha

Seria desonesto não nomear os modos de falha, porque eles não são óbvios até você estar a algumas sprints adentro.

A qualidade da spec é limitada pela qualidade do prompt

Os documentos de requisitos e design do Kiro são tão bons quanto a descrição inicial que você dá. Um prompt vago produz uma spec vaga, mas agora é uma spec vaga com aparência de rigor, porque está formatada em notação EARS, com critérios de aceitação e tudo mais. Isso é pior do que não ter spec, porque o time revisa, vê a estrutura e supõe que o conteúdo é sólido.

A mitigação é cultural, não técnica: trate a revisão da spec como uma revisão de design de verdade, não como carimbo. Se os requisitos parecem genéricos ou o design não cobre suas restrições específicas, conteste antes de aprovar. O ponto inteiro da etapa de aprovação é que ela é uma etapa, não uma formalidade.

A notação EARS pode produzir falsa precisão

O EARS é bom em eliminar ambiguidade em requisitos individuais. O que ele não faz é garantir completude: você pode ter vinte requisitos perfeitamente inequívocos que, juntos, deixam de fora o problema realmente difícil. Já vi o Kiro gerar requisitos EARS tecnicamente corretos, mas operacionalmente inúteis, porque descrevem o caminho feliz em detalhe e ignoram os modos de falha que vão de fato determinar se o sistema funciona em produção.

O conserto: ao revisar requirements.md, não cheque só se cada requisito está bem-formado. Verifique se o conjunto de requisitos cobre os casos de falha, os casos extremos e as preocupações operacionais (monitoramento, alertas, rollback) que importam para o seu sistema. Se não cobre, adicione antes de aprovar.

ADRs gerados automaticamente podem ser superficiais

Um arquivo de steering que diz "gere ADRs para escolhas arquiteturais significativas" vai produzir ADRs. Se esses ADRs trazem raciocínio útil depende de quanto contexto o Kiro tem sobre as suas restrições. Um ADR que diz "escolhemos PostgreSQL porque ele suporta queries relacionais" é tecnicamente correto e completamente inútil; qualquer engenheiro sênior já sabe disso. O valor está nas alternativas rejeitadas e nas razões específicas pelas quais foram rejeitadas.

Ajuste seu arquivo de steering para ser explícito sobre o que você quer capturar. Em vez de "registre escolhas significativas", tente "para cada seleção de tecnologia, documente pelo menos duas alternativas avaliadas, a razão técnica ou operacional específica pela qual cada uma foi rejeitada e as condições sob as quais a decisão deve ser revisitada." Quanto mais específica a instrução, mais útil o output.

Spec drift é silencioso por padrão

O Kiro não detecta automaticamente quando a implementação diverge do design. A spec é um snapshot da intenção no momento do design. Se um engenheiro (ou um agente em modo autopilot) faz uma mudança que contradiz o design (um banco diferente, um endpoint adicional na API, um modelo de dados alterado), os arquivos de spec não se atualizam sozinhos.

Isso é resolvível com Hooks, como descrito acima, mas não é o comportamento padrão. Se você está adotando o Kiro, configurar Hooks de detecção de drift deveria fazer parte da sua configuração inicial, não algo que você adiciona depois de descobrir o problema.

A governança para na fronteira do design

Em dezembro de 2025, um agente do Kiro deletou um ambiente de produção AWS em operação, causando uma indisponibilidade de 13 horas do AWS Cost Explorer numa região da China (The Register, fev/2026). A Amazon atribuiu o incidente ao fato de a função do engenheiro ter permissões mais amplas do que o pretendido. Reportagens independentes descreveram o Kiro decidindo de forma autônoma deletar e recriar o ambiente em vez de aplicar uma correção pontual — uma distinção que a Amazon contestou.

As duas versões levam à mesma lição: um time pode ter specs revisadas, designs aprovados e ADRs documentados, e ainda assim sofrer uma falha catastrófica porque ninguém revisou o que aconteceu entre o design aprovado e o deploy em produção.

O modelo de governança do Kiro cobre a fase de design a fundo. O que ele não cobre é a fronteira de execução: o momento em que um agente atua sobre infraestrutura real com permissões reais. O modo autopilot é útil, mas exige a mesma disciplina de qualquer pipeline de CI/CD: revisão de deploy, permissões com escopo limitado e uma pessoa no loop antes de mudanças chegarem à produção. O workflow de spec faz parecer fácil presumir que a governança está resolvida. Não está, a menos que seu time estenda essa disciplina para além do ponto onde o workflow do Kiro termina.

O que muda para o time

O design acontece em público, não em sessões privadas de agente

Num pipeline multiagente, a decisão de design é tomada dentro do pipeline. Quando um membro do time vê, ela já está implementada ou foi commitada num arquivo de saída que pode ou não chegar a um pull request. Com o Kiro, o documento de design é o primeiro output commitado no repositório, antes de a implementação começar. O time vê e revisa o design conforme ele é criado, não depois.

Isso muda o code review diretamente. Revisar código sem uma spec significa inferir intenção a partir da implementação, o que é lento e enviesado para comentários de estilo em vez de substância. Revisar código contra uma spec significa checar se a implementação atende aos requisitos declarados e se as escolhas se alinham com o raciocínio documentado. As revisões ficam mais rápidas e mais substantivas.

Trabalho paralelo expõe conflitos cedo

Pipelines multiagentes normalmente operam num único contexto de tarefa. Num time onde vários engenheiros constroem em paralelo, cada um usando suas próprias sessões de agente ou rodando seus próprios pipelines, não há mecanismo para detectar que duas features estão fazendo suposições arquiteturais conflitantes. As specs do Kiro, commitadas antes da implementação, fornecem o ponto de referência compartilhado que torna esses conflitos visíveis no momento certo, antes de o código conflitante ser escrito.

O conhecimento sobrevive à troca de pessoas

Quando um engenheiro sai de um time que estava fazendo vibe coding ou rodando pipelines de agente sem estrutura, o contexto vai junto com ele. Já vi isso acontecer vezes suficientes para saber como termina: três meses depois, alguém está fazendo engenharia reversa de um serviço que ninguém entende totalmente. Os ADRs e specs no modelo do Kiro estão atrelados ao repositório, não às pessoas. O raciocínio por trás de cada decisão significativa fica disponível para quem vier a seguir, seja um engenheiro entrando daqui a três meses ou um time herdando o sistema daqui a três anos.

O desafio honesto

Fica aqui o desafio honesto para times rodando pipelines multiagentes: seu pipeline produz código. Você sabe por que ele foi projetado do jeito que foi? Seu time sabe? Vão saber daqui a seis meses? Se a resposta a qualquer uma dessas é incerta, você está acumulando dívida de conhecimento que vai compor.

Essa dívida tem um arco previsível: a velocidade cai, o onboarding desacelera e, em algum momento, alguém propõe a reescrita — porque modificar um sistema que ninguém entende parece mais arriscado do que começar do zero.

O Kiro não substitui seu ferramental multiagente para execução de tarefas delimitadas. Ele fornece a camada estrutural (specs, ADRs, Hooks, artefatos visíveis ao time e commitados antes da implementação) que transforma output gerado por IA em software que seu time consegue de fato ter como seu.

A questão do overhead

O workflow de spec adiciona tempo de planejamento antes da implementação. Para um script de vida curta ou uma tarefa de automação delimitada, esse overhead não se justifica. Alguns times percebem que a abordagem estruturada do Kiro super-especifica problemas simples, e as etapas de aprovação adicionam fricção que parece desnecessária para mudanças de baixo risco.

O time de Martin Fowler examinou ferramentas de desenvolvimento spec-driven (Kiro entre elas) e concluiu que a abordagem opinativa, de workflow único, provavelmente "não é adequada para a maioria dos problemas reais de programação." Eles têm razão. A maior parte do trabalho diário de engenharia é modificação de sistemas existentes, correção de bugs e mudanças incrementais — trabalho em que um ciclo completo de spec cria mais fricção do que valor. A defesa do desenvolvimento spec-driven se sustenta no subconjunto de trabalho em que decisões de arquitetura estão sendo tomadas e o custo de errar é alto. Esse subconjunto é menor do que este artigo pode sugerir, mas é onde acontecem os erros mais consequentes.

O Kiro oferece tanto o modo spec-driven quanto o vibe coding na mesma IDE, e os dois convivem bem: vibe coding para exploração e trabalho descartável, specs para qualquer coisa que vá ser mantida. A pergunta mais difícil é se os times estão aplicando esse julgamento com precisão. Na minha experiência, a tentação é usar o caminho rápido para tudo e se convencer de que a feature é mais simples do que é. A maior parte da dívida de conhecimento em bases de código é o resíduo acumulado dessa decisão, tomada muitas vezes.

Uma heurística prática: use o modo spec quando qualquer uma destas for verdadeira — a feature toca um modelo de dados, introduz uma nova integração externa, atravessa uma fronteira de segurança ou vai ser trabalhada por mais de um engenheiro. Use vibe coding para todo o resto. O custo de uma decisão de arquitetura errada compõe a cada sprint que se segue; o custo de super-especificar um script descartável é uma hora do seu tempo.

Para times adotando o modo spec pela primeira vez, uma abordagem em fases reduz a resistência. Comece com uma feature nova que satisfaça pelo menos duas das condições da heurística acima — complexidade suficiente para tornar a spec valiosa, sem tanto a ponto de tornar a primeira experiência avassaladora. Conduza a revisão da spec como uma reunião de design real: indique alguém para contestar o documento de requisitos antes da aprovação, e não só lê-lo. Depois que a primeira feature for entregue, faça uma retrospectiva curta sobre se a spec capturou algo que de outra forma teria aparecido mais tarde. Esse único dado — "pegamos o problema de schema na revisão de design em vez de em produção" — é mais persuasivo para um time de engenharia cético do que qualquer argumento de processo.

Conclusão

A geração atual de ferramental de desenvolvimento com IA basicamente resolveu o problema de produzir código. As ferramentas conseguem transformar requisitos em linguagem natural em implementações funcionais a uma velocidade que pareceria implausível há três anos.

O que a maioria delas não resolveu é o problema do time: como um grupo de engenheiros constrói software em conjunto, com assistência de IA, de um jeito que produz entendimento compartilhado, e não output compartilhado que ninguém realmente possui? Como você responde "por que foi projetado assim?" quando o design aconteceu dentro de uma sessão de agente que mais ninguém viu?

A resposta do Kiro é estrutural: produzir os artefatos que tornam essas perguntas respondíveis, antes de o código existir, como parte padrão do workflow. Os arquivos de spec dão ao time visibilidade sobre a intenção do design. Os ADRs, gerados por um arquivo de steering que você configura e mantidos atualizados via Hooks, dão ao time visibilidade sobre o raciocínio das decisões. Ambos vivem no repositório e trafegam por pull requests como qualquer outro artefato de código.

Para times que já usam frameworks multiagentes para tarefas de execução, o Kiro não é um substituto. É a camada que essas ferramentas não fornecem: um workflow revisável e visível ao time, que captura decisões e transforma código gerado por IA em software que um time de engenharia consegue manter.

O problema da execução está em grande parte resolvido. O do time, não. Esse é o problema que vale a pena resolver — e é nele que o resto da indústria de ferramentas ainda não apostou.