Steering no Kiro: como registrar as convenções do seu repositório para o agente seguir

Steering é o conjunto de arquivos markdown que dá ao Kiro, a IA agêntica da AWS para desenvolvimento de software, o contexto permanente do projeto: o produto, a stack, a estrutura do repositório e as regras do time. Os arquivos ficam em .kiro/steering/, são versionados junto com o código e cada um declara, no front matter, quando deve entrar no contexto do agente. É o mecanismo que a documentação oficial descreve para que as convenções do projeto deixem de ser explicadas de novo a cada conversa.

Verificado contra a documentação de steering do Kiro na atualização de 15/10/2026, incluindo os modos de inclusão na Kiro CLI V3, disponível em acesso antecipado desde junho de 2026, segundo o changelog da CLI. Os modos suportados mudam entre versões da CLI: confira na versão instalada.

Steering e spec trabalham em camadas diferentes. A spec descreve o que construir em uma funcionalidade: requisitos, desenho e tarefas. O steering descreve como este time constrói qualquer funcionalidade: onde cada coisa mora, quais comandos validam o código, quais decisões já foram tomadas e por quê. Quando o steering está bem escrito, a spec fica mais curta, porque deixa de repetir o que vale para o projeto inteiro. Para a visão geral do produto e das superfícies, o ponto de partida é o guia do Kiro.

O que é steering e onde fica

A documentação define dois escopos e uma forma de distribuição para times:

• Workspace: .kiro/steering/ na raiz do projeto. Vale só para aquele repositório e viaja com ele no git. A página de configuração registra que o Kiro na web e no celular leem a configuração de projeto a partir do repositório clonado.
• Global: ~/.kiro/steering/ no diretório do usuário. Vale para todos os workspaces daquela pessoa. A sessão na web roda em sandbox na nuvem e não enxerga esse diretório local; para levar steering pessoal até lá, a documentação indica o upload pelo Configuration Sync.
• Time: o escopo global também serve para padrões corporativos. Segundo a documentação, os arquivos de time podem ser enviados às máquinas por soluções de MDM ou Group Policy, ou baixados de um repositório central para ~/.kiro/steering.

Os escopos são somados, não substituídos. Quando uma instrução global contradiz uma do workspace, o Kiro prioriza a do workspace. Isso permite uma regra geral para a empresa com exceção explícita em um repositório específico.

A decisão de onde registrar uma convenção tem um trade-off claro. O steering global distribuído alcança todos os repositórios de uma vez, mas não passa por revisão no repositório e não chega às sessões na web. O steering de workspace passa por pull request, tem histórico e vale em qualquer superfície que abra o repositório. A recomendação prática: convenção que depende do código fica no workspace; política transversal da empresa (idioma de commit, tratamento de segredo) fica no global distribuído e, se o time usa o Kiro na web, também no repositório.

Todo arquivo de steering começa pelo front matter YAML, que a documentação exige no início do arquivo, entre três hífens. Na prática, nada pode vir antes da primeira linha ---: nem título, nem comentário, nem linha em branco.

Os três arquivos de base: product.md, tech.md e structure.md

A documentação descreve três arquivos de fundação, incluídos por padrão em toda interação, que o IDE consegue gerar a partir da seção Steering do painel do Kiro. O arquivo gerado é um ponto de partida: ele registra o que está visível no código, e o que o time decidiu e não está escrito em lugar nenhum só entra quando alguém escreve.

• product.md: propósito do produto, quem usa, objetivos e as regras de negócio que atravessam o código. Fora dele: roadmap, metas comerciais e qualquer dado de cliente.
• tech.md: stack, versões, comandos de build e teste e restrições técnicas. Fora dele: tutorial da linguagem e regras que o linter já aplica.
• structure.md: organização das pastas, onde cada responsabilidade mora, convenções de nome e de import. Fora dele: a árvore completa do repositório, que o agente consegue ler sozinho.

Um tech.md para um serviço Node.js em AWS Lambda, com Amazon API Gateway e Amazon DynamoDB, fica assim:

