{"id":22770,"date":"2026-04-17T10:00:00","date_gmt":"2026-04-17T13:00:00","guid":{"rendered":"https:\/\/uds.com.br\/blog\/?p=22770"},"modified":"2026-04-06T18:06:43","modified_gmt":"2026-04-06T21:06:43","slug":"kiro-steering-files-configuracao","status":"publish","type":"post","link":"https:\/\/uds.com.br\/blog\/kiro-steering-files-configuracao\/","title":{"rendered":"Steering files no Kiro: como ensinar a IA a seguir os padr\u00f5es do seu projeto"},"content":{"rendered":"\n

Steering files s\u00e3o arquivos Markdown que d\u00e3o ao Kiro mem\u00f3ria persistente sobre o seu projeto. Em vez de repetir contexto a cada nova conversa, voc\u00ea configura os steering files uma vez e o agente passa a entender e respeitar suas conven\u00e7\u00f5es, stack e padr\u00f5es de c\u00f3digo em toda intera\u00e7\u00e3o, automaticamente.<\/p>\n\n\n\n

Os steering files do Kiro ficam na pasta .kiro\/steering\/<\/code> do projeto, s\u00e3o versionados no Git e compartilhados com todo o time. A documenta\u00e7\u00e3o oficial<\/a> os descreve como a forma de dar ao Kiro “persistent knowledge about your workspace through markdown files.” Na pr\u00e1tica, s\u00e3o a base que garante que o c\u00f3digo gerado por IA siga os padr\u00f5es do time, n\u00e3o os padr\u00f5es gen\u00e9ricos do modelo.<\/p>\n\n\n\n

O problema que os steering files resolvem<\/strong><\/h2>\n\n\n\n

Quem usa qualquer ferramenta de IA para desenvolvimento conhece a frustra\u00e7\u00e3o: a cada nova sess\u00e3o, \u00e9 necess\u00e1rio reexplicar o contexto do projeto, as conven\u00e7\u00f5es do time, o stack tecnol\u00f3gico, as regras de neg\u00f3cio. O agente n\u00e3o lembra do que foi dito ontem.<\/p>\n\n\n\n

Sem steering files, o Kiro funciona, mas gera c\u00f3digo gen\u00e9rico. Com steering files, o Kiro gera c\u00f3digo que respeita a arquitetura existente, usa as bibliotecas certas e segue as conven\u00e7\u00f5es de nomenclatura do time. A diferen\u00e7a \u00e9 entre um assistente gen\u00e9rico e um que conhece o projeto como um membro da equipe.<\/p>\n\n\n\n

Como os steering files funcionam no Kiro<\/strong><\/h2>\n\n\n\n

Quando voc\u00ea escreve um prompt, o agente recebe como contexto n\u00e3o apenas o prompt e o hist\u00f3rico da conversa, mas tamb\u00e9m o conte\u00fado dos steering files configurados. \u00c9 como se um briefing completo do projeto fosse anexado a cada mensagem, de forma invis\u00edvel.<\/p>\n\n\n\n

Os steering files do Kiro t\u00eam dois escopos poss\u00edveis:<\/p>\n\n\n\n

Workspace<\/strong> \u2014 arquivos em .kiro\/steering\/<\/code>, aplicados apenas ao projeto atual. Usados para conven\u00e7\u00f5es, stack e regras espec\u00edficas daquele codebase.<\/p>\n\n\n\n

Global<\/strong> \u2014 arquivos em ~\/.kiro\/steering\/<\/code>, aplicados a todos os projetos do usu\u00e1rio. Usados para prefer\u00eancias pessoais de estilo de c\u00f3digo, padr\u00f5es de seguran\u00e7a ou conven\u00e7\u00f5es que valem para qualquer projeto.<\/p>\n\n\n\n

Em caso de instru\u00e7\u00f5es conflitantes, o Kiro sempre prioriza as instru\u00e7\u00f5es do workspace sobre as globais. Dentro do workspace, instru\u00e7\u00f5es mais espec\u00edficas t\u00eam prioridade sobre instru\u00e7\u00f5es gerais.<\/p>\n\n\n\n

Tr\u00eas modos de inclus\u00e3o<\/strong><\/h3>\n\n\n\n

A documenta\u00e7\u00e3o de steering<\/a> define tr\u00eas modos de inclus\u00e3o que determinam quando cada steering file \u00e9 carregado:<\/p>\n\n\n\n

Always<\/strong> \u2014 inclu\u00eddo em toda intera\u00e7\u00e3o. Usado para os arquivos base (product.md, tech.md, structure.md) e qualquer conven\u00e7\u00e3o que deve valer sempre.<\/p>\n\n\n\n

Auto<\/strong> \u2014 inclu\u00eddo automaticamente quando o Kiro detecta que o conte\u00fado \u00e9 relevante para a tarefa atual, com base na descri\u00e7\u00e3o do arquivo. Ideal para guias de API, conven\u00e7\u00f5es de teste ou padr\u00f5es espec\u00edficos de um m\u00f3dulo.<\/p>\n\n\n\n

Manual<\/strong> \u2014 inclu\u00eddo apenas quando o desenvolvedor chama explicitamente via slash command (\/nome-do-arquivo<\/code>) no chat. \u00datil para guias de troubleshooting, procedimentos de migra\u00e7\u00e3o ou documenta\u00e7\u00e3o pesada que s\u00f3 \u00e9 necess\u00e1ria ocasionalmente.<\/p>\n\n\n\n

Os tr\u00eas arquivos base gerados automaticamente<\/strong><\/h2>\n\n\n\n

Ao executar Generate Steering Docs<\/strong> no painel do Kiro (ou via Command Palette: Cmd+Shift+P<\/code> > “Kiro: Generate project steering documents”), tr\u00eas steering files s\u00e3o criados com base na an\u00e1lise autom\u00e1tica do codebase:<\/p>\n\n\n\n

product.md<\/strong> \u2014 descreve o produto: qual problema resolve, quem s\u00e3o os usu\u00e1rios, quais as funcionalidades principais. O Kiro infere essas informa\u00e7\u00f5es do c\u00f3digo existente e da estrutura do projeto. Isso ajuda o agente a entender o “porqu\u00ea” por tr\u00e1s das decis\u00f5es t\u00e9cnicas.<\/p>\n\n\n\n

structure.md<\/strong> \u2014 documenta a organiza\u00e7\u00e3o do projeto: estrutura de diret\u00f3rios, conven\u00e7\u00e3o de nomenclatura de arquivos, padr\u00f5es de importa\u00e7\u00e3o. Garante que o c\u00f3digo gerado se encaixe na arquitetura existente.<\/p>\n\n\n\n

tech.md<\/strong> \u2014 lista o stack tecnol\u00f3gico: linguagens, frameworks, bibliotecas, ferramentas de build e depend\u00eancias. Evita que o Kiro sugira bibliotecas incompat\u00edveis ou padr\u00f5es divergentes do que o time j\u00e1 adota.<\/p>\n\n\n\n

Esses tr\u00eas arquivos t\u00eam inclus\u00e3o always<\/strong> por padr\u00e3o, ou seja, s\u00e3o lidos pelo agente em toda intera\u00e7\u00e3o.<\/p>\n\n\n\n

Como criar steering files customizados<\/strong><\/h2>\n\n\n\n

Al\u00e9m dos tr\u00eas arquivos base, voc\u00ea pode criar steering files para qualquer aspecto do projeto que precise de consist\u00eancia. No painel do Kiro, clique no bot\u00e3o +<\/strong> na se\u00e7\u00e3o Steering e descreva o que quer documentar. Ou crie manualmente um arquivo .md<\/code> na pasta .kiro\/steering\/<\/code>.<\/p>\n\n\n\n

Steering file de padr\u00f5es de c\u00f3digo<\/strong><\/h3>\n\n\n\n
# coding-standards.md<\/strong>\r\n\r\n## Conven\u00e7\u00f5es de nomenclatura<\/strong>\r\n- Componentes React sempre em PascalCase\r\n- Hooks customizados sempre iniciando com 'use'\r\n- Constantes em UPPER_SNAKE_CASE\r\n\r\n## Estrutura de componentes<\/strong>\r\n- Props sempre tipadas com TypeScript interface\r\n- Nunca usar 'any' \u2014 usar 'unknown' para tipos din\u00e2micos\r\n- Exportar tipos junto com os componentes\r\n\r\n## Tratamento de erros<\/strong>\r\n- Sempre usar o ErrorBoundary customizado para componentes\r\n- APIs nunca falham silenciosamente \u2014 sempre log + feedback ao usu\u00e1rio<\/code><\/pre>\n\n\n\n
Steering file para TDD<\/strong><\/h3>\n\n\n\n
# tdd.md<\/strong>\r\n\r\n## Ordem de desenvolvimento<\/strong>\r\n- Sempre escreva o teste antes do c\u00f3digo\r\n- Testes devem falhar antes de passar\r\n\r\n## Cobertura m\u00ednima<\/strong>\r\n- Todo novo m\u00f3dulo: m\u00ednimo 80% de cobertura\r\n- Fun\u00e7\u00f5es cr\u00edticas (pagamento, autentica\u00e7\u00e3o): 100%\r\n\r\n## Nomenclatura de testes<\/strong>\r\n- Padr\u00e3o: should [comportamento esperado] when [condi\u00e7\u00e3o]\r\n- Ex: should throw error when user is not authenticated<\/code><\/pre>\n\n\n\n
Steering file de seguran\u00e7a<\/strong><\/h3>\n\n\n\n
Outro steering file essencial para o Kiro \u00e9 o de seguran\u00e7a, que evita que o agente gere c\u00f3digo com vulnerabilidades conhecidas:<\/p>\n\n\n\n
# security.md<\/strong>\r\n\r\n## Credenciais<\/strong>\r\n- Nunca escreva credenciais, tokens ou chaves de API no c\u00f3digo\r\n- Use vari\u00e1veis de ambiente para todos os segredos\r\n\r\n## Autentica\u00e7\u00e3o<\/strong>\r\n- Todas as rotas privadas devem usar o middleware de autentica\u00e7\u00e3o existente\r\n- Nunca reimplemente autentica\u00e7\u00e3o do zero\r\n\r\n## Inputs<\/strong>\r\n- Todo input do usu\u00e1rio deve ser validado e sanitizado\r\n- Nunca construa queries SQL com concatena\u00e7\u00e3o de strings<\/code><\/pre>\n\n\n\n
Uma boa pr\u00e1tica recomendada no blog da AWS sobre steering files<\/a> \u00e9 pedir ao Kiro para atualizar os steering files sempre que ele comete um erro. Assim, o conhecimento adquirido em uma sess\u00e3o fica documentado para sess\u00f5es futuras.<\/p>\n\n\n\n
Boas pr\u00e1ticas para gerenciar steering files no Kiro<\/strong><\/h2>\n\n\n\n
Versione no Git.<\/strong> Steering files s\u00e3o parte do projeto. Fa\u00e7a commit junto com o c\u00f3digo para que toda a equipe e o Kiro tenham acesso ao contexto atualizado.<\/p>\n\n\n\n
Mantenha atualizados.<\/strong> Quando o projeto evolui, os steering files devem evoluir juntos. Considere criar um hook<\/a> que lembre de atualizar o tech.md<\/code> quando depend\u00eancias forem adicionadas.<\/p>\n\n\n\n
Seja espec\u00edfico.<\/strong> Quanto mais espec\u00edfico o steering file, melhor o comportamento do Kiro. Evite instru\u00e7\u00f5es vagas como “siga boas pr\u00e1ticas” \u2014 prefira “use o padr\u00e3o X para Y” com exemplos concretos.<\/p>\n\n\n\n
Comece simples.<\/strong> N\u00e3o tente documentar tudo de uma vez. Comece com os tr\u00eas arquivos base e v\u00e1 adicionando customizados conforme os problemas aparecerem.<\/p>\n\n\n\n
Nunca inclua segredos.<\/strong> A documenta\u00e7\u00e3o oficial<\/a> \u00e9 expl\u00edcita: nunca inclua chaves de API, senhas, credenciais de banco de dados, URLs internas sens\u00edveis ou dados de clientes (PII) em steering files. Eles s\u00e3o versionados no Git e podem ser compartilhados.<\/p>\n\n\n\n
Um dom\u00ednio por arquivo.<\/strong> Mantenha cada steering file focado em um t\u00f3pico: API design, testes, deploy, seguran\u00e7a. Arquivos longos e gen\u00e9ricos s\u00e3o menos eficazes que arquivos curtos e espec\u00edficos.<\/p>\n\n\n\n
<\/div>\n\n\n\n\n\n