Adoção do Kiro: método e governança no repositório do seu time

Um agente no time muda a pergunta da revisão

Um assistente que completa a linha é revisado linha a linha. Um agente lê o repositório, escreve em vários arquivos, executa comandos e chama ferramentas externas. A pergunta deixa de ser só "o código ficou bom?" e passa a ser o que o agente sabe do projeto, o que ele pode executar e quem aprova cada etapa.

O Kiro responde a essas perguntas com arquivos que ficam no repositório: steering para a convenção do time, specs para requisito, desenho e tarefas, hooks para automação por evento e regras de permissão para o que o agente executa. Adotar o Kiro é decidir o conteúdo desses arquivos para o seu time e colocá-los sob revisão, como qualquer código.

Para times que usam os plugins do Amazon Q Developer na IDE, a AWS anunciou o fim do suporte em 30/04/2027 e indica o Kiro para recursos semelhantes. A troca de ferramenta é a ocasião certa para registrar o método junto; o passo a passo por editor está em Amazon Q Developer para o Kiro, e a visão geral do produto, no guia do Kiro. A adoção do Kiro faz parte do pilar de IA aplicada da RFX.

Para quem é

• CTOs e heads de engenharia que precisam decidir como a IA entra no desenvolvimento com política de dado, controle de custo e trilha do que foi decidido
• Engineering managers e tech leads que querem requisito, desenho e tarefas revisados antes do código, no mesmo fluxo de PR que o time já usa
• Devs que já programam com IA e querem que o agente siga a convenção do projeto em toda sessão, com automação que roda sozinha e limites claros do que ele executa
• Times de plataforma e DevOps que vão operar a CLI do Kiro no pipeline e conectar o agente a ferramentas internas por MCP

O que a RFX entrega na adoção

• Steering do repositório. Produto, tecnologia e estrutura descritos em .kiro/steering/, mais arquivos por domínio (API, testes, dados) carregados só quando o agente mexe nos arquivos daquele domínio
• Padrão de spec. Quando usar spec de funcionalidade ou de correção, requisitos em notação EARS, critério de revisão de requirements.md, design.md e tasks.md em PR antes do código
• Hooks e governança. Lint e testes nos eventos do agente, com a mesma checagem no CI para cobrir a edição manual, bloqueio de operação sensível antes da ferramenta rodar e hooks versionados em .kiro/hooks/, com dono e propósito documentados
• Permissões e segredo. Regras de allow, ask e deny por capacidade, .kiroignore para o que o agente não lê e a rota de distribuição das regras: arquivo do usuário, agente versionado no repositório ou política central no Enterprise
• MCP com escopo. Servidores declarados no workspace, aprovação automática só para ferramentas de leitura e credencial por variável de ambiente
• Integração com o fluxo do time. Spec ligada ao item do backlog, revisão em PR e a CLI do Kiro em modo headless no pipeline, com ferramentas de leitura explícitas
• Segurança, LGPD e custo. Escolha de plano e região, configuração de telemetria e conteúdo, avaliação de transferência internacional e governança de créditos

Como a RFX configura, na prática

Os exemplos abaixo seguem a sintaxe da documentação oficial do Kiro, com o link de cada recurso. São o ponto de partida que a RFX adapta ao repositório e ao fluxo de cada time. Os exemplos são para o time técnico; quem decide pela adoção pode ir direto a Decisões de arquitetura e a Segurança, LGPD e custo.

Steering: a convenção do time em arquivo

O steering é markdown em .kiro/steering/. Os três arquivos de base são product.md, tech.md e structure.md. O que separa um steering útil de um decorativo é o modo de inclusão: always entra em toda interação, fileMatch entra quando o agente trabalha em arquivos do padrão, manual entra sob demanda e auto entra quando a descrição combina com a solicitação.

Armadilhas que a RFX corrige primeiro:

• Regra que não se verifica. "Escreva código limpo" ocupa contexto e não muda o resultado. Regra boa é verificável na revisão: formato de rota, formato de erro, onde fica o contrato
• Tudo em always. A convenção de banco entra quando o agente edita CSS. Arquivo por domínio com fileMatch mantém o contexto enxuto
• Regra sem o porquê. A documentação recomenda explicar a razão da decisão, e é ela que permite ao agente acertar o caso que a regra não previu
• Steering pessoal contra o do time. Em conflito, o steering do workspace vence o global de ~/.kiro/steering/. A convenção do time mora no repositório
• Segredo no steering. Chave de API e senha ficam fora, como a documentação determina, e o arquivo passa por PR como código