---
inclusion: always
---

# Tecnologia: servico-cobrancas

## Stack
- Node.js 24 em AWS Lambda (runtime nodejs24.x, arquitetura arm64)
- TypeScript com "strict": true
- Entrada HTTP: Amazon API Gateway (HTTP API)
- Persistência: Amazon DynamoDB, uma tabela por serviço
- Credenciais: AWS Secrets Manager, lidas em tempo de execução
- Infraestrutura: Terraform, em infra/

## Comandos
- Instalar dependências: npm ci
- Testes unitários: npm test
- Lint e tipos: npm run lint && npm run typecheck
- Plano de infraestrutura: terraform -chdir=infra plan

## Restrições
- Dependência nova só com ADR aprovado em docs/adr/.
  Por quê: cada pacote amplia a superfície de ataque e o pacote da função;
  o ADR registra a alternativa avaliada e quem aprovou.
- Infraestrutura só em Terraform, nunca pelo console da AWS.
  Por quê: mudança feita no console não aparece no plan, não passa por
  revisão e é desfeita na próxima aplicação.
- AWS SDK for JavaScript v3, importando só o cliente usado
  (@aws-sdk/client-dynamodb). Por quê: o SDK v3 é modular e o import
  por cliente mantém o pacote da função enxuto.
- Nunca editar package-lock.json à mão.
  Por quê: o CI usa npm ci, que falha se lock e package.json divergirem.

Cada restrição traz o porquê. A documentação recomenda explicar o raciocínio por trás de cada padrão, e há um motivo operacional: diante de um caso que a regra não previu, o agente consegue aplicar a intenção, e o time consegue julgar se a regra ainda faz sentido quando o contexto mudar. A regra de infraestrutura conversa com o que detalhamos no post sobre Terraform na AWS.

O product.md segue a mesma lógica, com foco no domínio:

---
inclusion: always
---

# Produto: servico-cobrancas

## Propósito
Emite e concilia cobranças de assinatura para clientes B2B.
Quem usa: o time financeiro (painel interno) e o sistema de assinaturas (API).

## Regras de negócio que atravessam o código
- Valor monetário sempre em centavos, como inteiro, moeda BRL.
  Por quê: ponto flutuante gera diferença de centavo na conciliação.
- Cobrança emitida nunca é apagada; o cancelamento gera um novo evento.
  Por quê: a trilha de auditoria exige o histórico completo.

## Glossário
- Cobrança: valor a receber de um cliente em uma data.
- Conciliação: confronto entre a cobrança e o crédito recebido no banco.

Modos de inclusão: always, fileMatch, manual e auto

O modo de inclusão define quando um arquivo entra no contexto. Os blocos abaixo são os da documentação de steering. O primeiro, always, é o padrão:

# Carregado em toda interação (padrão)
---
inclusion: always
---

# Carregado só quando mencionado com #nome-do-arquivo no chat
---
inclusion: manual
---

O fileMatch carrega o arquivo quando o trabalho envolve arquivos que casam com o padrão. O campo aceita um padrão único ou uma lista:

# Padrão único
---
inclusion: fileMatch
fileMatchPattern: "components/**/*.tsx"
---

# Lista de padrões
---
inclusion: fileMatch
fileMatchPattern: ["**/*.ts", "**/*.tsx", "**/tsconfig.*.json"]
---

O auto exige name e description. O Kiro compara a descrição com a solicitação e carrega o arquivo quando ela é relevante:

---
inclusion: auto
name: api-design
description: REST API design patterns and conventions. Use when creating or modifying API endpoints.
---

Arquivos manual e auto também aparecem como comandos de barra no chat. No modo auto, a description é a chave de seleção: escreva quando usar o arquivo ("use ao criar ou alterar rotas, contratos ou códigos de erro"), e não o que ele contém ("convenções de API").

Duas observações da documentação mudam o desenho para times que usam mais de uma superfície. No Kiro CLI, a versão V3 suporta os quatro modos; nas versões V1 e V2, só os arquivos always são carregados automaticamente. E agentes personalizados não carregam steering por padrão: é preciso declarar os arquivos no campo resources da configuração do agente.

