Alterar juntas as versões síncrona e assíncrona de uma biblioteca cliente sem quebrar a API

## Listar o comportamento público que não pode mudar antes de editar Antes de editar, identifique o comportamento público, as versões de ambiente de execução compatíveis, a arquitetura relevante e o menor conjunto de arquivos responsável pela alteração. - Trate assinaturas públicas, nomes de argumentos, valores padrão, tipos de retorno, exceções e comportamento em casos extremos como contratos de compatibilidade. - Localize todas as implementações paralelas do mesmo comportamento, como clientes síncronos e assíncronos. - Identifique as camadas de roteamento, análise, política, conexão e formatação de respostas que possam participar do comportamento. - Leia implementações, testes e sobrecargas de tipos próximos antes de escolher um padrão. - Preserve a semântica existente do protocolo e do servidor, a menos que a alteração solicitada exija explicitamente outra coisa. - Não amplie a tarefa para incluir limpeza sem relação com a alteração. Se o comportamento solicitado entrar em conflito com uma invariante documentada, pare e exponha o conflito em vez de redefinir o contrato silenciosamente. ## Aplicar a mesma mudança nos clientes síncrono e assíncrono Quando uma biblioteca oferecer pilhas de clientes equivalentes, trate a paridade como uma propriedade obrigatória. 1. Associe o símbolo síncrono alterado ao seu equivalente assíncrono, ou vice-versa. 2. Compare assinaturas, sobrecargas, anotações de tipo, valores padrão, formatos de retorno, erros e efeitos colaterais. 3. Aplique comportamento equivalente nas duas pilhas, a menos que uma diferença documentada do ambiente de execução torne isso impossível. 4. Mantenha consistentes as interfaces de comandos compartilhadas, as tabelas de roteamento, as funções de retorno do analisador e os dados das políticas. 5. Adicione testes correspondentes quando as duas pilhas expuserem o comportamento. Use a sintaxe de tipos e as convenções de sobrecarga estabelecidas na base de código. Se apenas um lado tiver de mudar, registre o motivo arquitetônico concreto e verifique se a assimetria é intencional. ## Alterar só a camada responsável e reutilizar as funções auxiliares existentes Prefira uma alteração cirúrgica que reutilize os auxiliares e as convenções existentes. - Modifique apenas a camada responsável pelo comportamento. - Preserve as interfaces públicas e a semântica dos erros. - Evite novas dependências, a menos que os recursos existentes não consigam atender ao requisito. - Evite novas abstrações quando um auxiliar ou padrão atual for suficiente. - Mantenha as importações mínimas e no escopo do módulo, a menos que uma importação adiada seja tecnicamente necessária. - Atualize as cadeias de documentação quando o comportamento mudar, mantendo-as coerentes com os tipos. A correção vem em primeiro lugar. Otimize somente depois que o comportamento estiver correto e nunca troque correção por menos alocações ou execução mais rápida. ## Não deixar os caminhos críticos mais lentos nem mudar o comportamento do protocolo Revise alterações em caminhos críticos para detectar alocações evitáveis, análises repetidas, trabalho duplicado e estruturas temporárias grandes. - Reutilize auxiliares estabelecidos e dados armazenados em cache. - Preserve a seleção do protocolo de comunicação de forma independente da formatação de respostas voltada ao usuário. - Mantenha as políticas de roteamento e agregação coerentes com a semântica dos comandos. - Quando relevante, trate explicitamente redirecionamentos, novas tentativas, diferenças de topologia e propagação de erros. - Não normalize silenciosamente um caso extremo que o serviço subjacente apresenta como distinto. Alterações de desempenho devem manter um comportamento observável idêntico. Se uma otimização complicar a correção ou a paridade, prefira a implementação correta mais simples. ## Testar de um caso com falha até a matriz completa de testes Construa evidências aumentando o escopo progressivamente: 1. Adicione ou atualize um teste determinístico que falhe antes da correção. 2. Execute o menor teste ou conjunto de testes relevante. 3. Execute a cobertura espelhada das variantes síncrona e assíncrona. 4. Verifique combinações significativas de protocolo, modo de resposta, topologia ou recursos opcionais. 5. Execute as análises de código, as verificações de formatação e as verificações de tipo exigidas pelo projeto. 6. Execute toda a matriz de testes compatível quando a alteração puder afetar um comportamento compartilhado. Não enfraqueça as asserções, remova a cobertura nem reclassifique falhas apenas para fazer o conjunto de testes passar. Testes que exigem infraestrutura externa devem permanecer claramente separados dos conjuntos locais padrão. ## Revisar as diferenças finais em busca de código de depuração e divergências entre síncrono e assíncrono Antes de concluir, inspecione toda a alteração e verifique: - apenas os arquivos e as linhas relevantes foram alterados; - não restam código de depuração, remoções acidentais nem mudanças de formatação sem relação com a tarefa; - as interfaces públicas e o comportamento dos erros permanecem inalterados, a menos que haja uma intenção explícita; - as implementações espelhadas e as anotações de tipo permanecem alinhadas; - os testes cobrem caminhos de sucesso, casos extremos e caminhos de falha; - as análises de código e os conjuntos de testes exigidos são aprovados; - a documentação corresponde ao comportamento implementado; - nenhuma dependência, alocação ou abstração desnecessária foi introduzida. Corrija cada problema encontrado e repita as verificações afetadas. Informe o que mudou, o que foi validado e qualquer cenário externo explicitamente não testado, sem afirmar que houve uma verificação mais ampla.