Alterar e testar código em um monorrepositório grande com muitos pacotes

## Localizar pacotes e pontos de entrada antes de editar - Identifique o layout do espaço de trabalho, os pacotes publicados, os componentes nativos, as suítes de testes, os exemplos, a documentação e os scripts de manutenção. - Localize a árvore de código-fonte do pacote principal, a saída compilada, os pontos de entrada da linha de comando, os pontos de entrada do servidor e o ponto de entrada da compilação. - Rastreie o ponto de entrada relevante antes de mudar o comportamento; não deduza a responsabilidade apenas pelo nome de um arquivo. - Antes de editar um arquivo aninhado, leia todos os `README.md` aplicáveis desde a raiz do repositório até o diretório de destino. - Trate a saída gerada e os diretórios de dependências apenas como evidências para pesquisa. Altere sua fonte ou gerador em vez de editar diretamente os arquivos gerados. ## Manter a compilação atualizada e escolher uma compilação parcial ou completa - Depois de trocar de branch ou inicializar um espaço de trabalho de estado incerto, execute a compilação completa de bootstrap para atualizar as saídas dos pacotes dependentes. - Para trabalho iterativo no código-fonte ou em testes de integração, inicie a compilação do pacote em modo de monitoramento antes de editar, a menos que ela já esteja em execução. - Uma alteração apenas de documentação, uma investigação somente para leitura ou uma análise limitada à CI pode omitir o modo de monitoramento, mas registre o motivo. - Use a compilação focada no pacote quando as alterações permanecerem dentro de um só pacote. Use a compilação completa quando o trabalho atravessar pacotes ou modificar código nativo. - Para erros de tipo, prefira a verificação de tipos dedicada a uma compilação completa quando ela fornecer evidências equivalentes. - Encerre qualquer processo de monitoramento iniciado por você após a conclusão da tarefa. ## Escolher testes que correspondam ao modo de desenvolvimento ou de produção - Escolha o comando de teste que corresponda exatamente ao comportamento de desenvolvimento ou produção e à implementação pretendida do empacotador ou do runtime. - Recompile o código-fonte afetado antes de executar testes de integração; uma saída compilada desatualizada invalida o resultado. - Execute primeiro o arquivo de teste ou padrão de nome relevante com o escopo mais restrito e só amplie quando a falha ou a superfície da alteração exigir. - Reproduza a CI com o mesmo comando, modo, flags de funcionalidade e nomes de variáveis de ambiente. Pequenas diferenças de modo podem alterar a resolução e os snapshots. - Não substitua um teste de integração por um teste unitário conveniente quando a afirmação envolver resolução de pacotes, empacotamento, inicialização ou comportamento do navegador. - Quando flags de funcionalidade habilitarem implicitamente um comportamento, teste a suíte normal com esse flag em vez de depender apenas de suítes dedicadas legadas. ## Escrever testes que esperam por condições em vez de pausas fixas - Use o gerador de testes do repositório, incluindo seus argumentos não interativos, para que os fixtures e a configuração do harness sigam as convenções locais. - Prefira auxiliares de repetição baseados em condições e com asserções a esperas fixas. Atrasos fixos são lentos e continuam sujeitos a condições de corrida. - Substitua auxiliares de polling obsoletos pelo padrão compatível de repetição e asserção. - Prefira diretórios reais de fixtures a grandes mapas de arquivos em linha para que os testes se assemelhem a projetos reais e continuem fáceis de manter. - Para testes específicos de um modo, execute a guarda de modo antes de iniciar manualmente um servidor quando o harness exigir inicialização adiada. - Controle a pré-busca e o estado de navegação dentro do limite de sincronização do teste; evite ações de histórico que restaurem o estado em cache e acionem trabalho descontrolado. ## Salvar a saída de testes e compilações em vez de executar de novo - Capture uma vez a saída completa de um teste ou compilação e depois pesquise e resuma a saída salva, em vez de executar novamente a mesma suíte com filtros diferentes. - Para arquivos maiores que aproximadamente 500 linhas, pesquise primeiro os símbolos relevantes e leia apenas os intervalos ao redor. - Pesquise diretórios gerados apenas quando necessário para confirmar o comportamento emitido; não os examine como fonte principal. - Agrupe edições relacionadas antes de executar a próxima compilação e use a verificação mais rápida que comprove a hipótese atual. - Armazene em cache as respostas de status remoto durante uma investigação e analise a resposta salva sob vários ângulos, em vez de buscá-la repetidamente. - Preserve a saída exata da falha, o comando, o modo e o ambiente como evidências para a próxima etapa de diagnóstico. ## Reproduzir falhas da CI e corrigi-las antes dos comentários de revisão - Use a ferramenta de análise de status do repositório quando houver uma e identifique se está sendo examinada a branch atual ou uma solicitação de alteração explícita. - Trate as falhas bloqueantes nesta ordem, a menos que as evidências determinem o contrário: compilação, formatação ou lint, tipos e, depois, testes. - Considere as falhas reais até que sejam refutadas. Um comportamento instável conhecido é contexto para investigação, não permissão para descartar uma falha. - Reproduza com o mesmo modo de CI e os mesmos flags de ambiente, especialmente quando houver diferentes empacotadores ou caminhos de runtime disponíveis. - Para falhas de resolução de módulos ou do grafo de compilação, execute o comando normal de integração específico do modo para exercitar o grafo real de pacotes. - Separe falhas de CI de comentários de revisão, resolva primeiro as evidências de execução bloqueantes e mantenha um registro conciso do que foi reproduzido. ## Ligar os flags de funcionalidade na compilação e no runtime - Adicione um novo flag de funcionalidade ao seu tipo público, esquema de validação e ponto de injeção em tempo de compilação quando ele for consumido por código empacotado pelo usuário. - Se o código pré-compilado do runtime consumir o flag, conecte também o valor de runtime em cada caminho relevante de servidor ou worker. - Não presuma que a injeção em tempo de compilação destinada ao código do usuário controle os componentes internos pré-compilados do runtime. - Mantenha carregamentos condicionais de módulos dentro de ramificações `if` / `else` em tempo de compilação para que a eliminação de código morto possa remover dependências inalcançáveis. - Em runtimes restritos, force para `false` os flags que protegem importações de plataformas sem suporte. - Mantenha importações específicas do runtime em seu módulo de entrada designado e exponha o comportamento necessário pela fachada pública desse módulo. - Use um sinal dedicado de runtime para distinguir um servidor de desenvolvimento ativo de uma compilação de depuração; um rótulo genérico de ambiente pode descrever ambos. - Marque qualquer novo cabeçalho não padrão de solicitação recebida para revisão de segurança, a menos que a camada de entrada o remova ou autentique. ## Manter segredos fora dos logs e parar quando a autenticação falhar - Trate os valores das variáveis de ambiente como confidenciais, a menos que sejam flags documentados do modo de teste. - Nunca imprima, cole, faça commit nem coloque tokens, chaves, cookies ou valores secretos em logs compartilhados, texto de revisão ou exemplos. - Replique os nomes e os modos das variáveis de CI sem inserir seus valores diretamente. Se um segredo obrigatório estiver ausente, pare e solicite-o pelo canal aprovado. - Use espaços reservados ao documentar a configuração e nunca faça commit de arquivos locais de segredos. - Se a autenticação do controle de versão falhar porque um agente de assinatura, provedor de chaves ou credencial protegida por hardware estiver indisponível, pare e peça ao usuário para desbloqueá-la. - Não altere protocolos nem endereços remotos, não repita a operação que falhou nem tente uma solução alternativa de autenticação sem aprovação explícita. ## Verificar a permissão antes de publicar solicitações de alteração ou comentários - Antes de criar ou editar uma solicitação de alteração, issue, discussão ou comentário remoto, determine se a contribuição vem de uma branch interna ou de um fork externo. - Verifique a política de contribuição do repositório e a autorização do usuário antes de escrever em nome dele. - Se a autorização for insuficiente, não se passe por mantenedor nem publique todo o conteúdo remoto. Ofereça fatos técnicos, revise o texto escrito pelo usuário e indique o caminho de envio controlado por ele. - Aplique exceções documentadas de modo restrito e somente depois de verificar suas condições. - Mantenha solicitações de alteração recém-criadas no estado de rascunho, a menos que o usuário decida explicitamente que estão prontas para revisão. - Operações de escrita remota exigem um escopo explícito; a análise e a reprodução locais não implicam permissão para publicar. ## Dividir o trabalho em pequenos passos e conferir cada um - Divida uma tarefa grande em pequenas etapas cujas saídas possam ser verificadas de forma independente. - Verifique cada etapa antes de passar à seguinte com o método correspondente ao risco: inspeção, formatação, lint, tipos, testes unitários, testes de integração, compilação ou observação em runtime. - Quando o método correto de verificação não estiver claro, pergunte antes de afirmar que a etapa está concluída. - Antes de fazer commit, execute nos arquivos alterados a mesma configuração de formatador e linter usada pelo hook de commit do repositório. - Revise o diff final em busca de edições não relacionadas, ruído gerado, material secreto e testes ou documentação ausentes. - Não informe a conclusão sem identificar as evidências que sustentam o comportamento alterado. ## Detectar binários nativos desatualizados e snapshots que não batem - A consulta a mapas de código-fonte pode exigir um flag explícito de runtime, e os caminhos do código-fonte podem diferir entre compiladores; teste os formatos de caminho conhecidos. - Considere o diretório de trabalho atual ao comparar rastreamentos de pilha de testes e produção. - Após alterações de branch, suspeite de binários nativos desatualizados quando o comportamento contradisser o código-fonte; atualize o artefato gerenciado por dependências pelo caminho de bootstrap aprovado. - Para um erro interno do compilador, remova apenas o cache de compilação incremental afetado e tente novamente uma vez antes de escalar. - Use o formatador oficial para código de linguagem nativa e prefira importações baseadas na raiz do repositório, exceto dentro de módulos de teste em linha com escopo rigorosamente limitado. - A saída dos snapshots pode variar conforme os flags e a implementação do runtime; portanto, atualize os snapshots somente no ambiente exato usado pelo trabalho de CI de destino. - Nos blocos de código da documentação, reconte as linhas exibidas após as edições e confirme que cada destaque aponta para a instrução pretendida.