{
  "resources": ["file://.kiro/steering/**/*.md"]
}

A consequência prática: uma regra que não pode faltar em nenhuma superfície (segurança, por exemplo) fica em always, mesmo que pese no contexto.

Referências a arquivos vivos

O steering pode apontar para arquivos do workspace em vez de copiá-los. A sintaxe da documentação:

# Arquivo inteiro (todas as superfícies)
#[[file:<caminho_relativo>]]

# Uma linha ou um intervalo inclusivo (IDE e CLI V3)
#[[file:<caminho_relativo>:<linha>]]
#[[file:<caminho_relativo>:<inicio>-<fim>]]

# Listagem de uma pasta, um nível (IDE e CLI V3)
#[[folder:<pasta_relativa>]]

Um arquivo de desenho de API que aponta para o contrato e para a decisão de arquitetura, em vez de reproduzi-los:

---
inclusion: auto
name: api-design
description: Convenções da API HTTP do servico-cobrancas. Use ao criar ou alterar rotas, contratos, códigos de erro ou paginação.
---

# Desenho de API

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

Decisão sobre autenticação entre serviços:
#[[file:docs/adr/0004-autenticacao-entre-servicos.md]]

Limites de paginação usados no código:
#[[file:src/config/limites.ts:12-30]]

- Rota nova entra primeiro no openapi.yaml, depois no código.
- Erro no formato application/problem+json, com campo "code" estável.
- Paginação por cursor (nextToken), nunca por número de página.
  Por quê: o DynamoDB pagina por LastEvaluatedKey; deslocamento numérico
  obrigaria a ler e descartar itens a cada página.

O caminho é relativo à raiz do workspace no steering de workspace, a ~/.kiro/steering/ no steering global e à pasta do próprio arquivo no caso do AGENTS.md. As referências obedecem às permissões de leitura e às regras de ignorar arquivos da sessão. Se um arquivo referenciado for renomeado, o Kiro deixa um marcador visível de referência não resolvida, em vez de descartar a referência em silêncio.

O motivo para referenciar é ter uma fonte única. Um trecho do contrato copiado para o steering vira uma segunda versão da verdade, que diverge no primeiro pull request que altera só uma das duas. Com a referência, o agente lê o openapi.yaml do momento, e o marcador de referência quebrada torna visível o arquivo que ficou para trás. O cuidado é com o peso: referenciar um arquivo grande dentro de um steering always coloca esse arquivo inteiro em toda conversa. Referência pesada combina com auto ou fileMatch.

Steering, AGENTS.md e skills: quem faz o quê

O Kiro lê três tipos de instrução, com papéis distintos:

• AGENTS.md: padrão aberto de instruções para agentes de código, em markdown sem campos obrigatórios, mantido pela Agentic AI Foundation, sob a Linux Foundation, segundo o site do padrão. No Kiro, ele é sempre carregado e não aceita modos de inclusão. Vale no diretório global de steering, na raiz do workspace e em subdiretórios: um AGENTS.md em services/api/ e outro em packages/ui/ entram como contexto junto com o restante do steering.
• Skills: pacotes portáteis no padrão aberto Agent Skills, cada um com uma pasta e um SKILL.md, além de scripts, referências e modelos opcionais. Segundo a documentação de skills, o carregamento é progressivo: na inicialização o Kiro lê só o name e a description de cada skill, carrega as instruções completas quando a solicitação casa com a descrição e lê scripts e referências só quando as instruções pedem.
• Steering: contexto específico do Kiro que molda o comportamento do agente, com os quatro modos de inclusão. A própria documentação de skills o recomenda para padrões e convenções do projeto.

Um ponto de atenção sobre o AGENTS.md: o site do padrão descreve que o arquivo mais próximo do código editado prevalece, enquanto a documentação do Kiro descreve todos os AGENTS.md encontrados sendo carregados juntos como contexto. Para não depender de precedência, escreva o arquivo de subdiretório como complemento do da raiz, nunca como contradição.

