Altere um monorepositório tipado sem quebrá-lo e mantenha sua wiki atualizada

## Descubra quais pacotes, testes e documentos uma alteração afeta Trate as orientações raiz para agentes como o contrato compartilhado por todos os agentes de programação. Todo arquivo de instruções específico de uma ferramenta deve permanecer enxuto e remeter a esse contrato, em vez de duplicá-lo. - Identifique onde ficam os pacotes principais, as integrações opcionais, as ferramentas de desenvolvimento, os módulos do ecossistema, os exemplos, a documentação e os testes. - Espere que os testes e fixtures fiquem próximos do pacote que exercitam, a menos que o repositório determine o contrário. - Leia as orientações do pacote mais próximo antes de editar um subsistema. - Antes de tocar nos arquivos, associe a alteração solicitada ao pacote responsável, à superfície pública, aos testes e à documentação. - Prefira o menor escopo afetado; não transforme uma tarefa específica em uma reescrita de todo o repositório. ## Use o gerenciador de pacotes e os scripts do repositório Use o gerenciador de pacotes, a definição do workspace, a versão do ambiente de execução e os scripts declarados pelo repositório. Não os substitua por uma alternativa familiar apenas porque ela está instalada localmente. - Use o comando de instalação documentado para preparar as dependências do workspace. - Use os scripts raiz de compilação, testes, lint e verificação de tipos para fazer verificações completas. - Use os filtros de workspace compatíveis para trabalhos concentrados em um pacote. - Preserve exatamente o encaminhamento de argumentos quando um invólucro passar opções para uma ferramenta subjacente. - Verifique os arquivos de configuração do repositório antes de alterar pressupostos sobre o gerenciador de pacotes ou o ambiente de execução. - Registre qualquer pré-requisito do qual dependa um comando de escopo mais restrito. ## Rode os testes na ordem da CI, sem arquivos de build antigos Reproduza a ordem da integração contínua, em vez de inventar uma sequência local. Se a CI instalar as dependências e executar o comando de validação sem compilar primeiro, execute os testes da mesma forma. - Não compile primeiro quando resultados gerados puderem ser encontrados junto dos arquivos-fonte. - Reconheça erros de registro duplicado, esquema duplicado ou classe decorada duplicada como possíveis evidências de que tanto os arquivos-fonte quanto os gerados foram carregados. - Remova somente os diretórios de resultados gerados sob as raízes de código-fonte documentadas, excluindo dependências, testes e fixtures. - Nunca exclua diretórios de código-fonte para resolver uma falha causada por resultados gerados. - Após a limpeza, execute novamente o teste que falhou antes de alterar o código da implementação. - Se a limpeza não mudar a falha, retome a depuração comum com as novas evidências. ## Siga o estilo do código e não guarde o estado do app em globais Prefira os padrões estabelecidos no repositório a novas abstrações. Use o sistema de módulos, as convenções da linguagem tipada, o formatador, o linter e o estilo de nomes de arquivo já adotados pela base de código. - Mantenha os nomes de arquivo em letras minúsculas e separados por hífen quando essa for a convenção do repositório. - Faça alterações na API pública de modo deliberado, com cobertura de testes e documentação. - Mantenha o estado mutável de execução específico da aplicação em um escopo pertencente a ela, e não em um singleton global do processo. - Use o armazenamento com escopo do framework para utilitários de ciclo de vida e outros serviços próprios de cada aplicação. - Volte a entrar no escopo da aplicação responsável para callbacks desvinculados, como temporizadores, ouvintes de eventos, manipuladores de proxy e pontos de escape no nível do módulo. - Não adicione invólucros de escopo redundantes ao redor de acessores já fixados ao contexto correto da aplicação. ## Faça os módulos carregados na inicialização funcionarem com snapshots Quando um ambiente de execução puder serializar um snapshot de inicialização, presuma que a inicialização durante a compilação pode parar antes da inicialização normal da aplicação. Todo módulo carregado nessa fase deve poder ser serializado com segurança. - Mantenha os módulos como externos quando o trabalho durante a importação ou a inicialização criar estado nativo não serializável. - Trate analisadores HTTP, vinculações HTTP/2, contextos TLS, canais DNS, instâncias de WebAssembly, monitores de arquivos, complementos nativos e sockets abertos como dependências de alto risco para snapshots. - Encaminhe os módulos externalizados pela ponte de carregamento do ambiente de execução durante a restauração. - Mantenha uma única lista padrão documentada dos módulos que devem continuar com carregamento tardio ou permanecer externos. - Amplie essa lista por meio da configuração compatível do repositório, em vez de corrigir resultados gerados. - Diferencie a criação direta de estado nativo do uso transitivo da rede: módulos internos externalizados com carregamento tardio talvez já protejam dependências transitivas, enquanto um pacote que crie diretamente estado nativo ou de WebAssembly ainda exige tratamento explícito. - Adicione um teste de compilação de snapshot quando uma dependência do framework puder acessar a pilha nativa ou de rede durante a inicialização. ## Coloque os tipos globais adicionados em um módulo de tipos próprio Coloque as ampliações globais de todo um pacote em um módulo dedicado de tipos globais. Ampliações compartilhadas que atendem a vários pacotes devem ficar em um pacote compartilhado de definições de tipos, e não em um único consumidor. - Mantenha os arquivos de declaração como módulos por meio de uma importação, uma importação apenas de tipos ou uma exportação vazia. - Importe a ampliação compartilhada a partir do ponto de entrada do pacote que precisa dessa superfície de tipos. - Evite declarações de ambiente que se tornam globais somente porque um arquivo não contém sintaxe de módulo. - Depois de mover tipos compartilhados, teste tanto o pacote que os define quanto pelo menos um pacote consumidor. - Documente qualquer alteração na superfície pública de tipos. ## Rode os testes necessários e revise o diff final antes de relatar Execute primeiro as verificações mais específicas que comprovem o comportamento alterado e amplie o escopo somente quando o limite afetado exigir. - Adicione cobertura de regressão para alterações em carregadores, ciclo de vida da aplicação, agrupamento, agentes, tratamento de HTTP ou comportamento de processos. - Execute formatação, lint, verificação de tipos e testes relevantes por meio dos scripts do repositório. - Use a convenção de mensagens de commit do repositório e mantenha o escopo exato. - Explique a motivação, o comportamento alterado, o risco e as evidências dos testes na descrição da alteração. - Revise o diff final em busca de edições não relacionadas, ruído gerado e alterações públicas não documentadas. - Não alegue êxito até que o comando relevante tenha sido concluído com sucesso. ## Não faça commit de segredos e pare antes de publicar falhas de segurança Leia a política de segurança do repositório antes de trabalhar com vulnerabilidades. Nunca envie ao repositório segredos, credenciais, endpoints privados ou configurações específicas de uma máquina. - Mantenha as versões locais do ambiente de execução e do gerenciador de pacotes alinhadas às declarações do repositório. - Trate os arquivos de bloqueio e a configuração do workspace como entradas coordenadas; altere-os somente para uma atualização intencional de dependência ou da cadeia de ferramentas. - Use espaços reservados em exemplos e na documentação, em vez de credenciais reais ou URLs privadas. - Mantenha as alterações sensíveis à segurança em um escopo restrito e adicione cobertura de regressão para o limite protegido. - Pare antes de publicar detalhes de vulnerabilidades ou alterar sistemas externos protegidos, a menos que a tarefa autorize explicitamente essa ação. ## Separe o código e outras fontes, a wiki e as regras para a IA Mantenha três camadas distintas de conhecimento. As fontes brutas são evidências de referência, a wiki armazena sínteses duradouras e as orientações raiz para agentes definem as regras compartilhadas do fluxo de trabalho. - Trate o código, a documentação voltada ao usuário, os arquivos raiz do projeto, os artefatos externos explícitos e o material bruto importado como evidências de fonte. - Comece pelos resumos da wiki para se orientar, mas confira as fontes brutas quando detalhes, conflitos ou atualidade forem importantes. - Não reescreva fontes brutas, a menos que a tarefa exija isso. - Registre na base de conhecimento do repositório as evidências externas usadas repetidamente. - Registre conflitos, em vez de nivelá-los até criar um falso consenso. - Mantenha enxutos os arquivos de agente específicos de ferramentas e faça-os apontar para o esquema compartilhado. ## Dê a cada página da wiki um só tema e seus arquivos de origem Dê a cada página de conhecimento substancial um único tema claro e um tipo de página declarado, como pacote, conceito, fluxo de trabalho, decisão ou fonte. - Use nomes de arquivo em letras minúsculas e separados por hífen. - Inclua metadados iniciais com título legível, tipo de página, resumo de uma linha, principais caminhos de origem, data local do calendário e estado de atualidade. - Liste as afirmações não triviais com arquivos-fonte rastreáveis. - Identifique como inferência toda síntese que não seja evidente. - Marque afirmações obsoletas ou não resolvidas quando a atualidade for incerta. - Mantenha o índice da wiki conciso e organizado por categoria. - Use um registro somente de acréscimos para ingestões substanciais, descobertas duradouras, refatorações relevantes e alterações que mudem o entendimento registrado. - Não registre edições triviais que apenas corrijam erros de digitação. ## Leia o índice da wiki antes de adicionar fontes ou responder perguntas Use um fluxo de trabalho previsível ao ingerir fontes, responder a perguntas sobre o repositório ou verificar a base de conhecimento com lint. - Para ingestão, leia o índice, encontre páginas existentes que devam absorver o material, crie ou atualize uma página de fonte quando justificável, atualize as páginas afetadas, renove o índice e acrescente uma entrada ao registro para alterações substanciais. - Para consultas, leia primeiro o índice e as páginas relevantes da wiki, confira as fontes brutas, grave as novas descobertas duradouras e registre alterações substanciais no conhecimento. - Para lint, procure páginas órfãs, afirmações obsoletas, conceitos duplicados, referências de fonte ausentes, áreas usadas com frequência sem páginas e contradições. - Prefira reestruturar páginas sobrepostas a torná-las indefinidamente mais longas. - Priorize a cobertura duradoura de pacotes fundamentais, integrações, ferramentas, comportamento do ciclo de vida, carregamento, testes, trabalho de lançamento e manutenção da documentação. ## Atualize a wiki só quando as APIs ou os fluxos de trabalho mudarem Atualize a base de conhecimento quando o trabalho alterar substancialmente APIs públicas, a estrutura da documentação, as responsabilidades dos pacotes, a arquitetura, os fluxos de trabalho recorrentes de colaboradores, as expectativas de testes ou os procedimentos de lançamento. - Evite alterações desnecessárias na wiki por uma mudança apenas no código que não modifique o entendimento duradouro. - Atualize as orientações para colaboradores na mesma alteração quando uma nova regra passar a ser aplicável de forma ampla. - Mantenha os caminhos de origem e as datas de atualidade sincronizados com os fatos que sustentam. - Adicione uma entrada ao registro somente quando a alteração do conhecimento for substancial o bastante para ajudar trabalhos futuros. - Compare a documentação final com o comportamento implementado antes de informar a conclusão.