Kiro Hooks: A Feature Gratuita Que Muda Tudo

Todo mundo fala de specs quando fala de Kiro. Faz sentido — é o grande diferencial. Mas tem uma feature que quase ninguém menciona e que pode mudar completamente como você trabalha: Hooks.

O detalhe absurdo: hooks são gratuitos. Não contam contra seus créditos do mês.

O Que São Hooks

Hooks são automações event-driven que disparam ações do agente quando eventos específicos ocorrem no seu projeto:

• Você salva um arquivo → o agente executa uma ação
• Você cria um arquivo novo → o agente executa outra ação
• Você deleta um arquivo → o agente reage
• Você dispara manualmente → o agente executa sob demanda

O agente tem acesso ao contexto do seu projeto (código, steering files, specs) e pode fazer qualquer coisa que faria numa conversa normal: editar arquivos, rodar comandos, analisar código.

A diferença: nenhum crédito é consumido.

Por Que Hooks São Gratuitos

Hooks executam tarefas previsíveis e repetitivas — lint, formatação, atualização de docs. O custo computacional é menor que conversas abertas, e a AWS optou por incluí-los como parte da proposta de valor do Kiro.

Pra times, isso muda a conta de ROI completamente. Você pode ter dezenas de automações rodando em cada save sem estourar o orçamento.

Eventos Disponíveis

No CLI, existem eventos adicionais:

• PreToolUse — antes do agente usar uma ferramenta
• PostToolUse — depois do agente usar uma ferramenta
• AgentSpawn — quando um subagent é criado
• AgentStop — quando um subagent termina

Como Configurar um Hook

No Kiro IDE

1. Pressione Cmd+Shift+K (ou Ctrl+Shift+K no Windows/Linux)
2. Selecione “New Hook”
3. Configure:
   • Nome: identificador único
   • Trigger: evento que dispara (On Save, On Create, etc.)
   • File Pattern: glob que define quais arquivos ativam o hook
   • Ação: descrição em linguagem natural do que fazer

Via Arquivo

Hooks ficam em .kiro/hooks/ como arquivos YAML ou Markdown:

# .kiro/hooks/auto-lint.yaml
name: auto-lint-typescript
trigger: on_save
pattern: "src/**/*.ts"
action: |
  Execute ESLint no arquivo salvo.
  Se houver erros que podem ser corrigidos automaticamente (--fix), corrija-os.
  Se houver erros que precisam de intervenção manual, liste-os como comentários TODO no início do arquivo.

10 Exemplos Práticos

1. Lint Automático em TypeScript

name: auto-lint-ts
trigger: on_save
pattern: "src/**/*.ts"
action: |
  Execute eslint --fix no arquivo.
  Se ainda houver erros após o fix, mostre-os no Problems panel.

Quando usar: Qualquer projeto TypeScript. Economiza o ciclo de “salvar → ver erro de lint → corrigir → salvar de novo”.

2. Type Check em Python

name: type-check-python
trigger: on_save
pattern: "**/*.py"
action: |
  Execute mypy no arquivo modificado.
  Se houver erros de tipo, adicione comentários # type: ignore com explicação apenas onde absolutamente necessário.
  Prefira corrigir o código a ignorar o erro.

Quando usar: Projetos Python com type hints. Pega erros de tipo no momento do save.

3. Atualizar Testes ao Modificar Código

name: update-tests
trigger: on_save
pattern: "src/modules/**/*.ts"
action: |
  Identifique o arquivo de teste correspondente em tests/.
  Se o arquivo de teste existe, analise as mudanças no código-fonte e atualize os testes para cobrir:
  - Novas funções ou métodos
  - Mudanças em assinaturas de função
  - Novos branches condicionais
  Se não existe arquivo de teste, crie um com cobertura básica.

Quando usar: Manter testes em sincronia com código sem esforço manual.

4. Atualizar Documentação de API

name: update-api-docs
trigger: on_save
pattern: "src/routes/**/*.ts"
action: |
  Analise os endpoints modificados.
  Atualize docs/api.md com:
  - Método HTTP e path
  - Parâmetros de entrada (query, body, path)
  - Formato de resposta
  - Exemplos de uso com curl
  Mantenha o estilo consistente com a documentação existente.

Quando usar: APIs REST. Docs sempre atualizadas com zero esforço.

5. Gerar Schema.yml para dbt

name: dbt-schema-gen
trigger: on_create
pattern: "models/**/*.sql"
action: |
  Analise o modelo SQL criado.
  Gere ou atualize o schema.yml correspondente com:
  - Nome do modelo
  - Descrição baseada no SQL
  - Colunas com tipos inferidos
  - Testes básicos (not_null, unique para PKs)

Quando usar: Projetos dbt. Economiza o trabalho tedioso de manter schema.yml.

6. Scan de Segurança Antes de Commit

