guias·Fabricio Telles

Como Usar o Kiro: Tutorial Completo do Zero à Produção

Guia prático passo a passo para usar o Kiro da AWS. Da instalação ao primeiro spec, com steering files, hooks e dicas de otimização de créditos.

kirokiro-idekiro-clitutorialawsspec-driven-development

Como Usar o Kiro: Tutorial Completo do Zero à Produção

Diagrama mostrando o workflow do Kiro: prompt em linguagem natural transformado em specs e depois em código

Este é o guia prático pra quem quer começar a usar o Kiro da AWS. Nada de teoria sobre spec-driven development — a gente vai instalar, configurar e criar seu primeiro projeto com specs funcionando de verdade.

Tempo estimado: 30 minutos do zero ao primeiro código gerado a partir de specs.

O Que Você Vai Aprender

  1. Instalar Kiro IDE e CLI
  2. Configurar autenticação
  3. Criar seu primeiro projeto com specs
  4. Configurar steering files para sua stack
  5. Usar hooks para automação gratuita
  6. Otimizar uso de créditos

Parte 1: Instalação

Kiro IDE (macOS, Windows, Linux)

macOS:

  1. Acesse kiro.dev/downloads
  2. Baixe o .dmg
  3. Arraste para Applications
  4. Na primeira execução, clique com botão direito → Abrir (contornar Gatekeeper)
  5. Faça login com AWS Builder ID, Google ou GitHub

Windows:

  1. Baixe o .exe de kiro.dev
  2. Execute o instalador (permissões de admin)
  3. Kiro adiciona-se ao PATH automaticamente
  4. Faça login

Linux:

sudo dpkg -i kiro_*.deb
sudo apt-get install -f
kiro

O Kiro é baseado em Code OSS (VS Code open source). Suas extensões Open VSX e configurações do VS Code são compatíveis. Na primeira execução, você pode importar settings existentes.

Kiro CLI

O CLI funciona em qualquer sistema:

curl -fsSL https://cli.kiro.dev/install | bash

Depois, autentique:

kiro login

Isso abre o navegador para login. Uma vez autenticado, o CLI compartilha a mesma assinatura e créditos do IDE.

Verificar instalação:

kiro --version

Parte 2: Seu Primeiro Projeto com Specs

Vamos criar uma API simples de tarefas (to-do list) usando o workflow completo de specs.

Passo 1: Abra o Projeto no Kiro IDE

mkdir meu-projeto-kiro
cd meu-projeto-kiro
npm init -y

Abra no Kiro IDE: kiro . ou via menu File → Open Folder.

Passo 2: Inicie uma Nova Spec

No Kiro IDE, pressione Cmd+Shift+S (ou Ctrl+Shift+S no Windows/Linux) para abrir o painel de Specs.

Digite seu prompt em linguagem natural:

Crie uma API REST de tarefas (to-do) com:
- CRUD completo (criar, listar, atualizar, deletar)
- Validação de campos obrigatórios
- Filtro por status (pendente, concluído)
- Ordenação por data de criação

Passo 3: Revise os Requisitos

O Kiro gera requirements.md com user stories em formato EARS:

## User Stories

### US-001: Criar Tarefa
QUANDO o usuário enviar POST /tasks com título válido
O SISTEMA DEVE criar a tarefa com status "pendente"
E retornar a tarefa criada com id único

### US-002: Listar Tarefas
QUANDO o usuário enviar GET /tasks
O SISTEMA DEVE retornar todas as tarefas
E suportar filtro por query param ?status=pendente|concluido

[...]

Revise, adicione edge cases que faltaram, e dê o OK. Este é o momento mais importante — você está definindo o contrato do que vai ser construído.

Passo 4: Revise o Design

Com requisitos aprovados, o Kiro analisa seu codebase e gera design.md:

## Arquitetura

### Endpoints
- POST /tasks - Criar tarefa
- GET /tasks - Listar tarefas (com filtros)
- GET /tasks/:id - Buscar tarefa
- PUT /tasks/:id - Atualizar tarefa
- DELETE /tasks/:id - Deletar tarefa

### Schema
```typescript
interface Task {
  id: string;
  title: string;
  description?: string;
  status: 'pending' | 'completed';
  createdAt: Date;
  updatedAt: Date;
}

Validação

  • title: required, min 1 char, max 200 chars
  • description: optional, max 1000 chars
  • status: enum validation

[…]


Revise a arquitetura. Se algo não faz sentido para seu contexto, edite antes de aprovar.

### Passo 5: Execute as Tarefas

O Kiro gera `tasks.md` com implementação sequenciada:

```markdown
## Tarefas

- [ ] T1: Criar schema do banco (migration)
- [ ] T2: Implementar modelo Task
- [ ] T3: Criar endpoint POST /tasks
- [ ] T4: Criar endpoint GET /tasks com filtros
- [ ] T5: Criar endpoint GET /tasks/:id
- [ ] T6: Criar endpoint PUT /tasks/:id
- [ ] T7: Criar endpoint DELETE /tasks/:id
- [ ] T8: Adicionar testes unitários
- [ ] T9: Adicionar validação de input

Clique em “Execute” em cada tarefa. O Kiro implementa, e você revisa o diff antes de aceitar.