---
inclusion: fileMatch
fileMatchPattern: ["src/api/**/*.ts", "src/routes/**/*.ts"]
---
# Convenções de API REST

- Rotas no plural e em kebab-case: /faturas, /faturas/{id}/itens
- Erro sempre no formato do contrato:
  { "codigo": "FATURA_NAO_ENCONTRADA", "mensagem": "..." }
- Rota nova entra primeiro no contrato:
  #[[file:docs/api/openapi.yaml]]
- Entrada validada na borda pelo schema do contrato;
  o handler recebe o dado já validado.

## Por quê
O contrato é consumido pelo app e por integrações externas.
Mudança fora dele quebra cliente sem aviso.

Guia completo da RFX: Steering no Kiro, com modos de inclusão, estrutura recomendada e exemplos de arquivo.

Spec: requisito testável antes do código

Uma spec gera três artefatos: requirements.md (ou bugfix.md, na spec de correção), design.md e tasks.md. Na spec de funcionalidade, os critérios de aceitação seguem a notação EARS: WHEN [condição] THE SYSTEM SHALL [comportamento]. Na spec de correção, o comportamento que não pode mudar entra como WHEN [condição] THEN the system SHALL CONTINUE TO [comportamento atual], que é a forma de registrar a regressão que o time quer evitar.

As decisões que a RFX fixa no padrão do time, a partir das boas práticas oficiais:

• Requirements-First ou Design-First. Requisitos primeiro quando o comportamento é conhecido; desenho primeiro quando a arquitetura já existe. A escolha acontece na criação e não muda no meio da spec
• Quick Spec ou spec com aprovação. A Quick Spec gera os três arquivos de uma vez, sem etapas de aprovação, e serve para o que o time domina. Domínio novo ou sujeito a auditoria vai pela spec com revisão por etapa
• Uma spec por funcionalidade. Spec do sistema inteiro vira documento que ninguém revisa. Spec pequena, ligada a um item do backlog, é revisada em PR antes de gerar código
• Analyze Requirements antes do desenho em regra de negócio sensível, para achar contradição e lacuna enquanto ainda é texto
• Dependência declarada nas tarefas. Ao executar todas as tarefas, o Kiro agrupa as independentes em ondas que rodam em paralelo. Duas tarefas que mexem no mesmo módulo precisam da dependência explícita no tasks.md

# Requisitos: cancelamento de assinatura pelo portal

## Requisito 1
**História:** Como assinante, quero cancelar a assinatura
pelo portal, para encerrar a renovação sem abrir chamado.

### Critérios de aceitação
1. WHEN o assinante confirma o cancelamento
   THE SYSTEM SHALL encerrar a renovação automática e
   registrar data, hora e canal da solicitação
2. WHEN a assinatura tem fatura em aberto
   THE SYSTEM SHALL exibir o valor pendente antes da
   confirmação
3. WHEN o serviço de cobrança está indisponível
   THE SYSTEM SHALL manter a assinatura ativa e informar
   que a solicitação não foi concluída

Guia completo da RFX: Specs no Kiro, com o checklist de revisão de cada arquivo e a execução em ondas.

Hooks: o que é determinístico vira comando

Um hook é um JSON em .kiro/hooks/ que reage a um evento: prompt enviado, arquivo salvo, criado ou apagado pelo agente, antes e depois de uma ferramenta, antes e depois de uma tarefa de spec, fim do turno do agente (a lista completa está nos tipos de hook). A ação é um comando de shell ou um prompt para o agente. A escolha entre os dois é a decisão de arquitetura que mais pesa no dia a dia:

• Comando para o que tem resposta certa. Lint, formatação, teste e varredura de segredo. Segundo as boas práticas de hooks, comando de shell é mais rápido e não consome créditos
• Prompt para o que pede julgamento. Atualizar a documentação da rota alterada ou revisar se o teste cobre o critério da spec. Prompt curto e com passos numerados
• Bloqueio antes da ferramenta. O hook de antes da ferramenta pode validar e barrar a chamada: é onde entra a operação que o time quer sempre conferida
• Edição manual não dispara. Segundo os tipos de hook, os gatilhos de arquivo respondem só ao que o agente altera. O lint do exemplo abaixo cobre a edição do agente; a mesma verificação vai também para o CI, que cobre a edição feita à mão
• Armadilha: hook de agente em padrão largo. Um hook de agente em PostFileSave dispara a cada arquivo que o agente salva, gasta crédito e pode abrir um ciclo se pedir ao agente que reescreva o próprio arquivo. Comece por um padrão estreito e defina o timeout do comando, que por padrão é de 60 segundos segundo a documentação

