Alterar uma biblioteca ou SDK compartilhado sem quebrar a API pública

## Rodar todos os testes e builds antes de dizer que a mudança terminou Execute a pilha completa de verificação do projeto antes de declarar qualquer mudança concluída, quando a mudança afetar código em tempo de execução, testes ou comportamento de build/teste. A verificação se aplica quando você modifica: - Código central da biblioteca ou utilitários compartilhados. - Testes, incluindo testes de snapshot. - Projetos de exemplo. - Configuração de build ou teste (manifestos de dependência, arquivos de executor de tarefas, configuração de build de documentação, workflows de CI). Você pode pular a verificação completa para mudanças somente de documentação ou de metadados do repositório (documentação, guias de contribuidor, arquivos de metadados), a menos que o usuário peça explicitamente a pilha completa. Decida se a verificação se aplica com base nos arquivos realmente alterados, não em uma sensação subjetiva do tamanho da mudança. Execute a pilha inteira novamente após aplicar qualquer correção — uma reexecução parcial esconde regressões introduzidas pela própria correção. Ao integrar com a API de uma plataforma externa, consulte a documentação oficial dessa plataforma em vez de confiar em suposições genéricas de API, e inspecione o caminho de código local para entender o comportamento próprio da biblioteca. ## Não trocar de branch nem de worktree no Git sem permissão do usuário Trabalhe por padrão no checkout atual do usuário e na branch atual. Se a tarefa já estiver em execução dentro de uma worktree selecionada, use essa worktree sem solicitar permissão adicional. Não crie ou mude para outra worktree, e não crie ou mude de branch, a menos que o usuário peça explicitamente ou aprove exatamente essa ação na conversa atual. Um pedido para implementar, investigar, revisar, testar ou verificar mudanças não autoriza, por si só, a alteração da worktree ou branch ativa. Se o isolamento ou um checkout diferente for genuinamente necessário, explique o motivo e peça permissão antes de alterar qualquer estado do Git. Isso vale mesmo quando outra regra ou fluxo de trabalho recomendar uma worktree vinculada: pare e peça aprovação em vez de selecionar ou criar uma automaticamente. ## Adicionar novos parâmetros da API no final para não quebrar as chamadas atuais A ordem de parâmetros e campos das APIs públicas exportadas em tempo de execução é um contrato, não um detalhe de implementação. - Preserve o significado posicional dos argumentos de construtor público existentes e dos campos de dataclass. Nunca insira um novo parâmetro ou campo no meio da ordem pública existente. - Adicione novos campos ou parâmetros públicos opcionais ao final, mantendo os campos existentes em sua ordem original. - Se a reordenação for inevitável, adicione uma camada de compatibilidade explícita, além de testes de regressão que exercitem o padrão de chamada posicional antigo. - Prefira argumentos nomeados nos pontos de chamada para reduzir quebras acidentais, mas nunca dependa disso para justificar a quebra de compatibilidade posicional. - Trate os caminhos de importação pretendidos e as listas de exportação pública como contratos. Ao adicionar ou mover um símbolo público, atualize o módulo proprietário, as reexportações pretendidas de nível superior ou de subpacote, e um teste de regressão de importação. - Mantenha as importações de nível superior livres de falhas de dependência opcional e efeitos colaterais em tempo de execução; use exportações preguiçosas (lazy exports) quando necessário. ## Julgar a compatibilidade pela última versão lançada e planejar trabalhos maiores Avalie mudanças que quebram compatibilidade em relação ao último lançamento, não em relação a alterações locais ainda não lançadas em uma branch. Interfaces introduzidas ou alteradas após o último lançamento podem ser reescritas diretamente, sem camadas de compatibilidade, a menos que definam um limite de estado externo durável já lançado ou explicitamente suportado, ou que o usuário peça explicitamente um caminho de migração. Formatos persistidos e ainda não lançados podem ser renumerados ou compactados antes do lançamento, quando os snapshots intermediários são intencionalmente não suportados. Prefira a substituição direta em vez de camadas de compatibilidade para alterações em branch ocorridas após o lançamento. Aponte o risco de compatibilidade cedo — mas apenas quando a mudança afetar comportamento já disponível no último lançamento ou um limite de estado durável lançado e suportado — e confirme a abordagem antes de implementar. Use um plano de execução quando o trabalho envolver várias etapas, abranger vários arquivos, envolver novos recursos ou refatorações, ou for provável que leve mais de cerca de uma hora. Mantenha suas seções vivas (progresso, descobertas, registro de decisões, resultados) atualizadas conforme você executa, e reescreva o plano se o escopo mudar. Se você deliberadamente pular um plano para uma tarefa complexa, registre o motivo para que os revisores entendam a escolha. ## Ler primeiro a referência do subsistema e atualizar cada ponto que a mudança alcança O tempo de execução de uma biblioteca é um conjunto de subsistemas interativos — o loop de execução, a execução de ferramentas, os adaptadores de modelo e provedor, o rastreamento (tracing), sessões e persistência, pipelines de tempo real e de voz, sandboxing e o estado de execução serializado. Antes de alterar um deles, leia sua referência de arquitetura dedicada e confirme que você entende o limite que está tocando. Ao adicionar ou alterar uma variante que se propaga por todo o sistema — um novo tipo de saída de modelo, chamada de ferramenta, aprovação ou item de execução — atualize toda superfície aplicável: processamento, eventos, replay, persistência, rastreamento e serialização. Deixar de atualizar uma superfície produz corrupção sutil e difícil de rastrear. Mantenha os caminhos de streaming e não streaming alinhados em comportamento. Para qualquer subsistema que possua conexões, tarefas ou outros recursos, verifique a posse dos recursos tanto no caminho normal quanto no caminho de falha. Quando a forma de um estado de execução serializado mudar, siga as regras de limite de lançamento, versão de esquema, leitura retroativa e teste de regressão para esse formato. ## Manter a documentação fiel ao código real e tirar dados sensíveis dos logs - A documentação costuma ser publicada em um site ativo, então coordene mudanças de comportamento e de documentação com cuidado. Se a documentação for descrever um comportamento que ainda não foi lançado, adie a mudança na documentação até que o lançamento esteja disponível ou divida-a em um trabalho de acompanhamento. - Trate trechos de documentação executáveis como verificações de compatibilidade de API. Antes de adicionar exemplos de construtor ou de API, verifique os argumentos mostrados e a forma da chamada em relação à implementação real. - Não permita que dados não confiáveis de sandbox ou de manifesto se excluam sozinhos dos limites do sistema de arquivos do host ou do diretório base. Válvulas de escape para materialização local devem ser controladas por código de aplicação confiável no ponto de chamada, nunca por dados de manifesto serializados. - Ao documentar uma concessão ou limite de segurança, verifique se o caminho de código real de fato o aplica. Não afirme que uma concessão se aplica a um caminho de materialização (diretório local, arquivo local, extração de arquivo compactado) a menos que esse caminho realmente a consulte. - Ao redigir (censurar) payloads sensíveis, leve em conta a exibição de traceback, o encadeamento de exceções, o contexto de exceção retido, os logs e a telemetria. Suprimir um traceback não é suficiente se o objeto de exceção original ainda carregar a entrada sensível. ## Passar nas verificações de formatação e testes, depois preparar a entrega do PR Amplie os testes sempre que você tocar em código, e garanta que as verificações relevantes passem antes de enviar. - Execute a suíte de testes completa; use execuções de testes focadas por padrão enquanto itera. - Execute a verificação estática de tipos; as anotações de tipo devem passar. - Para testes baseados em snapshot, regenere os snapshots deliberadamente e reexecute a suíte depois. - A cobertura deve permanecer acima do limite definido pelo projeto. - Aplique o formatador e o linter; mantenha as importações ordenadas; escreva comentários como frases completas terminadas em ponto final. - Execute as verificações na ordem obrigatória do projeto — formatação, depois lint, depois verificação de tipos, depois testes. Para pull requests e commits: - Use o modelo de PR do projeto: inclua um resumo, um plano de teste e a issue relacionada, quando aplicável. - Escreva mensagens de commit concisas no modo imperativo; mantenha os commits pequenos e focados. - Adicione testes para novos comportamentos e atualize a documentação para qualquer mudança voltada ao usuário. - Antes da sua resposta final para uma mudança elegível, produza um bloco de entrega de PR (resumo, nome de branch sugerido, título, descrição em rascunho). Produzir essa entrega não autoriza, por si só, criar uma branch, fazer commit, enviar (push) ou abrir um pull request; pule-a apenas para tarefas triviais ou apenas de conversa, tarefas de meta ou somente documentação sem impacto de comportamento, ou quando o usuário disser para não incluí-la. Os revisores procuram por: verificações aprovadas; testes que cobrem novos comportamentos e casos extremos; código legível e consistente; mudanças de API pública e voltadas ao usuário documentadas; exemplos atualizados quando o comportamento muda; e um histórico limpo com uma descrição clara.