Um conjunto de referência para um serviço na AWS

Para o serviço do exemplo, este é um conjunto que cobre o projeto sem pesar em toda conversa:

.kiro/steering/
├── product.md       always
├── tech.md          always
├── structure.md     always
├── seguranca.md     always
├── api-design.md    auto
├── testes.md        fileMatch: **/*.test.ts, test/**/*.ts
└── terraform.md     fileMatch: **/*.tf

O structure.md registra onde cada responsabilidade mora e a regra de dependência entre camadas:

---
inclusion: always
---

# Estrutura
- src/handlers/  um arquivo por rota; só traduz HTTP para o domínio
- src/domain/    regras de negócio puras, sem import do AWS SDK
- src/adapters/  acesso a DynamoDB, Secrets Manager e serviços externos
- infra/         Terraform do serviço
- docs/adr/      decisões de arquitetura numeradas (0001-titulo.md)

- domain/ nunca importa de adapters/.
  Por quê: a regra de negócio fica testável sem simular a AWS e a
  persistência pode mudar sem reescrever o domínio.
- Arquivos em kebab-case; classes e tipos em PascalCase.

O seguranca.md fica em always porque vale em qualquer tarefa e em qualquer superfície:

---
inclusion: always
---

# Segurança
- Nenhum segredo no código, em teste, em exemplo ou em steering.
  Credencial vem do AWS Secrets Manager em tempo de execução.
- Política IAM com privilégio mínimo: ações e recursos explícitos, por ARN.
  Curinga (*) só com justificativa registrada em ADR.
- Dado pessoal (nome, CPF, e-mail, telefone) nunca vai para log.
  Log estruturado em JSON, com id de correlação no lugar do dado.
  Por quê: log é replicado, retido e lido por mais gente que o banco.
- Entrada externa validada no handler, antes de chegar ao domínio.

As três regras têm base documentada: o AWS Secrets Manager existe para tirar credencial do código, as boas práticas do IAM recomendam conceder o privilégio mínimo, e o tratamento de dado pessoal em log é parte do desenho de LGPD que descrevemos em LGPD na cloud. O desenho de permissão por ARN está detalhado no post sobre IAM e zero trust.

Os arquivos condicionais carregam o detalhe que só importa quando o tipo de arquivo está em jogo:

---
inclusion: fileMatch
fileMatchPattern: ["**/*.test.ts", "test/**/*.ts"]
---

# Testes
- Teste de domínio não toca a AWS: entrada e saída puras.
- Teste de adaptador roda contra o DynamoDB Local (npm run test:integracao).
- O nome do teste descreve o comportamento: "rejeita cobrança com valor negativo".
- Bug corrigido ganha primeiro o teste que o reproduz, depois a correção.
  Por quê: prova que o teste detecta o defeito antes de a correção existir.

# ---- arquivo separado: .kiro/steering/terraform.md ----

---
inclusion: fileMatch
fileMatchPattern: "**/*.tf"
---

# Terraform
- State remoto no backend S3 declarado em infra/backend.tf.
- Tags obrigatórias via default_tags no provider aws: servico, ambiente, dono.
  Por quê: a tag é a base para alocar custo por time.
- Módulo novo em modules/<nome>/ com main.tf, variables.tf e outputs.tf.
- Antes de propor mudança: terraform fmt e terraform validate.
- O agente propõe o código e mostra o plan; o apply é humano, pelo pipeline.

O DynamoDB Local é a versão para desenvolvimento que a AWS documenta para testar sem acessar o serviço. A regra de tags conversa com a alocação de custo que tratamos em FinOps na AWS, e a última linha do terraform.md registra uma decisão de arquitetura do processo: o agente escreve e explica, a aplicação em produção segue o caminho revisado.

Armadilhas e como evitar

