Governança com IA em escala: steering, hooks e controles enterprise no Kiro

TL;DR

Steering transforma padrões da empresa em contexto versionado que viaja com o repo — inclusive AGENTS.md e referências a arquivos vivos via #[[file:]].
Hooks PreToolUse com exit code 2 bloqueiam ações perigosas (ex.: vazamento de segredo) antes de executarem — não é aviso, é barreira.
Custom agents aplicam least privilege: tools define o que existe, allowedTools define o que roda sem aprovação, e includeMcpJson: false corta o acesso a MCP não declarado.
Controles enterprise: SSO SAML/SCIM via AWS IAM Identity Center, billing consolidado, analytics, dashboard org e governança de API keys para uso headless.
GovCloud (US) existe, mas custa ~20% mais e não tem free tier.

O problema real não é a IA — é a escala

Colocar IA para escrever código na sua máquina é fácil. Você aceita ou rejeita cada sugestão, conhece o codebase, sabe o que é seguro. O risco é seu, o contexto é seu, o julgamento é seu.

Agora multiplique isso por 200 desenvolvedores, cada um com um estilo, alguns com pressa, todos com acesso a ferramentas que executam shell, escrevem arquivos e chamam servidores externos. De repente, “a IA fez” deixa de ser uma anedota divertida e vira uma pergunta de auditoria: quem autorizou essa ação? contra qual padrão? com quais permissões? dá para provar?

Governança de IA não é sobre desconfiar da IA. É sobre tornar o comportamento correto o caminho de menor resistência — e o comportamento perigoso, impossível.

O Kiro trata isso em três camadas que se reforçam: steering (o padrão que a IA sempre carrega), hooks (as barreiras que ela não consegue atravessar) e custom agents + controles de conta (quem pode fazer o quê, e como isso é cobrado e auditado). Vamos por partes.

Steering como padrão que viaja com o repo

O primeiro erro de quem adota IA em time é achar que “prompt bom” resolve. Prompt não escala: ele mora na cabeça (ou no histórico) de uma pessoa. O que escala é contexto versionado no repositório.

Steering são arquivos Markdown com front matter YAML que o Kiro injeta no contexto do agente segundo regras que você define. Ficam em dois lugares:

