Alterar uma base de código com vários pacotes sem quebrar o que já funciona

## Antes de editar, descobrir qual pacote é responsável e quais são suas regras Antes de editar, identifique a raiz do repositório, o pacote ou subsistema responsável pelo comportamento e as instruções aplicáveis para colaboradores mais próximas do trecho afetado. - Encaminhe o trabalho ao menor escopo correto. - Leia as referências locais de arquitetura, convenções, compilação e testes necessárias para esse escopo. - Use uma pesquisa direcionada para um único símbolo e um grafo de dependências disponível para localizar chamadores entre arquivos, imports, o impacto de uma renomeação ou um raio de alteração amplo. - Confirme as versões do ambiente de execução e do gerenciador de pacotes, as definições do espaço de trabalho e os pré-requisitos de compilação a partir da configuração registrada no controle de versão. - Trate os arquivos de instruções vinculados ou gerados como visualizações da fonte oficial que eles declaram; edite apenas o arquivo de origem. Se as instruções entrarem em conflito ou a responsabilidade não estiver clara, pare antes de escrever e apresente o conflito exato. Não modifique pacotes sem relação durante a investigação. ## Manter o comportamento e os nomes públicos atuais e respeitar a arquitetura Evite prejudicar os usuários existentes. Não altere um valor padrão nem retire um nome público, a menos que a alteração aprovada exija isso expressamente. Mantenha os nomes legados funcionando e acompanhe a descontinuação com uma transição documentada e testes do comportamento antigo. Respeite a arquitetura já estabelecida pelo repositório: - mantenha o comportamento dentro de sua camada responsável ou limite de extensão; - preserve a equivalência entre adaptadores oficiais quando o contrato central mudar; - mantenha a configuração em cascata e os contratos públicos de personalização; - neutralize o conteúdo controlado pelo usuário e evite poluir o espaço de nomes global; - atenda aos requisitos declarados de internacionalização e acessibilidade; e - prefira os utilitários existentes e o mínimo de dependências em vez de mecanismos paralelos. Se uma alteração incompatível for inevitável, indique-a com destaque, explique o contrato afetado e ofereça um caminho de migração. ## Fazer a menor alteração possível, com testes e documentação Faça a menor alteração coerente que atenda ao requisito. Siga o estilo de código, comentários e documentação já estabelecido pelo pacote. Para alterações de comportamento: 1. Adicione ou atualize testes unitários focados. 2. Adicione os testes adequados de integração, navegador ou ponta a ponta quando o comportamento atravessar um limite. 3. Execute as compilações prévias necessárias antes dos testes dos pacotes dependentes. 4. Execute os comandos específicos de verificação de código, tipos, estilo e testes para o escopo afetado. 5. Atualize guias públicos, referências de API, exemplos, notas de migração ou entradas do registro de alterações quando o usuário puder perceber a mudança. 6. Atualize as instruções para colaboradores do escopo somente quando a mudança criar uma convenção, local, restrição ou dificuldade recorrente e duradoura. Não declare a conclusão enquanto faltarem os testes necessários ou a documentação voltada ao usuário. Registre qualquer teste que não pôde ser executado e o motivo concreto. ## Pedir aprovação antes de adicionar dependências e verificar antes do lançamento Obtenha a aprovação da pessoa responsável pela manutenção antes de adicionar uma dependência de terceiros. Verifique as licenças das dependências diretas e transitivas, o estado de manutenção, as implicações de segurança, o custo de empacotamento ou execução e se o repositório já oferece essa capacidade. Siga as convenções do repositório para ramificações, solicitações de alteração, revisões e registro de alterações. Mantenha o histórico de mudanças fácil de revisar, evite reescrever o histórico compartilhado e separe trabalhos sem relação. Em trabalhos que durem vários dias, preserve um ponto de controle visível com o método de colaboração aprovado pelo repositório. Antes do lançamento, confirme que os testes de compatibilidade abrangem o comportamento novo e o antigo, que a documentação necessária está presente, que os artefatos gerados estão atualizados e que as variantes do pacote ou os adaptadores previstos foram testados. ## Informar os testes executados e os riscos que restam Retorne um relatório de verificação conciso que liste: - o comportamento alterado e seu escopo; - os arquivos ou componentes afetados; - os testes, compilações e verificações de código e tipos executados, com seus resultados; - as considerações de compatibilidade e segurança; - as atualizações de documentação ou do registro de alterações; e - tudo que não foi executado, os riscos restantes e a próxima ação necessária. Separe os resultados verificados das suposições. Destaque qualquer alteração incompatível ou verificação obrigatória incompleta antes dos detalhes secundários.