• Steering longo demais em always. Cada linha ocupa contexto em toda conversa, inclusive nas que não têm relação com ela. Mitigação: always só para o que vale sempre; o resto vai para fileMatch, auto ou manual.
• Regras contraditórias entre global e workspace. O workspace prevalece no conflito, e quem lê só o arquivo global não percebe a exceção. Mitigação: exceção no workspace sempre explícita ("diferente do padrão da empresa, aqui usamos X, porque Y").
• Contradição entre AGENTS.md e steering. Os dois são carregados, e o agente recebe as duas versões. Mitigação: cada convenção em um lugar só; o outro arquivo, se precisar, aponta para ela.
• Segredo no steering. As boas práticas da documentação são diretas: nunca incluir chave de API, senha ou dado sensível. O arquivo é versionado com o código e entra no contexto do agente. Mitigação: o steering diz de onde ler a credencial, e a varredura de segredos do pipeline também cobre .kiro/.
• Regra sem porquê. Sem o raciocínio, o agente aplica a regra ao pé da letra no caso que ela não previu, e ninguém sabe se pode removê-la. Mitigação: toda restrição com uma linha "Por quê".
• Arquivo desatualizado. Steering que descreve uma arquitetura antiga orienta o agente para ela. Mitigação: referência a arquivo vivo no lugar de cópia, e revisão quando a arquitetura muda.
• Front matter fora do lugar. Um título ou uma linha em branco antes do --- descumpre a exigência de front matter no início do arquivo. Mitigação: revisar o topo de todo arquivo novo no pull request.
• Agente personalizado sem steering. Ele não carrega steering por padrão. Mitigação: o glob de resources faz parte do modelo de agente do time.

As boas práticas oficiais resumem a disciplina: um domínio por arquivo, nomes descritivos, o porquê de cada decisão, exemplos junto das regras e mudança de steering tratada como mudança de código, com revisão. Para os nomes, a seção de estratégias comuns da documentação sugere arquivos como api-standards.md, testing-standards.md e security-policies.md.

Como manter o steering vivo

Steering é código que orienta o agente de todo o time, então merece o mesmo processo de qualquer código compartilhado. Três mecanismos sustentam isso.

Dono por arquivo. O arquivo CODEOWNERS do GitHub faz com que os donos sejam chamados automaticamente para revisar pull requests que alteram o que é deles. Combinado com a regra de proteção de branch que exige revisão de code owner, nenhuma convenção muda sem quem responde por ela:

# A última regra que casa com o arquivo prevalece
/.kiro/                        @sua-org/arquitetura
/AGENTS.md                     @sua-org/arquitetura
/.kiro/steering/seguranca.md   @sua-org/seguranca
/.kiro/steering/terraform.md   @sua-org/plataforma

Revisão a cada mudança de arquitetura. Quando um ADR é aceito, as regras que derivam dele entram no steering no mesmo pull request. A documentação recomenda revisar o steering no planejamento da sprint e nas mudanças de arquitetura; amarrar isso ao ADR transforma a recomendação em rotina.

O próprio agente pode redigir a proposta, desde que a solicitação limite o escopo e deixe a decisão com quem revisa:

Leia docs/adr/0007-filas-com-sqs.md, que foi aceito.
Compare com os arquivos em .kiro/steering/ e com o AGENTS.md da raiz.

1. Liste as regras que derivam deste ADR e ainda não estão no steering.
2. Para cada regra, indique o arquivo de destino e o modo de inclusão
   (always, fileMatch ou auto), justificando a escolha.
3. Proponha o texto de cada regra com uma linha "Por quê" que cite o ADR.
4. Aponte regras atuais que este ADR contradiz ou torna obsoletas.

Não edite nenhum arquivo. Mostre a proposta para revisão.

A última linha separa a redação da decisão: a proposta volta como texto, o time ajusta e a alteração entra pelo pull request do ADR, com o dono do arquivo na revisão.

Confirmação de que o steering foi carregado. No Kiro CLI, o comando /context show lista os arquivos em contexto em duas seções, Agent (os recursos persistentes do agente, como o glob de steering) e Session (o que foi adicionado na sessão), com a fração da janela de contexto que eles ocupam, segundo a documentação de contexto do CLI:

/context show