Workspace: .kiro/steering/*.md — viaja com o repo, é revisado em PR, vale para todo o time (isto é o “team steering”).
Global: ~/.kiro/steering/ — preferências pessoais do desenvolvedor, não commitadas.

A distinção importa para governança: o que é padrão da empresa vive no workspace e passa por code review; o que é gosto individual fica no global. Um novo dev que clona o repo já herda os padrões do time no primeiro kiro — sem onboarding manual, sem “ah, esqueci de te falar”.

O front matter precisa ser a primeira coisa do arquivo (sem linha em branco antes) e controla quando aquele steering entra em cena:

---
inclusion: fileMatch
fileMatchPattern: ["**/*.ts", "**/*.tsx"]
---
# Convenções de TypeScript

- TypeScript strict. Proibido `any` — use `unknown` + narrowing.
- Erros nunca são engolidos: sempre logar com correlação (requestId).
- Toda função pública exportada tem teste em Vitest. Cobertura mínima 80% em `src/domain`.
- Chamadas HTTP externas passam pelo cliente central em `src/lib/http` (retry + timeout).

Os modos de inclusion são a alavanca de governança fina:

Modo	Quando entra no contexto	Uso típico
`always`	Sempre	Padrões inegociáveis (segurança, stack)
`fileMatch`	Quando um arquivo casa com o padrão	Regras por tecnologia/pasta
`manual`	Só quando referenciado com `#nome` no chat	Playbooks pontuais
`auto`	Modelo decide via `name`/`description`	Guias contextuais

Além dos arquivos fundacionais que times costumam manter (product.md, tech.md, structure.md), o Kiro suporta o padrão aberto AGENTS.md. Ele é sempre incluído (não tem inclusion mode) e pode ficar na raiz do workspace ou em ~/.kiro/steering/. É o lugar natural para as regras que valem para qualquer agente que tocar naquele repositório.

O detalhe que fecha o loop de governança é a referência a arquivos vivos:

---
inclusion: always
---
# Contrato de API

A fonte de verdade da nossa API é o OpenAPI. Ao criar ou alterar endpoints,
respeite o schema abaixo — não invente campos.

#[[file:api/openapi.yaml]]

Toda mudança de contrato exige atualização do arquivo acima no mesmo PR.

Com #[[file:api/openapi.yaml]], o steering não descreve o contrato — ele aponta para o arquivo real. Quando o OpenAPI muda, o steering muda junto, sem cópia desatualizada. É a diferença entre uma regra que apodrece e uma regra que acompanha o código.

Hooks que impõem qualidade e segurança

Steering orienta. Hooks impõem. Essa é a distinção que separa “boa intenção” de “controle”.

Hooks são automações disparadas por evento, definidas em JSON no workspace (.kiro/hooks/*.json) ou por usuário (~/.kiro/hooks/). Cada hook tem name, trigger, action (obrigatórios) e opcionalmente matcher (regex que filtra por nome de tool ou caminho), timeout e enabled.

O ponto crítico de governança está em quais triggers podem bloquear. Nem todos podem — e isso é intencional:

Trigger	Momento	Bloqueia?
`PreToolUse`	Antes de uma tool rodar	✅ Sim
`PreTaskExec`	Antes de executar uma task de spec	✅ Sim
`UserPromptSubmit`	Ao enviar um prompt	✅ Sim
`PostToolUse` / `PostFileSave` / `Stop` / etc.	Depois do fato	❌ Não

A regra dos exit codes de uma action do tipo command é o mecanismo de barreira:

0 → sucesso (em SessionStart/UserPromptSubmit, o STDOUT vai para o contexto).
2 → bloqueia — mas só nos triggers Pre* e UserPromptSubmit. O STDERR volta ao agente explicando o motivo.
Qualquer outro → apenas aviso; a execução segue.

Ou seja: um hook PostFileSave que retorna 2 não impede nada (o arquivo já foi salvo). Para realmente barrar, você precisa de um trigger Pre*. Este é o exemplo canônico — varrer segredos antes de qualquer comando de shell rodar:

{
  "version": "v1",
  "hooks": [
    {
      "name": "block-secrets",
      "description": "Bloqueia comandos de shell que exponham segredos",
      "trigger": "PreToolUse",
      "matcher": "execute_bash",
      "action": { "type": "command", "command": "./scripts/scan-secrets.sh" }
    }
  ]
}

O matcher execute_bash faz o hook rodar antes de toda invocação da tool de shell. O scan-secrets.sh inspeciona o comando proposto; se detectar uma AWS access key, um token, um .env sendo catado para um destino externo — ele escreve o motivo em STDERR e sai com código 2. O Kiro cancela a execução e devolve o STDERR ao agente, que aprende por que foi barrado e tenta outro caminho.

Repare no encadeamento com o steering: a regra “nunca commite segredos” pode estar num AGENTS.md, mas é o hook PreToolUse que a torna inviolável. Orientação + barreira. Um sem o outro é frágil.

Hooks também servem para qualidade contínua, sem bloquear. Um PostFileSave que roda o linter em cada .ts salvo pelo agente mantém o padrão do steering vivo na prática:

{
  "version": "v1",
  "hooks": [
    {
      "name": "lint-on-save",
      "description": "Roda o linter quando um .ts é salvo pelo agente",
      "trigger": "PostFileSave",
      "matcher": "\\.ts$",
      "action": { "type": "command", "command": "npm run lint" },
      "timeout": 30,
      "enabled": true
    }
  ]
}

A pergunta de governança não é “a IA vai seguir a regra?”. É “a regra é executável?”. Se a resposta for não, você tem um wiki, não um controle.

Least privilege com agentes

A terceira camada responde: qual agente pode fazer o quê? No Kiro CLI, custom agents são definidos em JSON (.kiro/agents/ no workspace ou ~/.kiro/agents/ global) e implementam least privilege de forma explícita.

A distinção mais importante — e a mais mal compreendida — é entre tools e allowedTools:

tools = o conjunto de ferramentas que existem para esse agente.
allowedTools = o subconjunto que roda sem pedir aprovação. Tudo o que está em tools mas fora de allowedTools exige confirmação humana a cada uso.

{
  "name": "backend-specialist",
  "description": "Especialista em backend Node/TS. Só lê e escreve em src/.",
  "tools": ["read", "write", "execute_bash"],
  "allowedTools": ["read"],
  "resources": [
    "file://README.md",
    "file://.kiro/steering/**/*.md",
    "skill://.kiro/skills/**/SKILL.md"
  ],
  "prompt": "Você é um especialista em backend. Siga o steering do projeto. Nunca altere arquivos fora de src/.",
  "model": "claude-sonnet-4",
  "mcpServers": {
    "fetch": { "command": "fetch3.1", "args": [] }
  },
  "includeMcpJson": false
}

