# 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.

Source: https://agentify.ia.br/blog/como-usar-kiro-tutorial-completo/

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

- Instalar Kiro IDE e CLI

- Configurar autenticação

- Criar seu primeiro projeto com specs

- Configurar steering files para sua stack

- Usar hooks para automação gratuita

- Otimizar uso de créditos

## Parte 1: Instalação

### Kiro IDE (macOS, Windows, Linux)

**macOS:**

- Acesse [kiro.dev/downloads](https://kiro.dev/downloads)

- Baixe o `.dmg`

- Arraste para Applications

- Na primeira execução, clique com botão direito → Abrir (contornar Gatekeeper)

- Faça login com AWS Builder ID, Google ou GitHub

**Windows:**

- Baixe o `.exe` de kiro.dev

- Execute o instalador (permissões de admin)

- Kiro adiciona-se ao PATH automaticamente

- 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:

- [Kiro CLI ou IDE: Quando Usar Cada Um](/comparativos/kiro-cli-ou-ide-diferencas/)

- [Kiro Hooks: A Feature Gratuita Que Muda Tudo](/guias/kiro-hooks-automacao-gratuita/)

- [GitHub Copilot ou Kiro?](/comparativos/github-copilot-ou-kiro-comparativo/)

---

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](https://ft.ia.br).

---

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

-->