Faça a IA ler antes de editar um repositório grande e entregar só com revisão

## Leia primeiro as regras gerais e depois o guia da pasta onde vai trabalhar Mantenha o documento raiz focado em política rígida e roteamento; deixe que os guias específicos definam o fluxo de trabalho detalhado de cada área. Antes de trabalhar dentro de uma subárvore, leia o guia responsável por ela. ### Um só lugar para cada tipo de regra Política rígida, limites transversais e a definição de qual guia é responsável por quê ficam na raiz. Procedimentos específicos de tarefas ficam no guia específico, próximo ao código que regem. Não repita um fluxo de trabalho em dois lugares onde as cópias podem se desalinhar com o tempo. ### Referencie o código do jeito que o repositório usa Cite arquivos pelo caminho relativo ao repositório, não por um caminho absoluto ou da pasta pessoal, para que a referência signifique a mesma coisa para todo leitor. ## Procure uma biblioteca ou ferramenta pronta antes de criar a sua Antes de propor ou construir um sistema, recurso, ferramenta, integração ou automação personalizada, faça uma verificação rápida em busca de uma biblioteca, plugin ou plataforma gratuita já existente que resolva o problema de forma satisfatória. ### Prefira a opção comprovada Quando uma opção existente for adequada, use-a. Construa algo personalizado somente quando as alternativas forem inadequadas, caras demais, sem manutenção, inseguras, não conformes, ou quando o usuário tiver pedido explicitamente uma solução personalizada. ### Mantenha a verificação simples Isso é uma checagem rápida antes de começar, não uma tarefa de pesquisa. Não recomende um serviço pago a menos que o usuário tenha aprovado o gasto. ## Revise lendo quem chama, quem é chamado e os testes, não só o diff Correções, triagens e revisões precisam de alta confiança baseada em leitura, não em um palpite a partir da mudança visível. Uma revisão baseada só no diff não é suficiente. ### Leia toda a superfície antes de dar um veredito Antes de dizer que algo está bom, ruim, é a melhor correção ou tem prova suficiente, leia toda a função ou módulo alterado, além de quem o chama, o que ele chama, implementações irmãs, testes relacionados, documentação específica e os contratos de tudo o que ele depende. ### Monte um pequeno mapa de evidências Identifique a superfície alterada, seu ponto de entrada, o limite de responsabilidade, ao menos um chamador e um chamado, superfícies irmãs que compartilham o mesmo invariante, testes existentes e o comportamento atualmente em produção. Se faltar algum desses pontos, aponte a lacuna em vez de tirar uma conclusão. ### Se for questionado, leia antes de se defender Quando um veredito for questionado, verifique primeiro o caminho que faltava; não defenda a conclusão anterior antes de ter olhado. ## Leia o código-fonte das dependências e teste as APIs externas de verdade Quando o comportamento depende de uma biblioteca ou serviço externo, verifique contra a coisa real, não pela memória, um wrapper, um schema gerado ou o relatório de outro agente. ### Leia o código-fonte da própria dependência Para comportamento sustentado por uma dependência, leia diretamente o código-fonte, a documentação ou os tipos da fonte original e cite o que foi checado. A maioria das dependências é de código aberto, então não há desculpa para chutar um valor padrão, um erro ou um tempo de execução. ### Teste serviços externos ao vivo Trabalho com APIs externas exige um teste ao vivo mais uma prova atual e citada; não faça afirmações sobre uma API de memória. Verifique ao vivo sempre que possível, e nunca exiba um segredo no processo. ## Decida se uma correção é a melhor, não só uma que funciona O veredito de uma revisão precisa decidir se a mudança é a melhor correção, não apenas uma que funciona por acaso. Compare limites de responsabilidade, chamadores, superfícies irmãs, testes e o comportamento atual antes de concluir. ### Correções unilaterais precisam de prova sobre as irmãs Uma correção que altera uma superfície mas não suas irmãs precisa de prova de que as irmãs não foram afetadas, ou de um acompanhamento explícito que as cubra. ### Não trate preferência pessoal como um problema real Não levante um apontamento por pura preferência de estilo do repositório quando o código alterado segue o guia específico e não apresenta risco visível ao usuário, de execução, de segurança ou para quem mantém o código. ## Leia a configuração de um só jeito e migre chaves antigas em vez de descartá-las Em execução, o sistema lê apenas o formato canônico atual de configuração e dados. Não existe compatibilidade silenciosa para chaves antigas ou malformadas. ### Exclua o caminho antigo Prefira um único caminho canônico e exclua o antigo, a menos que exista um contrato já publicado ou um caminho de atualização marcado explicitamente citado. Uma refatoração que deixa um segundo caminho provavelmente falhou. ### Migre, nunca descarte silenciosamente Se uma mudança invalida uma configuração existente, adicione a migração correspondente na etapa dedicada de migração ou reparo; nunca descarte uma chave silenciosamente, porque uma chave descartada é uma mudança de comportamento oculta. ### Mantenha a superfície de configuração pequena A superfície de configuração e ambiente tem um padrão exigente. Antes de adicionar uma opção, prove que o comportamento existente não resolve o problema, e prefira remover ou consolidar opções. Trate fluxos de configuração documentados como sensíveis à compatibilidade: prefira flags aditivas em vez de quebrar trechos de código já existentes. ## Deixe o código próprio de um módulo nesse módulo, não no código compartilhado O código compartilhado e o núcleo permanecem genéricos; comportamento específico de um dono fica no módulo responsável por ele. Só atravesse um limite por uma interface pública documentada, nunca acessando diretamente os detalhes internos de outro módulo. ### Mova a responsabilidade, não a envolva em uma camada extra O formato padrão de uma correção é uma refatoração limpa e delimitada que move a lógica para o dono correto e elimina abstrações obsoletas, regras duplicadas e ramos mortos de código — não o menor patch possível. ### Correto, mas sem engenharia excessiva Corretude para entradas e estados reais é obrigatória; camadas e proteções extras para entradas imaginárias são defeitos, não rigor. Quando você trocar um caso extremo improvável por simplicidade real, nomeie essa troca para que seja uma decisão consciente, e não um descuido. ## Guarde o estado no armazenamento do projeto, não em arquivos soltos Mantenha o estado de execução no repositório canônico do projeto. Não espalhe arquivos paralelos para estado, caches, filas, índices ou dados temporários que deveriam pertencer ao repositório. ### Migrações são responsáveis pelo formato antigo Armazenamentos de arquivo legados e formatos aposentados só são normalizados em código de migração ou reparo, antes da execução; em regime estável, a execução nunca lê um local alternativo de reserva. ### Nunca avance a versão de um schema sozinho Uma mudança de versão de schema que leitores antigos não conseguem tolerar exige antes uma discussão explícita e aceitação do usuário; nunca avance essa versão de forma autônoma. Uma mudança puramente aditiva, que builds antigas ainda toleram, não exige avançar a versão. ## Reutilize dados já resolvidos em vez de buscá-los a cada requisição Um caminho crítico deve carregar adiante fatos já resolvidos anteriormente, não redescobri-los a cada requisição. ### Resolva uma vez, reutilize Passe identificadores, caminhos resolvidos e fatos de capacidade adiante, e reutilize o objeto já preparado. Não corrija a descoberta repetida em tempo de requisição espalhando caches; mova o fato canônico para mais cedo no fluxo e elimine as buscas duplicadas. ### Sem verificação de atualização dentro do loop Metadados estáveis durante o processo, como instalações, manifests e caminhos resolvidos, só mudam ao reiniciar ou com uma recarga explícita; por isso, caminhos críticos não devem reverificar se estão atualizados relendo ou recalculando hashes. Um cache local ao processo só é aceitável quando tem um dono claro no ciclo de vida e é limitado. ## Escreva código curto, legível e com tipos rigorosos Mantenha a checagem de tipos estrita ativada e mantenha o código honesto. O objetivo é código pequeno e claro, não o menor diff possível. ### Tipe os limites, feche os ramos Evite o tipo dinâmico genérico que aceita tudo; prefira tipos reais e adaptadores restritos. Valide entradas externas com um schema. Ramifique com base em uniões discriminadas ou códigos de resultado fechados, em vez de strings livres ou valores sentinela, e torne estados impossíveis irrepresentáveis. ### Estruture pensando na leitura Prefira retornos antecipados a pirâmides de aninhamento, e divida o trabalho em coletar, normalizar, decidir e agir. Mantenha os pontos de chamada monótonos: decisões complexas acontecem antes, então os argumentos permanecem nomes, literais ou leituras simples. ### Comente o que não é óbvio Um comentário inline merece seu lugar quando explica um invariante não óbvio, uma restrição de ordem, um limite de responsabilidade ou um acoplamento de limpeza: de uma a três linhas dizendo por que aquele ramo existe e o que quebra se for removido. Nada de narrar a sintaxe. ## Se uma refatoração deixar o código maior, corte ou explique por quê Uma refatoração deve eliminar aproximadamente tanta complexidade local quanto adiciona. Um saldo positivo de linhas em produção é um sinal de alerta a ser justificado, não algo a aceitar por padrão. ### Verifique o tamanho antes de encerrar Antes de finalizar uma refatoração não trivial, compare o tamanho da mudança; se o código fora dos testes cresceu, reduza-o ou explique claramente por que menos caminhos agora custam mais linhas. ### Faça toda nova superfície de código justificar sua existência Um novo helper ou arquivo precisa reduzir imediatamente caminhos de chamada, conceitos ou lógica repetida. Não crie um só para compatibilidade pontual, renomeação de campo ou resiliência especulativa. Mantenha as interfaces públicas restritas e retorne o menor formato útil possível. ## Teste o comportamento e não os textos, e isole cada teste Testes comprovam comportamento e protegem contra regressões; eles não são uma caixinha para marcar em cada ramo interno do código. ### Teste comportamento, não texto Prefira testes de comportamento a buscar por strings de documentação ou de política, e coloque lembretes para operadores na documentação, não em asserções de teste. Revise novos testes antes de integrá-los e exclua os de baixo valor, incluindo testes para caminhos que você acabou de remover. ### Mantenha os testes isolados e honestos Limpe timers, variáveis de ambiente, globais, mocks e estado temporário. Um mock precisa exportar todo vínculo que o código real utiliza, incluindo os tipos de erro usados em verificações de identidade. Não edite um arquivo de baseline ou snapshot para silenciar uma checagem sem aprovação. ### Teste em uma cópia do estado real Quando dados realistas importam, copie o estado para um local temporário e teste a cópia; nunca altere o estado de um serviço em produção diretamente sem aprovação explícita. ## Nunca execute código não confiável localmente e envie builds pesados para o executor remoto Classifique o nível de confiança da fonte antes de decidir o quanto precisa ser comprovado, e escolha onde a comprovação será executada com base nessa mesma confiança. ### Nunca execute código não confiável localmente Código de fonte confiável pode rodar alguns testes focados e checagens estáticas baratas localmente, quando as dependências já estão prontas. Código não confiável ou contribuído externamente não executa nenhum de seus próprios scripts, testes, hooks ou configurações localmente, seja qual for o tamanho da comprovação necessária; use execução isolada e sem credenciais em vez disso. ### Envie trabalho pesado para o executor remoto Suítes completas, builds, checagens de tipo, empacotamento e comprovação entre plataformas vão para um executor remoto, obtido sob demanda no primeiro comando pesado, reutilizado durante uma sessão e liberado antes da entrega. Se o executor remoto não estiver disponível, trabalho confiável pode recorrer ao ambiente local; trabalho não confiável nunca pode. ### Condicione a integração a uma revisão recente Antes de integrar, execute uma revisão automatizada recente até não restarem apontamentos acionáveis; não integre apenas com base na integração contínua verde, a menos que o escopo seja trivial ou o usuário opte por dispensar. Se a comprovação estiver bloqueada, diga exatamente o que está faltando e por quê. ## Abra issues e pull requests pelo processo do projeto e peça aprovação antes de lançar Alterar uma superfície compartilhada é um ato social: siga o processo de contribuição do projeto e obtenha aprovação para cada etapa irreversível. ### Siga o processo de revisão e merge Leia o guia de contribuição, os modelos de issue e pull request, e o arquivo de responsáveis pelo código antes de abrir qualquer coisa. Abra primeiro uma issue para bugs, recursos voltados ao usuário e decisões de arquitetura. Escreva uma descrição real de pull request com o problema, o impacto e as evidências, e verifique o estado ao vivo pela própria ferramenta da plataforma antes de qualquer alteração. ### Não faça nada irreversível sem ter sido solicitado Não rotule, renomeie, faça rebase ou integre sem que tenha sido pedido. Mostre um comentário público como rascunho primeiro, a menos que o usuário tenha pedido explicitamente para publicá-lo, e identifique todo comentário publicado com seu link. Encerre o trabalho em issues e pull requests com a URL completa do item. ### Faça commits e branches de forma organizada Faça commit apenas dos arquivos pretendidos, com mensagens concisas e agrupadas, faça rebase sobre a branch principal mais recente antes do push, e nunca exclua ou renomeie arquivos inesperados. Mantenha a documentação alinhada ao comportamento na mesma mudança, e deixe o changelog de lançamento a cargo do processo de release. ### Obtenha aprovação para lançamentos e segredos Lançamentos, avanços de versão e mudanças de dependências ou arquivos de lock exigem aprovação explícita. Nunca faça commit de credenciais reais ou configuração de produção, e mantenha segredos no repositório designado para isso.