Neste agente, ler (read) é autônomo, mas escrever (write) e rodar shell (execute_bash) sempre param para pedir confirmação. O desenvolvedor mantém a mão no volante nas ações que mudam estado, enquanto a IA flui livre nas ações de leitura, que são inofensivas. É a materialização do princípio: automação onde o risco é baixo, humano no loop onde o risco é alto.

O campo resources reforça o cerco: o agente só enxerga o README.md, o steering do projeto e as skills declaradas — não o repositório inteiro. Menos superfície de contexto, menos chance de vazamento acidental e comportamento mais previsível.

E há um controle de segurança que muita gente passa batido: includeMcpJson: false. Por padrão, um agente herdaria os servidores MCP configurados no mcp.json do workspace/usuário. Com includeMcpJson: false, essa herança é cortada — o agente só acessa os servidores MCP declarados explicitamente no próprio mcpServers (aqui, apenas fetch).

Isso importa porque MCP é uma porta para o mundo externo: bancos de dados, APIs, sistemas internos. Um agente “backend-specialist” não tem motivo para falar com o servidor MCP de billing ou de produção. includeMcpJson: false garante que ele não fale — mesmo que aquele servidor esteja configurado na máquina do dev. Você declara a superfície de MCP por agente, em vez de dar a todos acesso a tudo.

Controles enterprise

As três camadas acima vivem no repositório e na máquina do dev. Mas governança de verdade precisa de controles no nível da conta e da organização. É o que o plano Team entrega, ancorado no AWS IAM Identity Center.

Identidade e provisionamento. SSO via SAML e provisionamento automático via SCIM, ambos pelo AWS IAM Identity Center. Isso significa que entrada e saída de pessoas na ferramenta seguem o mesmo source of truth de identidade do resto da sua stack AWS. Desligou no IdP, perdeu o acesso ao Kiro — sem conta órfã, sem licença esquecida.

Billing e visibilidade. Billing consolidado, analytics de uso e um dashboard organizacional dão ao gestor a resposta para “quanto estamos gastando, quem está usando e em quê”. Lembrando o modelo de créditos: crédito é unidade de trabalho (medido até 0,01), e modelos consomem em ritmos diferentes — uma tarefa que custa X no agente Auto custa 1,3X no Sonnet 4.6. Overage a US$ 0,04/crédito. Ter esse dado agregado no dashboard é o que permite gestão de custo real, não chute.

Governança de API keys (headless). Para CI/CD, o Kiro CLI roda headless autenticado por KIRO_API_KEY. A geração dessas chaves é privilégio de assinantes Pro/Pro+/Pro Max/Power, e o admin controla quem pode gerá-las. No pipeline, a chave entra como secret e o acesso a ferramentas é restrito por categoria:

name: Kiro Code Review
on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Kiro CLI
        run: curl -fsSL https://cli.kiro.dev/install | bash
      - name: Review PR changes
        env:
          KIRO_API_KEY: ${{ secrets.KIRO_API_KEY }}
        run: kiro-cli chat --no-interactive --trust-tools=read,grep "Revise as mudanças deste PR em busca de problemas de segurança"

