Steering files no Kiro: como ensinar a IA a seguir os padrões do seu projeto

Steering files são arquivos Markdown que dão ao Kiro memória persistente sobre o seu projeto. Em vez de repetir contexto a cada nova conversa, você configura os steering files uma vez e o agente passa a entender e respeitar suas convenções, stack e padrões de código em toda interação, automaticamente.

Os steering files do Kiro ficam na pasta .kiro/steering/ do projeto, são versionados no Git e compartilhados com todo o time. A documentação oficial os descreve como a forma de dar ao Kiro “persistent knowledge about your workspace through markdown files.” Na prática, são a base que garante que o código gerado por IA siga os padrões do time, não os padrões genéricos do modelo.

O problema que os steering files resolvem

Quem usa qualquer ferramenta de IA para desenvolvimento conhece a frustração: a cada nova sessão, é necessário reexplicar o contexto do projeto, as convenções do time, o stack tecnológico, as regras de negócio. O agente não lembra do que foi dito ontem.

Sem steering files, o Kiro funciona, mas gera código genérico. Com steering files, o Kiro gera código que respeita a arquitetura existente, usa as bibliotecas certas e segue as convenções de nomenclatura do time. A diferença é entre um assistente genérico e um que conhece o projeto como um membro da equipe.

Como os steering files funcionam no Kiro

Quando você escreve um prompt, o agente recebe como contexto não apenas o prompt e o histórico da conversa, mas também o conteúdo dos steering files configurados. É como se um briefing completo do projeto fosse anexado a cada mensagem, de forma invisível.

Os steering files do Kiro têm dois escopos possíveis:

Workspace — arquivos em .kiro/steering/, aplicados apenas ao projeto atual. Usados para convenções, stack e regras específicas daquele codebase.

Global — arquivos em ~/.kiro/steering/, aplicados a todos os projetos do usuário. Usados para preferências pessoais de estilo de código, padrões de segurança ou convenções que valem para qualquer projeto.

Em caso de instruções conflitantes, o Kiro sempre prioriza as instruções do workspace sobre as globais. Dentro do workspace, instruções mais específicas têm prioridade sobre instruções gerais.

Três modos de inclusão

A documentação de steering define três modos de inclusão que determinam quando cada steering file é carregado:

Always — incluído em toda interação. Usado para os arquivos base (product.md, tech.md, structure.md) e qualquer convenção que deve valer sempre.

Auto — incluído automaticamente quando o Kiro detecta que o conteúdo é relevante para a tarefa atual, com base na descrição do arquivo. Ideal para guias de API, convenções de teste ou padrões específicos de um módulo.

Manual — incluído apenas quando o desenvolvedor chama explicitamente via slash command (/nome-do-arquivo) no chat. Útil para guias de troubleshooting, procedimentos de migração ou documentação pesada que só é necessária ocasionalmente.

Os três arquivos base gerados automaticamente

Ao executar Generate Steering Docs no painel do Kiro (ou via Command Palette: Cmd+Shift+P > “Kiro: Generate project steering documents”), três steering files são criados com base na análise automática do codebase:

product.md — descreve o produto: qual problema resolve, quem são os usuários, quais as funcionalidades principais. O Kiro infere essas informações do código existente e da estrutura do projeto. Isso ajuda o agente a entender o “porquê” por trás das decisões técnicas.

structure.md — documenta a organização do projeto: estrutura de diretórios, convenção de nomenclatura de arquivos, padrões de importação. Garante que o código gerado se encaixe na arquitetura existente.

tech.md — lista o stack tecnológico: linguagens, frameworks, bibliotecas, ferramentas de build e dependências. Evita que o Kiro sugira bibliotecas incompatíveis ou padrões divergentes do que o time já adota.

Esses três arquivos têm inclusão always por padrão, ou seja, são lidos pelo agente em toda interação.

Como criar steering files customizados

Além dos três arquivos base, você pode criar steering files para qualquer aspecto do projeto que precise de consistência. No painel do Kiro, clique no botão + na seção Steering e descreva o que quer documentar. Ou crie manualmente um arquivo .md na pasta .kiro/steering/.

Steering file de padrões de código

# coding-standards.md

## Convenções de nomenclatura
- Componentes React sempre em PascalCase
- Hooks customizados sempre iniciando com 'use'
- Constantes em UPPER_SNAKE_CASE

## Estrutura de componentes
- Props sempre tipadas com TypeScript interface
- Nunca usar 'any' — usar 'unknown' para tipos dinâmicos
- Exportar tipos junto com os componentes

