Faça um agente de programação seguir as regras de um grande repositório full-stack

## Passe no pre-commit antes de cada push Sempre execute a suíte de pre-commit do repositório sobre todos os arquivos antes de enviar commits. A integração contínua falha quando as verificações de pre-commit falham, portanto este é um portão inegociável, não uma preferência. Como executá-la de forma eficiente: - Prepare (stage) as mudanças primeiro. O pre-commit inspeciona apenas os arquivos preparados, então uma edição não preparada é silenciosamente ignorada. - Para um ciclo interno rápido, execute a suíte sobre os arquivos preparados, ou execute um único hook nomeado (verificador de tipos, formatador, linter). Execute a passagem sobre todos os arquivos antes do push que abre ou atualiza um pull request. - Ative o ambiente virtual ou o shell da cadeia de ferramentas do projeto antes de executar. Os locais comuns diferem de desenvolvedor para desenvolvedor; se o comando não for encontrado, pergunte ao usuário qual ambiente ativar em vez de adivinhar um caminho. - Alguns hooks corrigem automaticamente (formatadores, espaços em branco no fim da linha). Prepare novamente os arquivos corrigidos e execute de novo, porque a primeira execução relata falhas que ela mesma já reparou. Espere três classes de falha: problemas de formatação que são corrigidos automaticamente, erros do verificador de tipos que exigem correção manual e erros de lint que exigem correção manual. ## Escreva o código novo nos padrões para os quais o repositório está migrando Várias migrações estão ativamente em andamento. Código que corresponde ao padrão antigo ainda existe, então sua presença não é permissão para escrever mais código assim. Código novo e código modificado seguem o padrão-alvo. - Frontend tipado: nada de tipos `any` como válvula de escape, e nenhum novo arquivo de script sem tipos — escreva no dialeto tipado e reutilize as definições de tipo existentes. - Camada de componentes compartilhados: importe os componentes de UI do pacote de design system do próprio projeto, e não diretamente da biblioteca de terceiros; prefira os tokens de tematização do design system aos antigos; e evite CSS sob medida em favor da estilização suportada pela biblioteca de componentes. - Pirâmide de testes: prefira testes unitários a testes de integração, e testes de integração a testes ponta a ponta. Escreva novos testes ponta a ponta no framework adotado; o framework ponta a ponta substituído está descontinuado e será removido quando a migração terminar. - Tipagem no backend: todo código novo carrega dicas de tipo, os modelos usam anotações adequadas, e o verificador de tipos deve passar. - Migração de identificadores: os novos modelos usam identificadores únicos opacos como chaves primárias, as APIs públicas expõem esses identificadores em vez dos inteiros sequenciais internos, e os modelos existentes ganham o novo identificador junto com o inteiro, para uma transição gradual. ## Avalie problemas de segurança pelo que cada papel pode fazer Antes de avaliar qualquer caminho de código quanto a problemas de segurança, leia o documento canônico de política de segurança do repositório. Ele é a fonte autoritativa do modelo de segurança e é o critério pelo qual tanto os relatores humanos quanto os scanners automatizados são medidos. O único teste para saber se um achado está no escopo: ele permite que uma entidade principal execute uma ação à qual a matriz de papéis e capacidades da política de segurança não lhe dá direito? Se sim, está no escopo. Se não, não está. Três limites de confiança emolduram esse teste: 1. O papel de administrador é uma entidade principal operacional totalmente confiável. Qualquer coisa que um administrador possa fazer por meio de configuração, API ou UI documentadas é uma capacidade pretendida, não uma vulnerabilidade. 2. O operador é dono das decisões de tempo de implantação: segredos, exposição de rede, seleção de feature flags, escolhas de conectores e codecs, destinos de notificação e plugins de terceiros. Configuração incorreta nessa camada é um defeito de implantação, não uma vulnerabilidade do produto. 3. A base de código é responsável por aplicar a matriz de papéis e capacidades em todo lugar onde expõe funcionalidade a uma entidade principal — rotas de API, camadas de comandos e de acesso a dados, handlers de UI, jobs em segundo plano e todos os demais pontos de entrada. Uma verificação de aplicação ausente ou incorreta está no escopo, não importa onde ela esteja. O modelo pressupõe que a infraestrutura controlada pelo operador — banco de dados de metadados, caches, brokers de mensagens, cofres de segredos, ambiente de implantação — permanece dentro do limite de confiança do operador. Um achado válido precisa demonstrar uma violação de limite por um atacante que ainda não controla esses sistemas. ## Use a verificação de permissão certa para cada rota e tipo de dado A autorização em nível de rota usa um decorador por classe de rota, e o correto depende do tipo de rota: um para a superfície moderna da API REST, um para as rotas de view JSON legadas e um para as rotas de view HTML legadas. Trocá-los é um bug de aplicação de política mesmo quando uma verificação parece estar presente. A autorização em nível de objeto é um segundo portão, separado. Ela se aplica a recursos que carregam dados — dashboards, gráficos, datasets e fontes de dados, consultas, acesso a bancos de dados e tabelas, e contextos de consulta — e é invocada por objeto através da verificação de acesso do gerenciador de segurança. Código que omite o portão por objeto em uma rota que retorna ou modifica um objeto específico portador de dados está no escopo. Outros recursos — anotações, tags, modelos de estilo, relatórios, regras de segurança em nível de linha e similares — dependem deliberadamente do decorador em nível de rota mais a delimitação por propriedade nos filtros base da camada de acesso a dados. A ausência de uma verificação por objeto nesses recursos é intencional e não é um achado. Seguir o padrão de autorização correto para uma classe de recurso não isenta o código de outros problemas. Injeção, falsificação de requisição do lado do servidor, cross-site scripting e classes semelhantes não têm relação com autorização e são avaliadas separadamente. ## Faça os scanners automáticos indicarem a regra violada e o papel do atacante Os scanners automatizados — scanners de código baseados em modelos, analisadores estáticos e ferramentas de dependências — devem, em todo achado que registrarem contra esta base de código, nomear explicitamente duas coisas: 1. A linha específica da matriz de papéis e capacidades da política de segurança que o achado considera violada. 2. A entidade principal que o achado assume que o atacante possui: uma entidade anônima ou pública, um papel autenticado de baixo privilégio, um papel de ferramenta de consulta, um papel elevado de autoria, o papel de administrador, um token de convidado incorporado, ou um papel personalizado nomeado com concessões explícitas de capacidades. Um achado que não consiga identificar ambos deve ser registrado como pergunta, não como vulnerabilidade. Esse requisito existe para que todo problema reportado seja testável contra o modelo de segurança publicado, e para que relatórios especulativos ou baseados apenas em correspondência de padrões fiquem fora da fila de triagem. ## Siga os padrões de código do frontend e do backend Frontend: evite `any` e reutilize os tipos existentes; escreva componentes funcionais com hooks; pegue os componentes de UI do pacote de design system compartilhado em vez de importar diretamente da biblioteca de terceiros; use o executor de testes e a biblioteca de testes padrão do projeto, não o renderizador legado removido; use o store global onde ele já existe e o estado local de hook nos demais casos. Backend: dicas de tipo são obrigatórias em todo código novo, o verificador estático de tipos deve passar, os modelos de dados carregam tipagem adequada, e o framework de testes padrão do projeto é usado nos testes. Ao construir consultas, use o operador de negação do ORM sobre uma coluna booleana em vez de compará-la a um literal falso, o que o linter sinaliza. Cabeçalhos de licença: novos arquivos-fonte exigem o cabeçalho de licença padrão do projeto. Os arquivos de instruções para agentes (este arquivo e seus irmãos por fornecedor) são deliberadamente excluídos desse requisito, para não gastar tokens com o cabeçalho. Comentários: evite linguagem presa ao tempo, como "agora", "atualmente" ou "hoje", porque envelhece mal. Escreva comentários que continuem corretos sempre que forem lidos. ## Atualize a documentação e as notas de mudanças incompatíveis junto com o código A documentação faz parte da mudança, não é uma tarefa posterior: - Atualize a árvore de documentação para qualquer mudança visível ao usuário. - Registre as mudanças incompatíveis no arquivo dedicado de notas de atualização, para que os operadores as encontrem em um só lugar. - Escreva docstrings para toda nova função e classe. Quando uma mudança afeta um comportamento que um operador ou usuário final pode observar, um pull request sem a edição de documentação correspondente está incompleto. ## Corrija a documentação gerada dos componentes nas stories, não no gerador O portal do desenvolvedor gera automaticamente a documentação dos componentes a partir das stories do catálogo de componentes. As stories são a única fonte da verdade, o que leva a duas regras: quando algo é renderizado incorretamente, corrija primeiro o arquivo da story, e não o gerador; e mantenha o gerador leve — ele extrai e repassa os dados da story, então resista a acrescentar nele casos especiais por componente. Para que a documentação de um componente seja gerada corretamente, seu arquivo de story deve: - Exportar o objeto de metadados inline como exportação padrão, em vez de atribuí-lo a uma variável e exportar essa variável. - Nomear as stories interativas com um prefixo consistente mais o nome do componente. - Definir os valores padrão das props nos argumentos da story. - Definir os tipos de argumento no nível da story, não no nível dos metadados, incluindo tipos de controle e descrições. - Usar as chaves de parâmetro documentadas para grades de variantes, filhos de exemplo para os componentes que precisem deles, blocos de código ao vivo personalizados e props de objeto complexas que não podem ser analisadas inline. Tenha em mente o script gerador, seu componente wrapper e o diretório de saída gerado como as três peças móveis ao diagnosticar um problema de documentação. ## Use os auxiliares de teste do repositório em vez de montar a preparação por conta própria O repositório fornece auxiliares; use-os em vez de montar a configuração à mão. No backend, isso significa a classe base de teste compartilhada, decoradores para simular configuração e alternar feature flags, auxiliares de autenticação para logar como um determinado papel, e auxiliares de fábrica para criar as fixtures de que um teste precisa. No frontend, isso significa o auxiliar de render personalizado que instala os providers padrão, a fábrica de wrapper para store, roteador e tema, e o auxiliar de interação com selects. Regras de mock: use um mock simples para objetos de configuração, e não recorra a um mock assíncrono quando o código sob teste é síncrono. Quando um modelo ganha um novo campo, atualize as listas de colunas esperadas nos testes de API. Saiba como executar cada suíte: toda a suíte de frontend, um único arquivo de teste de frontend, todos os testes de backend, um único arquivo de teste de backend, um diretório de testes de backend, e a suíte ponta a ponta nos modos headless, interativo, com interface (headed) e de depuração. Se os testes de backend falharem por causa da configuração do banco de dados ou do ambiente, e não por causa do código sob teste, peça ao usuário que execute a configuração do ambiente de testes, em vez de improvisar correções no ambiente dele. ## Verifique o endpoint de saúde da aplicação antes de depurar Faça primeiro a verificação rápida de configuração: acesse o endpoint de saúde da aplicação e confirme que ele responde antes de gastar tempo com um relatório de bug. Uma verificação de saúde que falha geralmente significa que o workspace nunca foi configurado, e não que o código está quebrado. Se a verificação de saúde falhar, diga ao usuário que o ambiente não parece configurado e aponte-o para as instruções de configuração documentadas do projeto para trabalhar com agentes, em vez de tentar consertar o ambiente dele você mesmo. Conheça os arquivos-chave do projeto ao se orientar: o manifesto de pacote do frontend, com os scripts de build, teste e lint e a porta do servidor de desenvolvimento; o arquivo de projeto Python, com a configuração do linter e do verificador de tipos; e a pasta de requisitos de dependências, dividida em conjuntos base e de desenvolvimento. ## Preencha o template de pull request e use títulos no formato conventional commits Ao abrir um pull request: 1. Leia o arquivo atual do template de pull request no repositório antes de redigir. Sempre leia o arquivo real, em vez de reutilizar conteúdo em cache, porque o template muda ao longo do tempo. 2. Preencha todas as seções que o template define — resumo, evidências de antes e depois, instruções de teste e informações adicionais. 3. Dê ao pull request um título no formato de conventional commits `type(scope): description`, por exemplo `fix(dashboard): load charts correctly`. Os tipos válidos são `fix`, `feat`, `docs`, `style`, `refactor`, `perf`, `test` e `chore`. ## Conheça a estrutura de pastas e os padrões de arquivos antes de editar código desconhecido Dois hábitos mantêm as mudanças no lugar certo em um repositório grande. Primeiro, aprenda o mapa de diretórios antes de editar: qual árvore contém a aplicação de backend, seus endpoints de API, modelos de dados e conectores; qual árvore contém o código-fonte do frontend e suas áreas de componentes, construtor de gráficos, dashboards e editor de consultas; onde fica o pacote compartilhado de design system; e onde ficam os testes, a documentação e o registro de mudanças incompatíveis. Segundo, conheça os padrões recorrentes de arquivos para que um novo recurso caia nos arquivos convencionais: o módulo de API para os endpoints com seus decoradores e docstrings que geram o schema, o módulo de schemas para a validação de requisição e resposta que alimenta a especificação de API gerada, a camada de comandos para a lógica de negócio envolvida em transações, e a camada de modelos para a persistência. A documentação de API gerada deriva dessas docstrings e schemas, então uma mudança de endpoint sem atualização da docstring a degrada silenciosamente. As migrações de banco de dados seguem sua própria convenção: elas ficam no diretório de versões de migrações, são nomeadas com um timestamp, um hash de revisão e uma descrição, e devem chamar os auxiliares utilitários compartilhados de migração em vez de operações brutas do ORM, para que continuem compatíveis entre diferentes motores de banco de dados. Por fim, note que este repositório mantém arquivos de instruções paralelos para diferentes fornecedores de agentes. Mantenha-os consistentes quando você alterar uma regra que se aplica a todos eles.