Alterar um grande monorrepositório de fluxos de trabalho em Python sem quebrá-lo

## Encontrar o pacote responsável e suas instruções antes de editar Use, no texto, a terminologia canônica do domínio do projeto. Preserve identificadores literais, comandos, caminhos, chaves de configuração e nomes de compatibilidade exatamente como o código exige; não os reescreva apenas por coerência estilística. Antes de editar: - Identifique o pacote responsável, suas instruções locais e o guia de arquitetura ou testes mais próximo. - Use o executor de desenvolvimento e testes gerenciado pelo projeto, em vez de invocar diretamente as ferramentas do sistema anfitrião. - Instale os ganchos do repositório ou os adaptadores de comandos por meio do procedimento documentado de configuração única. - Coloque scripts auxiliares temporários somente na área de desenvolvimento montada designada e remova-os quando a tarefa estiver concluída. - Selecione as verificações de acordo com os arquivos e pacotes realmente alterados. Trate arquivos de bloqueio de dependências gerados e artefatos semelhantes como saídas de um gerador oficial, nunca como código-fonte a ser editado manualmente. ## Impedir que o agendador execute código de fluxos e que os processos de trabalho acessem o banco de dados direto Compreenda o fluxo de dados antes de alterar o código de orquestração: 1. Os autores definem fluxos de trabalho por meio do SDK público. 2. Processadores isolados analisam essas definições e armazenam de forma persistente os dados serializados dos fluxos de trabalho. 3. Os agendadores leem os dados serializados e não devem executar código de fluxos de trabalho fornecido pelos autores. 4. Os processos de trabalho executam tarefas por meio do SDK ou da API compatíveis e não devem acessar diretamente o banco de dados de metadados. 5. Os serviços de API intermedeiam as interações da interface do usuário e dos clientes com o estado persistente. 6. Os serviços de acionamento de eventos são executados separadamente dos agendadores e dos processos de trabalho. Use credenciais de curta duração e escopo estritamente limitado entre os componentes. Verificações de software que desencorajam o acesso direto ao banco de dados são proteções úteis, mas não constituem um limite de segurança contra código deliberadamente malicioso. Classifique qualquer possível problema de segurança antes de propor uma correção: - Uma violação explorável do modelo de confiança documentado é uma vulnerabilidade. - Um comportamento já declarado como externo ao modelo de confiança é uma limitação conhecida. - Uma opção de implantação mais segura que não repara uma garantia violada é uma orientação de reforço da segurança. Mantenha essas categorias distintas para que a gravidade e a medida corretiva correspondam ao risco real. ## Colocar cada dependência no pacote que a importa Trate o monorrepositório como um conjunto de distribuições relacionadas, e não como um único pacote indiferenciado. A orquestração central, os SDKs públicos, as integrações com provedores, as ferramentas de linha de comando, os modelos de implantação, as ferramentas de desenvolvimento e os scripts podem ter ciclos de lançamento e regras de dependências diferentes. Para uma biblioteca compartilhada: - Mantenha sua API pequena e independente. - Dê a ela sua própria árvore de código-fonte, testes, configuração e dependências declaradas. - Use os vínculos de espaço de trabalho oferecidos pelo repositório em vez de duplicar código. - Teste a própria biblioteca e cada componente consumidor diretamente afetado. Coloque cada dependência na distribuição que a importa. Quando uma alteração ultrapassar os limites entre pacotes, verifique tanto a direção das importações quanto a responsabilidade pelo lançamento antes de modificar manifestos. Gere novamente os arquivos de bloqueio com o fluxo de trabalho compatível e examine a variação resultante nas dependências para detectar mudanças alheias. ## Escrever código Python claro e manter cada alteração pequena Formate e faça a análise estática de cada arquivo Python alterado enquanto a mudança ainda for pequena. Mantenha explícito o comportamento em produção: - Não use asserções para validação em tempo de execução nem para tratar erros recuperáveis. - Escreva comentários que expliquem restrições ou intenções, não que apenas narrem o código. - Meça durações com um relógio monotônico. - Mantenha as importações no escopo do módulo, exceto nos casos documentados de dependências circulares, carregamento tardio ou dependências opcionais. - Proteja importações custosas usadas apenas para verificação de tipos, para que elas não afetem o início da execução. - Lance a exceção significativa de menor abrangência; não introduza uma exceção-base genérica que capture tudo. - Converta falhas do domínio em respostas específicas de protocolo somente no limite de transporte. - Dê nomes com verbos de ação às funções e preserve o cabeçalho de licença obrigatório. Prefira uma alteração pequena e fácil de revisar a uma refatoração oportunista. Se uma limpeza não for necessária para o comportamento solicitado, deixe-a para uma alteração separada. ## Gravar no banco de dados em lotes pequenos para não deixar o agendador lento Funções que recebem uma sessão de banco de dados não devem confirmar a transação implicitamente. Transforme a sessão em um argumento exclusivo por palavra-chave quando o código-base adotar essa convenção e permita que o responsável pela transação decida quando confirmá-la ou revertê-la. Evite gravações em massa sem limite dentro de ciclos do agendador ou de manutenção: 1. Filtre por colunas indexadas. 2. Processe um lote de tamanho limitado. 3. Confirme ou libere a transação entre os lotes. 4. Continue até não restarem linhas elegíveis. Isso limita a duração dos bloqueios, o crescimento da memória e a privação de recursos de outros trabalhos do agendador. Confirme o comportamento no banco de dados padrão e execute testes de cobertura com sistemas alternativos de banco de dados quando a consulta alterada depender de uma semântica específica do sistema. Nunca trate um comando de limpeza destrutiva como uma medida rotineira de diagnóstico. Determine o alvo exato e obtenha a aprovação exigida antes de excluir bancos de dados, volumes, caches ou dados de usuários. ## Escrever primeiro um teste que falha e ampliar os testes só quando preciso Comece com um teste que expresse o comportamento exato a ser alterado e confirme que ele falha sem a implementação. Em seguida, faça a menor mudança que leve o teste a passar. Use a estrutura de testes e os recursos auxiliares preferidos pelo repositório: - Reproduza a organização do código-fonte na árvore de testes. - Use dublês de teste vinculados à especificação para que desvios da interface causem falhas claras. - Use os mecanismos compatíveis para sobrescrever a configuração e controlar o tempo. - Parametrize variações relevantes de entradas e mecanismos de banco de dados. - Marque os testes de banco de dados com precisão e mantenha os demais testes independentes da configuração do banco. - Verifique nomes e campos estruturados de eventos, em vez de textos de registro renderizados e instáveis. Não teste isoladamente a biblioteca padrão nem uma dependência de terceiros. Teste o comportamento de integração que é responsabilidade deste código. Execute primeiro um teste específico; depois, o conjunto de testes do pacote afetado, a verificação estática de tipos e a análise estática. Execute conjuntos mais amplos somente quando a abrangência das dependências os justificar. ## Atualizar juntas as regras de CI e a documentação, com notas de versão só para mudanças visíveis Quando o comportamento seletivo da integração contínua mudar, atualize em conjunto a lógica de seleção, os testes correspondentes e a documentação. Uma regra que existe apenas no código ou apenas no texto está incompleta. Adicione metadados de lançamento somente para alterações visíveis ao usuário na distribuição que fornece o comportamento. Refatorações internas, trabalho restrito a testes, ferramentas de desenvolvimento e manutenção não visível ao usuário normalmente não exigem uma nota de lançamento. Use os geradores do projeto para arquivos de bloqueio, referências de comandos, esquemas e outra documentação gerada. Examine as diferenças geradas, mas não altere arquivos gerados para ocultar um problema na fonte oficial. Antes da entrega, execute as verificações pertinentes de formatação, análise estática, tipos, testes, documentação e seleção. Registre qualquer etapa de verificação omitida intencionalmente e o motivo concreto pelo qual ela não se aplicava. ## Revisar todo o diff e abrir uma solicitação de integração a partir da sua bifurcação Revise a diferença completa da tarefa antes de publicar. Confirme que os limites arquitetônicos, as premissas de segurança, os testes, as saídas geradas, os metadados de lançamento e as instruções locais sejam coerentes entre si. Pergunte antes de fazer uma grande refatoração entre pacotes, adicionar uma dependência de ampla abrangência, alterar o comportamento de uma migração destrutiva ou realizar uma publicação externa que ainda não tenha sido autorizada. Nunca exponha segredos, contorne ganchos obrigatórios, edite manualmente arquivos gerados nem execute comandos destrutivos de controle de versão sem aprovação explícita. Antes de qualquer operação remota: - Inspecione os repositórios remotos configurados e confirme qual é o repositório oficial e qual é a bifurcação do colaborador. - Não envie alterações diretamente ao repositório remoto oficial nem à sua ramificação padrão protegida. - Pergunte antes de renomear ou reescrever repositórios remotos quando as funções deles não estiverem claras. - Procure uma solicitação de integração existente para que o trabalho não seja duplicado. - Reposicione as alterações sobre a ramificação de destino atual ou sincronize-as de outra forma por meio do fluxo de trabalho aceito pelo repositório. Use um título em linguagem simples, no imperativo e centrado no impacto para o usuário. Explique no corpo por que a alteração é necessária, declare a assistência de IA quando exigida e inclua referências aos chamados pertinentes. Não se adicione como coautor nem marque pessoas, a menos que o usuário tenha autorizado ou que elas já participem da discussão. Se uma correção completa estiver pronta, prefira a solicitação de integração em vez de abrir um chamado duplicado. Se a alteração for apenas uma solução alternativa, uma medida de mitigação ou uma correção parcial, crie ou vincule um chamado de acompanhamento e faça referência a ele tanto na solicitação de integração quanto próximo ao código temporário.