{
  "version": "v1",
  "hooks": [{
    "name": "Lint on save",
    "trigger": "PostFileSave",
    "matcher": "\\.(ts|tsx)$",
    "action": { "type": "command", "command": "npx eslint --fix" }
  }]
}

Guia completo da RFX: Hooks no Kiro, com os gatilhos, o bloqueio antes da ferramenta e cinco hooks de referência.

Permissões: o agente executa o que o time decidiu

As permissões são regras por capacidade (shell, fs_read, fs_write, mcp) com efeito allow, ask ou deny. Três propriedades da documentação orientam o desenho: o efeito mais restritivo vence e nenhum allow derruba um deny; o comando de shell é dividido em ;, &&, || e |, e cada parte é conferida; e as regras ficam em ~/.kiro/settings/permissions.yaml ou num arquivo por usuário fora do repositório, de modo que um repositório clonado não injeta regra.

A consequência prática é que a política do time não chega pelo permissions.yaml de um commit. Pelos escopos da documentação, há três rotas para distribuí-la, e a RFX escolhe com o time pelo trade-off de cada uma:

• Arquivo do usuário. O ~/.kiro/settings/permissions.yaml instalado no onboarding aceita allow, ask e deny, mas vale por máquina e depende de cada pessoa manter a versão em dia
• Agente versionado. O campo permissions do arquivo de agente em .kiro/agents/ fica no repositório e passa por pull request; vale para quem usa aquele agente, como o revisor do pipeline
• Política da organização. No Enterprise, o managed-settings.json distribuído por MDM só aceita deny e ask e, se estiver inválido, o Kiro falha fechado. Segundo a documentação de políticas de permissão, a aplicação é no cliente e pode ser contornada por quem tem acesso de administrador na própria máquina

Dois pontos que a documentação deixa explícitos e que entram no treinamento: segundo a seção Autopilot versus supervised mode, os dois modos dão as mesmas capacidades ao agente, e o Supervised é fluxo de revisão, não controle de segurança; e no modo headless não há a quem perguntar, então todo ask vira deny. Para leitura, o .kiroignore usa a sintaxe do .gitignore e tira arquivo do alcance do agente, inclusive das buscas.

• Armadilha: allow amplo no shell. Liberar "git *" libera também o push. O exemplo abaixo libera só leitura do git e os scripts de teste e lint, e nega o resto que é sensível

rules:
  # leitura do git e scripts do projeto, sem publicar pacote
  - capability: shell
    effect: allow
    match: ["git status", "git diff *", "git log *", "npm test*", "npm run lint*"]
    exclude: ["npm publish*"]

  # nunca, em nenhum modo
  - capability: shell
    effect: deny
    match: ["git push *", "rm -rf *", "sudo *"]

  # segredo fora do alcance do agente
  - capability: fs_read
    effect: deny
    match: ["**/.env", "**/.env.*", "secrets/**", "**/*.pem"]

Guia completo da RFX: Governança de IA no código, com os seis escopos de permissão, o managed-settings.json e a trilha de auditoria.

MCP com escopo: ferramenta externa com credencial fora do arquivo

A configuração de MCP do workspace fica em .kiro/settings/mcp.json e prevalece sobre a do usuário. O exemplo conecta o AWS Documentation MCP Server, com aprovação automática só para as ferramentas de leitura, e um servidor interno remoto com o token lido de variável de ambiente.

• "autoApprove": ["*"]. Aprova toda ferramenta do servidor, inclusive as que escrevem. A aprovação automática é lista explícita de ferramentas de leitura
• Token literal no JSON. O arquivo vai para o repositório. Credencial entra como ${VARIAVEL}, e na IDE o Kiro só expande variável aprovada na configuração "Mcp Approved Env Vars"
• Versão solta. O exemplo usa @latest, como a documentação do servidor. No arquivo do time, a RFX fixa a versão para que a atualização passe por revisão como qualquer dependência
• Ferramenta perigosa escondida. O disabledTools tira a ferramenta do alcance do agente, e só se instala servidor de origem confiável

{
  "mcpServers": {
    "aws-docs": {
      "command": "uvx",
      "args": ["awslabs.aws-documentation-mcp-server@latest"],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR",
        "AWS_DOCUMENTATION_PARTITION": "aws"
      },
      "autoApprove": ["search_documentation", "read_documentation"]
    },
    "backlog-interno": {
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer ${BACKLOG_MCP_TOKEN}" },
      "autoApprove": [],
      "disabledTools": ["delete_issue"]
    }
  }
}