name: security-scan
trigger: manual
action: |
  Analise todos os arquivos staged para commit.
  Procure por:
  - Credenciais hardcoded (API keys, passwords, tokens)
  - Conexões de banco sem SSL
  - Queries SQL vulneráveis a injection
  - Inputs de usuário não sanitizados
  Se encontrar problemas, liste-os com severidade e sugestão de correção.
  Não faça commit se houver problemas de severidade alta.

Quando usar: Antes de cada commit. Previne vazamento de credenciais.

7. Validar Conventional Commits

name: validate-commit-message
trigger: manual
action: |
  Analise a mensagem de commit proposta.
  Verifique se segue Conventional Commits:
  - Prefixo válido (feat, fix, docs, style, refactor, test, chore)
  - Escopo opcional entre parênteses
  - Descrição imperativa e concisa
  Se inválida, sugira uma mensagem corrigida.

Quando usar: Times que seguem Conventional Commits.

8. Atualizar Storybook ao Modificar Componente

name: update-storybook
trigger: on_save
pattern: "src/components/**/*.tsx"
action: |
  Se o componente modificado tem um arquivo .stories.tsx correspondente:
  - Verifique se todas as props estão representadas em stories
  - Adicione stories para novas variantes
  Se não tem .stories.tsx, crie um com stories básicas cobrindo:
  - Estado default
  - Estados de loading/error se aplicável
  - Variações de props principais

Quando usar: Projetos React/Vue com Storybook.

9. Estimativa de Custo CloudFormation

name: cfn-cost-estimate
trigger: on_save
pattern: "**/*.yaml"
condition: |
  Apenas se o arquivo contém AWSTemplateFormatVersion
action: |
  Analise os recursos definidos no template CloudFormation.
  Adicione um comentário no início do arquivo com estimativa mensal de custo:
  - Liste cada recurso e custo estimado
  - Some o total mensal
  - Avise sobre recursos sem tier gratuito
  Use preços da região us-east-1 como referência.

Quando usar: Projetos de infraestrutura AWS. Evita surpresas na fatura.

10. Notificação Slack em Deploy

name: deploy-notification
trigger: manual
action: |
  Colete informações do último deploy:
  - Branch/tag
  - Commits incluídos desde último deploy
  - Autor
  - Timestamp
  Formate como mensagem Slack e envie para o webhook configurado em .env (SLACK_WEBHOOK_URL).

Quando usar: Manter o time informado sobre deploys.

Hooks para Times

Hooks são arquivos em .kiro/hooks/ — versionados no Git. Quando você configura um hook, ele fica disponível para todo o time.

Isso cria consistência no automático:

• Mesmo padrão de lint pra todo mundo
• Mesmas verificações de segurança
• Mesma estrutura de documentação

Ninguém precisa lembrar de rodar lint ou atualizar docs. O hook faz por você.

Anti-Patterns: O Que Evitar

❌ Hooks que Demoram Muito

Hooks devem ser rápidos. Se seu hook demora 30 segundos para executar, você vai desabilitar depois de 3 saves.

Solução: Quebre em hooks menores ou use trigger manual para tarefas pesadas.

❌ Hooks que Modificam Muitos Arquivos

Um hook que modifica 50 arquivos em cada save é receita para conflitos de merge e confusão.

Solução: Mantenha hooks focados. Um hook, uma responsabilidade.

❌ Hooks Sem Padrão de Arquivo Específico

# Ruim
pattern: "**/*"

# Bom
pattern: "src/modules/**/*.ts"

Hooks muito amplos disparam em contextos errados e criam ruído.

❌ Hooks que Contradizem Steering Files

Se seu steering file diz “use async/await” e seu hook converte para callbacks, você tem um problema.

Solução: Alinhe hooks com steering files. Os dois são parte do mesmo contexto.

Hooks no CLI vs IDE

Os arquivos de hook são compatíveis entre os dois. Você pode criar no IDE e executar no CLI.

Perguntas Frequentes

Hooks realmente não consomem créditos?

Correto. Hooks são gratuitos em todos os planos, incluindo o Free.

Posso desabilitar um hook temporariamente?

Sim. No IDE, vá em Settings → Hooks e desabilite. No CLI, renomeie o arquivo para .disabled.yaml ou mova para fora da pasta.

Hooks funcionam com arquivos binários?

Não diretamente. O padrão de arquivo pode incluir binários, mas a ação do hook precisa fazer sentido para o contexto. Hooks são mais úteis para arquivos de texto.

Posso ter múltiplos hooks para o mesmo evento?

Sim. Todos os hooks que correspondem ao evento e padrão são executados.

Hooks podem falhar e bloquear o save?

Por padrão, não. Hooks executam em background. Se você quer comportamento de “gate” (bloquear se falhar), use hooks manuais antes de commit/deploy.

Próximos Passos

Agora que você entende hooks, explore outros recursos do Kiro:

• Como Usar o Kiro: Tutorial Completo
• Kiro CLI ou IDE: Quando Usar Cada Um
• GitHub Copilot ou Kiro?

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

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