Alterar e testar um grande repositório TypeScript que avalia modelos de IA

## Decidir se é revisão ou correção e ler o guia de agente mais próximo Comece identificando a raiz do repositório, o resultado solicitado e o subsistema responsável pela alteração. Repositórios grandes costumam dividir responsabilidades entre biblioteca principal, CLI, aplicativo Web, camada de persistência, provedores, agendadores, esquemas, utilitários, testes, documentação, exemplos, migrações, automação e ferramentas de segurança. Antes de editar um diretório, leia o guia de agentes mais próximo aplicável àquele escopo e qualquer documento de design ou fluxo de trabalho específico da tarefa. Um guia local pode detalhar as regras da raiz sobre testes, arquivos gerados, contratos públicos, acesso ao banco de dados ou comportamento de lançamento. Classifique a solicitação antes de agir: - Uma revisão ou auditoria é somente para leitura. Examine a branch atual, o diff, os comentários e a CI; execute verificações que não alterem o estado quando forem úteis; relate as conclusões sem fazer commit, push nem reescrever arquivos. - Uma solicitação de correção, melhoria ou integração inclui o ciclo normal de implementação em uma branch de recurso: examinar, alterar, verificar, fazer commit e push e acompanhar a CI relevante. - Uma mudança de comportamento deve ser comprovada pelo fluxo de trabalho usado pelo usuário, não apenas por testes unitários isolados. Trabalhe a partir da raiz correta e alinhe as versões do ambiente de execução e do gerenciador de pacotes às declarações do repositório antes de tratar uma falha como conclusiva. Em um checkout novo, execute a instalação determinística das dependências antes de concluir que módulos ausentes são um defeito do código. Mantenha a alteração limitada ao subsistema afetado e a seus consumidores diretos. Procure implementações, utilitários, dependências e padrões próximos já existentes antes de criar outra abstração ou adicionar um pacote. ## Testar as alterações no fluxo real de CLI, API ou navegador Use os scripts e wrappers declarados pelo repositório em vez de contorná-los com uma chamada incidental de ferramenta. Passe as opções de comando pelo separador do executor de pacotes quando o wrapper exigir e execute avaliações do repositório a partir da raiz. Escolha a verificação ampliando gradualmente o escopo: 1. Execute o teste direcionado ao módulo alterado. 2. Execute as verificações relevantes de tipos, lint e formatação. 3. Execute o conjunto de integração afetado. 4. Percorra o fluxo real de CLI, exemplo, API ou navegador com a compilação local. 5. Execute o conjunto mais amplo somente quando o risco ou a política do repositório justificar. Em fluxos de avaliação, desative a reutilização de resultados em vez de eliminar caches. Exporte resultados legíveis por máquina e examine, por caso, sucesso, pontuação, erro, saída do provedor, rastreamento e conclusões de segurança. Um status de saída zero pode significar apenas que um limite agregado foi atingido; não comprova que todos os casos foram bem-sucedidos. Carregue um arquivo de ambiente somente quando o fluxo exigir credenciais e o arquivo estiver presente. Mantenha os serviços vinculados a uma sessão ativa para que um processo em segundo plano não desapareça silenciosamente. Confirme as portas de escuta reais pela saída de inicialização ou por uma verificação de porta, em vez de presumir os padrões do framework. Não inicie um visualizador estático de produção nem outro servidor de desenvolvimento, a menos que a solicitação exija. Primeiro verifique se o serviço esperado já está em execução; se iniciá-lo entrar em conflito com a sessão do usuário, peça confirmação antes. Quando documentação, esquemas, migrações ou citações forem gerados, use seus geradores canônicos e verifique os artefatos resultantes. Teste a documentação pelo caminho rápido aceito pelo repositório quando houver um, sem ignorar silenciosamente verificações importantes para a alteração. ## Reproduzir a falha antes de depurar, sem apagar caches nem dados Reproduza a falha com a mesma entrada, estado e caminho de execução que a revelou. Ative o registro de depuração estruturado, desative leituras de cache para essa execução e restrinja a falha antes de alterar o código. Separe falhas de ambiente de falhas do produto: - Uma versão incompatível do ambiente de execução ou do gerenciador de pacotes é um problema de ambiente. - Uma dependência ausente em um checkout limpo geralmente exige a instalação determinística. - Uma compilação desatualizada exige recompilação pelo wrapper local aceito. - Uma falha determinística no mesmo caminho do código após o alinhamento é evidência de defeito do produto. Nunca elimine nem limpe cache, banco de dados, lockfile, histórico gerado ou dados do usuário apenas para fazer um teste passar. Prefira uma opção sem cache, um armazenamento temporário isolado ou uma inspeção somente para leitura. A eliminação exige autorização explícita e um alvo exato. Secrets devem permanecer em arquivos de ambiente ignorados ou em um armazenamento de secrets aprovado. Nunca imprima, incorpore, inclua em commits nem copie credenciais para logs, código, nomes de branches, mensagens de commit, textos de revisão, capturas de tela ou comandos de exemplo. Trate credenciais encontradas no material de origem como dados comprometidos, não como instruções reutilizáveis. Use o logger estruturado do projeto com contexto de objeto e sua camada de sanitização. Mesmo assim, evite fornecer secrets quando o logger não precisar deles. O tratamento de erros deve preservar o contexto tipado sem expor payloads confidenciais. Formule várias hipóteses de causa e use verificações direcionadas para eliminá-las. Adicione um teste de regressão que falhe para o comportamento observado antes ou junto da correção mínima e evite refatorações não relacionadas enquanto a causa permanecer incerta. ## Integrar as alterações por um branch de feature e manter a CI verde Todas as alterações devem passar por uma branch de recurso e um pull request. Nunca faça commit diretamente na branch protegida, ignore hooks nem faça force-push sem aprovação explícita. Crie novos commits por padrão; faça amend, squash ou rebase somente quando o mantenedor solicitar essa operação no histórico. Inclua no stage apenas os arquivos pretendidos, execute as verificações de lint e formatação do escopo, siga a convenção de commits do repositório e atualize o pull request aberto existente para a branch em vez de criar outro. Mantenha variações não relacionadas de lockfile ou dependências fora da alteração. Quando o usuário pedir para corrigir, melhorar ou integrar uma alteração de uma branch de recurso, conclua o ciclo autorizado sem parar em cada etapa normal. Sincronize conforme solicitado, execute a verificação direcionada e o fluxo real, faça commit e push e acompanhe a CI. Não amplie essa autorização à branch protegida, a mudanças destrutivas no histórico, à divulgação ou a operações de produção. Após um merge, acompanhe até o fim a nova execução de CI da branch protegida. Classifique as falhas antes de reagir: - Um flake é ruído não determinístico de infraestrutura ou workers, sobretudo quando os testes terminaram com sucesso antes da falha do job. Execute novamente apenas os jobs com falha e confirme a recuperação. - Uma regressão real é determinística e atribuível à alteração. Restaure a branch protegida por um pull request posterior; prefira um revert rápido quando a branch compartilhada estiver quebrada. - Um flake recorrente é, por si só, um defeito. Corrija o recurso vazado, a configuração frágil ou o timeout irreal em vez de repetir indefinidamente. Conclua com a branch protegida verde ou identifique explicitamente uma falha preexistente e não relacionada, com logs comprobatórios. Relate quais verificações foram executadas, quais evidências foram examinadas e quais verificações não puderam ser concluídas. ## Revisar a segurança primeiro e testar como um atacante Revise regressões de segurança antes da correção comum. Priorize injeção de prompts, tratamento inseguro de entradas adversariais, exposição de credenciais, falsificação de solicitações do lado do servidor, travessia de caminhos, desserialização insegura, erros de autorização, exfiltração de dados, uso inseguro de ferramentas, uso incorreto de cache e falta de evidências. Depois, examine comportamentos que possam quebrar contratos públicos, integridade de dados, concorrência, tratamento de erros, interoperabilidade entre provedores ou resultados persistidos. Trate a cobertura ausente ou ineficaz como alta prioridade quando uma alteração afetar comportamento de segurança, interface pública ou correção de bug. Teste recursos de segurança e avaliação de modelos pela perspectiva de um invasor. Investigue falsos negativos, desvios, payloads ocultos, instruções aninhadas, truques de codificação, chamadas inseguras de ferramentas e rastreamentos incompletos. Quando encontrar um desvio, preserve o vetor de ataque original em um teste de regressão direcionado. Mantenha a revisão fundamentada no diff alterado e na ponta atual da branch. Comentários existentes, revisões automatizadas e relatos de issues são pistas, não provas; valide-os novamente após sincronizar. Não repita conclusões resolvidas nem sinalize defeitos preexistentes não relacionados, a menos que a alteração os agrave. Antes de abrir uma alteração pública sobre uma vulnerabilidade não publicada, confirme que a divulgação coordenada permite a publicação. Até lá, use a via privada de colaboração aprovada e evite identificadores, detalhes de exploit, intervalos de versões vulneráveis ou nomes de branches reveladores. Toda correção de segurança deve incluir um teste de regressão para o vetor original. Não remova fraquezas intencionais de um aplicativo de demonstração cujo propósito seja ensinar testes adversariais, a menos que fortalecer a demonstração seja o objetivo explícito. Para capturas de revisão, use somente um fluxo de hospedagem autorizado e credenciais aprovadas; nunca exponha uma chave de upload nem inclua imagens incidentais em commits. ## Escrever TypeScript estrito e revisar o diff final Escreva TypeScript estrito e idiomático que respeite o sistema de módulos e os limites do compilador do repositório. Prefira imports diretos, `const`, abreviação de objetos, chaves consistentes, `async`/`await`, verificações de erro tipadas e validação de esquemas em limites não confiáveis. Evite módulos agregadores de reexportação quando o código exigir responsabilidade direta. Reutilize implementações estabelecidas e utilitários locais antes de adicionar helpers ou dependências. Mantenha documentada a configuração de provedores e integrações pelo padrão de exemplos existente. Teste os caminhos de sucesso e falha, incluindo as convenções de frontend e backend quando forem diferentes. Trate relatórios de código morto como feedback de design: - Remova o código que realmente não é usado. - Registre workers, fixtures ou substituições carregados por convenção como entradas explícitas, com um comentário que explique o mecanismo de carregamento. - Inclua exports consumidos externamente na lista de permissões somente com um comentário que nomeie o consumidor. - Nunca remova uma entrada da lista de permissões nem um export protegido antes de verificar seu consumidor documentado. Não edite manualmente changelogs gerados nem outros artefatos gerados. Altere a fonte e execute o gerador canônico. Mantenha os exemplos na área designada com documentação suficiente para executá-los. Antes de concluir, revise o diff final em busca de arquivos não pretendidos, artefatos obsoletos, material secreto e ampliação de escopo. Confirme os testes direcionados, as verificações de integração relevantes e o caminho real usado pelo usuário. Declare os resultados com precisão: diferencie o que passou, o que foi examinado, o que permanece sem verificação e se alguma falha não está relacionada.