Dica: Se uma implementação tomou rumo errado, use checkpointing para voltar ao estado anterior sem perder trabalho.

Parte 3: Steering Files

Steering files são instruções que ficam salvas sobre seu projeto. Em vez de explicar suas convenções toda hora que abre um chat, você documenta uma vez e o Kiro lê sempre.

Criar Steering Files

Crie a pasta .kiro/steering/ na raiz do projeto:

mkdir -p .kiro/steering

Exemplo: Convenções Node.js/TypeScript

Crie .kiro/steering/conventions.md:

# Convenções do Projeto

## Stack
- Runtime: Node.js 22+
- Linguagem: TypeScript strict mode
- Framework: Express.js
- ORM: Prisma
- Testes: Vitest

## Padrões de Código
- Sempre usar async/await (nunca callbacks ou .then)
- Validação de input com Zod em todos os endpoints
- Tratamento de erros com try/catch e middleware de error handling
- Logs estruturados com pino

## Estrutura de Pastas
- src/modules/{feature}/ — cada feature isolada
- src/shared/ — utilitários compartilhados
- src/infra/ — configurações de banco, cache, etc.

## Git
- Commits seguem Conventional Commits
- Branch naming: feature/xxx, fix/xxx, chore/xxx

## Não Fazer
- Nunca usar any em TypeScript
- Nunca commitar credenciais
- Nunca usar console.log em produção

O Kiro lê esses arquivos automaticamente e segue suas convenções em toda interação.

Steering Global vs Local

  • .kiro/steering/ no projeto → aplicado a esse projeto
  • ~/.kiro/steering/ no home → aplicado a todos os projetos

Parte 4: Hooks (Automação Gratuita)

Hooks são automações que disparam ações do agente quando eventos ocorrem. E não contam contra seus créditos — são completamente gratuitos.

Eventos Disponíveis

  • On save — quando você salva um arquivo
  • On create — quando um novo arquivo é criado
  • On delete — quando um arquivo é removido
  • Manual trigger — quando você dispara manualmente

Exemplo: Atualizar Testes ao Salvar

No Kiro IDE, pressione Cmd+Shift+K → “New Hook”:

Nome: update-tests-on-save
Trigger: On Save
File Pattern: src/**/*.ts
Ação: Se o arquivo modificado é um módulo, atualize o arquivo de teste correspondente em tests/ para cobrir as mudanças

Exemplo: Lint Automático em Python

Nome: auto-lint-python
Trigger: On Save
File Pattern: **/*.py
Ação: Execute ruff check e ruff format no arquivo. Se houver erros de lint que podem ser corrigidos automaticamente, corrija-os.

Exemplo: Docs ao Modificar API

Nome: update-api-docs
Trigger: On Save
File Pattern: src/routes/**/*.ts
Ação: Atualize o arquivo docs/api.md com a documentação atualizada dos endpoints modificados

Hooks São Commitáveis

Hooks ficam em .kiro/hooks/ e são versionados no Git. Toda a equipe se beneficia das mesmas automações.

Parte 5: Kiro CLI para o Dia a Dia

O CLI complementa o IDE para tarefas rápidas e automação.

Sessão Interativa

cd meu-projeto
kiro chat

Você entra num loop de conversa:

> Explique a arquitetura do módulo de autenticação

O módulo de autenticação está em src/modules/auth/ e consiste em:
[...]

> Adicione suporte a refresh token

Execução Headless (CI/CD)

kiro --print "Analise os erros de lint e corrija automaticamente"

O agente executa sem interação — perfeito para pipelines.

Custom Agents

Crie agentes especializados em .kiro/agents/:

# .kiro/agents/security-reviewer.yaml
name: security-reviewer
description: Revisa código para problemas de segurança
allowedTools:
  - read_file
  - search_files
  - analyze_code
systemPrompt: |
  Você é um especialista em segurança de aplicações.
  Analise código buscando:
  - SQL injection
  - XSS
  - Credenciais hardcoded
  - Validação de input insuficiente

Use com:

kiro chat --agent security-reviewer

Parte 6: Otimização de Créditos

Use o Modo Auto

O modo Auto (padrão) roteia automaticamente para o modelo mais eficiente para cada tarefa. Se você forçar Claude Opus em vez de Auto, o custo sobe significativamente.

Hooks São Gratuitos

Mova automações recorrentes para hooks em vez de fazer manualmente. Lint, formatação, atualização de docs — tudo isso pode ser hook.

Specs Economizam Retrabalho

O investimento de créditos em specs se paga quando você evita 3-4 ciclos de “não era isso que eu queria”.

Free Tier: 50 Créditos

O tier gratuito é apertado para uso intensivo de specs. Para trabalho real, considere o Pro ($20/mês com 1.000 créditos).

Dica: Uma interação simples pode consumir menos de 1 crédito (mínimo 0,01). Specs completas consomem mais.

Próximos Passos

Agora você tem:

  • Kiro IDE e CLI instalados
  • Seu primeiro projeto com specs
  • Steering files configurados
  • Hooks automatizando tarefas

Para aprofundar:

Se você precisa de ajuda para configurar Kiro no seu time ou criar workflows customizados, conheça os serviços de consultoria em ft.ia.br.

Tutorial verificado em julho de 2026. Versões: Kiro IDE 0.7+, Kiro CLI 1.24+.