A mesma página registra que os arquivos de contexto são limitados a 75% da janela de contexto do modelo e que o excedente é descartado, o que reforça a disciplina de manter always enxuto. Em qualquer superfície, um teste de comportamento complementa a listagem: pergunte ao agente algo que só o steering responde (por exemplo, "qual é a regra de paginação desta API e de qual arquivo ela vem?") e confira se a resposta cita a regra e o arquivo certos. Resposta genérica indica arquivo fora do contexto, modo de inclusão que não disparou ou description imprecisa no modo auto.

Pergunta no checklist de PR. O modelo de pull request do repositório traz a pergunta que evita o steering desatualizado:

## Convenções do agente
- [ ] Isto muda alguma convenção registrada em .kiro/steering/ ou em AGENTS.md?
- [ ] Se sim, o arquivo de steering foi atualizado neste mesmo PR.
- [ ] Se um ADR foi aceito, as regras derivadas dele entraram no steering.
- [ ] Nenhum segredo, chave ou dado pessoal foi incluído em .kiro/.

Com dono, gatilho e checklist, o steering acompanha o código na mesma velocidade, e a convenção que o agente segue é a mesma que o time revisou.

Para levar o Kiro a vários times, com steering, specs e governança desenhados para a sua operação na AWS, conheça a adoção do Kiro com a RFX.

Perguntas frequentes

O que é steering no Kiro?

É o conjunto de arquivos markdown que dá ao Kiro, a IA agêntica da AWS para desenvolvimento de software, o contexto permanente do projeto: produto, stack, estrutura do repositório e regras do time. Cada arquivo declara no front matter YAML quando deve ser carregado (always, fileMatch, manual ou auto), e a documentação oficial trata esses arquivos como parte do código do projeto.

Onde ficam os arquivos de steering do Kiro?

Em .kiro/steering/ na raiz do projeto (escopo de workspace) e em ~/.kiro/steering/ no diretório do usuário (escopo global). Os dois escopos são somados; em instrução conflitante, o workspace prevalece. Arquivos de time podem ser distribuídos para o diretório global por MDM, Group Policy ou download de um repositório central.

Qual a diferença entre steering e AGENTS.md no Kiro?

O AGENTS.md é um padrão aberto de instruções para agentes de código. No Kiro ele é sempre carregado, não aceita modos de inclusão e também é lido em subdiretórios do workspace. O steering é específico do Kiro e permite carregar cada arquivo só quando ele é relevante, por padrão de arquivo, por descrição ou por menção no chat.

Quando usar fileMatch, auto ou manual no steering?

Use fileMatch para convenções de um tipo de arquivo (testes, Terraform, componentes de interface), auto para convenções de um tipo de tarefa descrito em linguagem natural (desenho de API) e manual para material extenso e pontual, puxado com #nome no chat. Reserve always para regras curtas que valem em toda interação.

Posso colocar chaves ou senhas em um arquivo de steering?

Não. As boas práticas da documentação do Kiro orientam a nunca incluir chaves de API, senhas ou dados sensíveis em steering. O arquivo é versionado com o código e entra no contexto do agente. Credenciais ficam em um cofre como o AWS Secrets Manager, e o steering descreve apenas de onde o código deve lê-las.

O Kiro CLI carrega todos os modos de inclusão?

Segundo a documentação oficial, o Kiro CLI V3 suporta os quatro modos (always, fileMatch, manual e auto). Nas versões V1 e V2, só os arquivos marcados como always são carregados automaticamente. Agentes personalizados não carregam steering por padrão: é preciso declarar os arquivos no campo resources da configuração do agente.

Sobre o autor

Rodrigo Araújo

Arquiteto de Soluções, IA e Cloud | RFX Tecnologia

Arquiteto de Soluções, IA e Cloud na RFX Tecnologia, lidera projetos de migração, FinOps e IA aplicada na nuvem para empresas do Nordeste e de todo o Brasil. É também o idealizador da Jornada de Inovação AWS em João Pessoa, encontro que aproxima donos de negócio da região das aplicações reais de cloud e inteligência artificial.