Note o --trust-tools=read,grep: no ambiente headless não há humano para aprovar nada, então você concede apenas leitura e busca. É o mesmo princípio de least privilege dos custom agents, agora no pipeline. A alternativa --trust-all-tools existe, mas dar shell irrestrito a um agente sem supervisão em CI é justamente o que a governança deve evitar. E a boa notícia: a governança do admin (restrições de MCP, políticas de modelo, web fetch) também vale no headless — o pipeline não é uma porta dos fundos para escapar das regras.

GovCloud. Para cargas reguladas, existe o Kiro em AWS GovCloud (US). O trade-off é explícito: custa ~20% mais, não tem free tier e exige IAM Identity Center. Não é uma versão diferente do produto — é o mesmo Kiro num limite de conformidade mais rígido, com o preço da conformidade embutido.

Rastreabilidade para auditoria

Governança que não deixa rastro não sobrevive a uma auditoria. O bom é que, no modelo do Kiro, os controles já são os artefatos de auditoria — porque quase tudo vive como texto versionado:

Steering e hooks estão no Git. Cada mudança de padrão ou de barreira passa por PR: quem alterou, quando, com qual justificativa e quem aprovou. O histórico do .kiro/ é a trilha de auditoria da sua política de IA.
Custom agents são JSON versionado. O escopo de permissões de cada agente (tools, allowedTools, includeMcpJson) é revisável e diffável. “Quem deu shell irrestrito a esse agente?” é uma pergunta que o git blame responde.
Specs sincronizam intenção e código. No spec-driven development, requirements.md (em notação EARS), design.md e tasks.md mantêm o porquê e o como ao lado do código, sincronizados conforme ele evolui. A rastreabilidade requisito → design → tarefa → commit fica explícita, o que é ouro numa auditoria de conformidade.
Analytics e dashboard org cobrem o lado de consumo: uso por pessoa/time, gasto de créditos, adoção.

O princípio unificador: em vez de perguntar à ferramenta “o que a IA fez?”, você lê o repositório. Os controles não são logs escondidos num vendor — são arquivos que você já revisa. Isso reduz o custo de auditoria de “extrair relatório proprietário” para “ler o Git”.

Checklist de adoção enterprise

Acionável, na ordem em que eu faria:

Conclusão

Governança de IA em escala não se resolve com prompts melhores; resolve-se com contexto, barreiras e permissões versionados no repositório.
Steering faz o padrão da empresa viajar com o código (team steering no workspace, AGENTS.md, #[[file:]] para arquivos vivos).
Hooks PreToolUse com exit code 2 são a barreira executável — só triggers Pre* e UserPromptSubmit bloqueiam de fato.
Custom agents aplicam least privilege via tools vs allowedTools, e includeMcpJson: false fecha a porta de MCP não declarado.
Os controles enterprise (SSO SAML/SCIM no IAM Identity Center, billing consolidado, analytics, governança de API keys, GovCloud) fecham o loop no nível da organização.
E porque quase tudo é texto versionado, a trilha de auditoria já existe: você lê o Git, não um relatório proprietário.

Referências

Steering — documentação: https://kiro.dev/docs/steering/
Hooks — documentação: https://kiro.dev/docs/hooks/
Permissões e ferramentas: https://kiro.dev/docs/cli/chat/permissions/
Custom agents: https://kiro.dev/docs/cli/custom-agents/
Modo headless (governança de API key): https://kiro.dev/docs/cli/headless/
Kiro Enterprise: https://kiro.dev/enterprise/
Preços (times e GovCloud): https://kiro.dev/pricing/
Padrão AGENTS.md: https://agents.md/

Este artigo foi publicado originalmente no Medium. Preços, nomes de modelos e detalhes de produto refletem o estado do Kiro em meados de 2026 e podem mudar — confirme em kiro.dev antes de tomar decisões. Este é um conteúdo educacional independente, sem vínculo oficial com a AWS.

Tags: kiro, aws, governance, devsecops, enterprise

Publicado originalmente em prompt.victorbatistax.com. Se você chegou por outra plataforma, esta é a versão canônica.