## Tratamento de erros
- Sempre usar o ErrorBoundary customizado para componentes
- APIs nunca falham silenciosamente — sempre log + feedback ao usuário

Steering file para TDD

# tdd.md

## Ordem de desenvolvimento
- Sempre escreva o teste antes do código
- Testes devem falhar antes de passar

## Cobertura mínima
- Todo novo módulo: mínimo 80% de cobertura
- Funções críticas (pagamento, autenticação): 100%

## Nomenclatura de testes
- Padrão: should [comportamento esperado] when [condição]
- Ex: should throw error when user is not authenticated

Steering file de segurança

Outro steering file essencial para o Kiro é o de segurança, que evita que o agente gere código com vulnerabilidades conhecidas:

# security.md

## Credenciais
- Nunca escreva credenciais, tokens ou chaves de API no código
- Use variáveis de ambiente para todos os segredos

## Autenticação
- Todas as rotas privadas devem usar o middleware de autenticação existente
- Nunca reimplemente autenticação do zero

## Inputs
- Todo input do usuário deve ser validado e sanitizado
- Nunca construa queries SQL com concatenação de strings

Uma boa prática recomendada no blog da AWS sobre steering files é pedir ao Kiro para atualizar os steering files sempre que ele comete um erro. Assim, o conhecimento adquirido em uma sessão fica documentado para sessões futuras.

Boas práticas para gerenciar steering files no Kiro

Versione no Git. Steering files são parte do projeto. Faça commit junto com o código para que toda a equipe e o Kiro tenham acesso ao contexto atualizado.

Mantenha atualizados. Quando o projeto evolui, os steering files devem evoluir juntos. Considere criar um hook que lembre de atualizar o tech.md quando dependências forem adicionadas.

Seja específico. Quanto mais específico o steering file, melhor o comportamento do Kiro. Evite instruções vagas como “siga boas práticas” — prefira “use o padrão X para Y” com exemplos concretos.

Comece simples. Não tente documentar tudo de uma vez. Comece com os três arquivos base e vá adicionando customizados conforme os problemas aparecerem.

Nunca inclua segredos. A documentação oficial é explícita: nunca inclua chaves de API, senhas, credenciais de banco de dados, URLs internas sensíveis ou dados de clientes (PII) em steering files. Eles são versionados no Git e podem ser compartilhados.

Um domínio por arquivo. Mantenha cada steering file focado em um tópico: API design, testes, deploy, segurança. Arquivos longos e genéricos são menos eficazes que arquivos curtos e específicos.

| Especialista em Kiro

Precisa de steering files que realmente funcionam?

Mapeamos suas convenções e ensinamos o Kiro a codificar certo. Reduza revisões desde o primeiro commit.

Personalizar steering files com a UDS 🠖

Perguntas frequentes sobre steering files no Kiro

Steering files do Kiro funcionam no Kiro CLI?

Sim. O Kiro CLI lê os mesmos steering files da pasta .kiro/steering/. Se os arquivos estão versionados no Git, qualquer desenvolvedor que usar o Kiro (IDE ou CLI) no mesmo projeto terá acesso ao mesmo contexto. O Kiro também suporta o padrão AGENTS.md como formato alternativo de steering.

Quanto de conteúdo posso colocar em um steering file?

Não há limite técnico rígido, mas a recomendação da documentação oficial é manter cada arquivo focado em um domínio e ser específico. Steering files muito longos ou genéricos reduzem a eficácia do agente. Inclua o “porquê” das decisões, não apenas o “quê”: explique por que o time escolheu determinado padrão, com exemplos de código.

É possível ter instruções conflitantes entre steering files?

Sim, e o Kiro resolve o conflito com uma hierarquia clara: instruções do workspace (.kiro/steering/) sempre têm prioridade sobre as globais (~/.kiro/steering/). Dentro do workspace, instruções mais específicas tendem a prevalecer sobre instruções gerais.

Steering files afetam o consumo de créditos?

Não diretamente. Steering files são carregados como contexto, não como prompts adicionais. Eles aumentam levemente o tamanho do contexto enviado ao modelo, mas o impacto em créditos é negligível comparado ao benefício de gerar código correto na primeira tentativa.

Posso usar steering files para mudar o comportamento dos specs?

Sim. Por exemplo, criando um steering file specs.md com a instrução “sempre escreva testes antes do código”, você força o Kiro a gerar tarefas em ordem TDD no fluxo de spec-driven development. Steering files podem modificar o comportamento de specs, hooks e do chat.