Guia completo da RFX: MCP no Kiro, com Powers, servidores da AWS e credencial de curta duração.

CLI headless: o Kiro no pipeline, só com leitura

O modo headless da CLI roda um prompt sem sessão interativa, autenticado pela variável KIRO_API_KEY. Segundo a documentação, a chave de API existe nos planos Pro, Pro+, Pro Max e Power, e em assinatura gerida por administrador ele precisa liberar a geração antes. No pipeline, a chave vem do cofre de segredos do CI, nunca do repositório.

• --trust-all-tools no CI. Aprova toda ferramenta numa execução que ninguém acompanha. A RFX usa --trust-tools com a lista exata de ferramentas de leitura, como no exemplo oficial de revisão de PR
• Servidor MCP obrigatório. Com --require-mcp-startup, a execução falha com código 3 se o servidor não subir, em vez de rodar sem a ferramenta e devolver uma análise incompleta

# KIRO_API_KEY injetada pelo cofre de segredos do CI
curl -fsSL https://cli.kiro.dev/install | bash

kiro-cli chat --v3 --no-interactive \
  --trust-tools=read_file,grep_search \
  "Revise as mudanças deste PR em busca de problemas de segurança"

O script de instalação traz sempre a última versão da CLI. Em produção, a RFX não deixa o pipeline depender disso: a versão é homologada e fixada numa imagem de runner ou num artefato interno, e cada atualização entra por pull request. O desenho completo está em Kiro CLI no pipeline.

Decisões de arquitetura da adoção

Cada linha é uma decisão que a RFX leva para o time tomar com os dois lados à vista. O critério vem do contexto do time, não de uma preferência da ferramenta.

Fontes: Kiro Enterprise, permissões, kiro.dev (modo Auto), specs, boas práticas de hooks e steering.

Segurança, LGPD e custo

A documentação de proteção de dados separa o que muda por plano. No Free e nos planos individuais, o conteúdo pode ser usado para melhoria do serviço, sujeito ao opt-out em Settings, Telemetry and Content, e fica armazenado em US East (N. Virginia). No Free Tier, a mesma página prevê ainda a retenção das entradas por até 60 dias para detecção de abuso, fora do alcance do opt-out; por isso o Free não entra em piloto com código de cliente. No Enterprise, o conteúdo não é usado para melhoria do serviço e fica na região do perfil: US East (N. Virginia) ou Europe (Frankfurt) nas regiões comerciais. São Paulo aparece só como região do IAM Identity Center, onde ficam as identidades. O Kiro Web está disponível apenas em us-east-1, roda num sandbox gerenciado na nuvem e fica fora das regras de permissão, do .kiroignore e dos hooks: habilitar ou não as Cloud Sessions é uma decisão própria do administrador. A criptografia em repouso usa chaves do AWS Key Management Service (AWS KMS), e o administrador do Enterprise pode configurar chave gerenciada pelo cliente.

A leitura completa das duas páginas oficiais está no guia do Kiro, na seção de dados e LGPD. Para a LGPD, isso significa transferência internacional de dados sempre que dado pessoal chega ao contexto do agente. A RFX trata a questão em duas frentes: tira do alcance do agente o que não precisa estar lá (.kiroignore, regra de fs_read e steering que proíbe dado real em prompt e fixture) e registra a base e o plano escolhidos na avaliação do controlador. A documentação também lembra que o agente acessa arquivos locais, variáveis de ambiente e credenciais AWS da máquina: o perfil AWS usado com o Kiro é de leitura, como no exemplo de escopo do Kiro na operação.

O custo é por crédito. A página de preços, consultada em 15/10/2026, lista os planos Free, Pro, Pro+, Pro Max e Power, com cota mensal de créditos por usuário que não acumula para o mês seguinte. Nos planos individuais, o uso além da cota vem da compra de pacotes de créditos adicionais a US$ 0,04 por crédito, cobrados na compra e com validade de 12 meses. No Enterprise, o excedente começa desabilitado e, quando o administrador habilita, é cobrado a US$ 0,04 por crédito no fechamento do mês. A governança que a RFX monta junto: hook de comando no lugar de hook de agente onde a resposta é determinística, steering enxuto por domínio, Quick Spec só no que o time domina e acompanhamento do consumo por usuário no primeiro mês. O método de estimativa está em Custo de IA generativa na AWS, e a forma de provar o retorno, em Como medir a adoção de IA no time.