Altere um repositório com vários módulos e código gerado sem passar do que foi aprovado

## Leia as instruções da raiz e de cada pasta antes de editar Comece localizando as orientações do repositório que regem os arquivos que você pode alterar. Trate a documentação do projeto e os arquivos de instruções aninhados como a autoridade para as convenções locais, em vez de presumir padrões genéricos do ecossistema. - Leia as orientações da raiz e quaisquer instruções mais específicas no diretório de destino. - Revise a visão geral do repositório, o guia de contribuição, a configuração de desenvolvimento, as orientações de testes e a documentação de publicação relevantes para a tarefa. - Siga a instrução aplicável mais próxima quando houver divergência entre as orientações gerais do repositório e as específicas do módulo. - Consulte as políticas referenciadas nos arquivos mantidos pelo projeto, em vez de confiar em comandos lembrados. - Identifique os arquivos de responsabilidade e as pessoas encarregadas de revisar a área afetada. - Determine o fluxo de trabalho compatível, as aprovações necessárias e as expectativas de validação antes de editar. - Pergunte somente quando as fontes oficiais entrarem em conflito ou quando uma decisão com consequências importantes permanecer sem solução. ## Descubra qual módulo é dono da mudança e quem a revisa Entenda como a base de código está dividida antes de escolher onde implementar um comportamento. Em um repositório com vários módulos, os limites de compilação, os manifestos de dependências, as áreas geradas, os exemplos, os testes e as unidades de publicação podem variar conforme o diretório. - Localize o módulo responsável pelo comportamento público e os componentes de baixo nível dos quais ele depende. - Diferencie a implementação escrita manualmente do código gerado, dos modelos, das especificações, dos dados de teste e dos exemplos. - Inspecione os manifestos dos módulos para entender os limites das dependências diretas e indiretas. - Use as regras de responsabilidade para identificar quem mantém o código, os serviços e a infraestrutura compartilhada. - Verifique se uma alteração afeta um pacote, uma família de módulos ou uma superfície de compatibilidade compartilhada. - Siga a estrutura de diretórios e os padrões de nomenclatura estabelecidos, em vez de criar estruturas paralelas. - Mantenha os módulos não relacionados fora da alteração, a menos que uma dependência verificada exija atualizações coordenadas. ## Use as versões de ferramentas e os comandos de tarefa do projeto Use a cadeia de ferramentas declarada pelo repositório e pelo módulo de destino. A compatibilidade de versões, os executores de tarefas, os geradores e a preparação do ambiente são decisões do projeto, não valores a serem deduzidos da instalação local mais recente. - Confirme nas políticas ou configurações mantidas as versões de linguagem e ferramentas compatíveis no momento. - Prefira as tarefas gerenciadas pelo repositório aos comandos diretos da linguagem quando elas realizarem uma preparação adicional. - Execute comandos a partir do diretório do módulo ou do espaço de trabalho esperado pelo fluxo documentado. - Preserve a seleção do ambiente, as opções de compatibilidade, os recursos gerados e outras preparações realizadas pelas tarefas oficiais. - Instale pré-requisitos globais somente quando o fluxo documentado os exigir explicitamente. - Mantenha as versões do gerador e do compilador alinhadas às versões fixadas ou compatíveis com o projeto. - Informe pré-requisitos ausentes como um impedimento concreto, em vez de alterar silenciosamente o fluxo de trabalho. ## Peça permissão antes de lançamentos, mudanças na CI ou uso de credenciais Agentes podem ler código, explicar comportamentos, propor alterações, implementar edições autorizadas, adicionar testes, melhorar a documentação e ajudar na análise de problemas ou revisões. Operações de maior impacto continuam sujeitas à autoridade humana explícita. - Não acione publicações, aprove etapas de publicação nem publique pacotes sem aprovação. - Não altere a integração contínua, os canais de implantação nem os controles do fluxo de trabalho como parte incidental de outra alteração. - Não modifique licenças, avisos legais nem políticas de conformidade sem autorização explícita. - Não use credenciais, contate serviços externos nem altere estados remotos além da tarefa concedida. - Trate a classificação de problemas, as sugestões de rótulos e a detecção de duplicatas como recomendações, a menos que alterações de estado tenham sido autorizadas. - Pare antes de operações destrutivas ou alterações em ambientes protegidos e solicite a decisão necessária. - Prossiga com a implementação e a validação comuns dentro do escopo sem pedir confirmações desnecessárias. ## Altere a especificação e gere de novo em vez de editar arquivos gerados Pacotes gerados exigem um caminho de alteração diferente do código escrito manualmente. Edições manuais na saída gerada costumam ser sobrescritas e podem separar a implementação da especificação oficial. - Identifique arquivos gerados por meio de marcadores do repositório, manifestos, arquivos de localização ou regras de diretório documentadas. - Não altere manualmente a saída gerada quando o projeto exigir regeneração orientada pela especificação. - Altere a especificação, o modelo ou a entrada do gerador que seja a fonte oficial documentada. - Use o comando de geração indicado pelo projeto e as versões de ferramentas necessárias. - Revise o diff gerado para encontrar arquivos inesperados, alterações de formatação desnecessárias ou mudanças de API não relacionadas. - Mantenha os pontos de extensão manual separados das regiões geradas conforme os padrões do repositório. - Se a regeneração não estiver disponível ou autorizada, explique a limitação, em vez de apresentar uma edição temporária como uma correção duradoura. ## Faça mudanças pequenas que mantenham a compatibilidade com versões anteriores Prefira alterações focadas que sigam as convenções de código existentes e preservem a compatibilidade. Uma modificação pequena e fácil de revisar é mais segura do que uma refatoração ampla quando ambas atendem ao requisito. - Leia as implementações próximas antes de escolher auxiliares, nomes, padrões de erro e localização de arquivos. - Preserve a compatibilidade com versões anteriores, a menos que uma alteração incompatível seja explicitamente aprovada e documentada. - Siga as convenções locais para nomes públicos, siglas, comentários e documentação de APIs públicas. - Use erros descritivos que preservem um contexto útil sem expor informações confidenciais. - Mantenha intactos os avisos obrigatórios de direitos autorais e licenças. - Siga a política de dependências do módulo e evite adicionar uma dependência externa para um comportamento já disponível localmente. - Separe a limpeza não relacionada da alteração solicitada para que as pessoas revisoras possam avaliar claramente a intenção. ## Compile e teste primeiro o módulo afetado e amplie só se preciso Execute primeiro os menores comandos que exercitem o módulo afetado e amplie a validação somente quando o comportamento compartilhado ou a política do repositório exigir. Um comando bem-sucedido só é significativo quando cobre o caminho alterado. - Compile o módulo de destino usando sua tarefa documentada ou o comando correspondente da linguagem. - Execute os testes unitários diretamente relevantes antes das suítes mais amplas de pacotes ou do espaço de trabalho. - Adicione verificações de tipos, análise estática, formatação e validação de arquivos gerados quando o módulo exigir. - Confirme se a seleção de testes realmente incluiu o pacote e os casos pretendidos. - Inspecione as variáveis de ambiente necessárias antes de tentar testes de integração ou em ambientes reais. - Não alegue validação com base em um comando que ignorou alvos ou dependeu de um estado externo indisponível. - Registre os comandos executados, os resultados observados e as verificações que não puderam ser concluídas. ## Escreva testes que não dependam de rede nem de ordem, e exemplos que funcionem Os testes devem comprovar a alteração de comportamento e permanecer confiáveis em diferentes máquinas. Os exemplos devem demonstrar um uso compatível seguindo as convenções do repositório para exemplos executáveis. - Reutilize a biblioteca de asserções e a estrutura de testes já estabelecidas no módulo. - Ao corrigir um defeito, confirme se o novo teste falha pelo motivo pretendido antes de aplicar a correção. - Mantenha os testes unitários independentes de redes, credenciais, estados que mudam com o tempo e ordem de execução. - Armazene os dados de teste no local designado e mantenha-os no mínimo necessário. - Isole as configurações de testes em ambientes reais em arquivos de ambiente autorizados e nunca registre informações confidenciais. - Adicione mensagens às asserções quando melhorarem de modo substancial o diagnóstico. - Coloque os exemplos na estrutura esperada de nomes e pacotes e garanta que sejam compilados ou executados pelo fluxo de testes documentado. ## Atualize a documentação do módulo e o changelog quando o comportamento mudar A documentação faz parte da superfície de implementação. Atualize-a quando, caso contrário, usuários, responsáveis pela manutenção ou ferramentas de publicação receberiam uma visão incompleta ou enganosa da alteração. - Atualize a visão geral do módulo quando a configuração, o comportamento compatível ou o uso público mudar. - Adicione ou revise comentários de API conforme o estilo de documentação do projeto. - Registre alterações visíveis aos usuários no histórico exigido. - Forneça exemplos para novas APIs públicas quando a política do repositório exigir. - Mantenha as instruções de configuração, geração, migração e publicação sincronizadas com os comandos reais. - Verifique se as referências continuam válidas e não direcionam leitores para locais privados ou obsoletos. - Evite alterações desnecessárias na documentação quando o comportamento e o fluxo de trabalho não mudarem. ## Abra a solicitação de mudança a partir da branch aprovada após revisar todo o diff Use o caminho de contribuição aprovado pelo repositório e facilite a inspeção da alteração completa. Uma contribuição deve conectar implementação, testes, documentação e justificativa sem alterar o histórico compartilhado protegido. - Crie o trabalho a partir da branch base aprovada e publique por meio do fork ou remoto autorizado. - Revise o diff completo da branch antes de abrir uma solicitação de alteração. - Use um título descritivo e mencione trabalhos relacionados quando estiverem disponíveis. - Inclua testes que impeçam regressões futuras e a documentação exigida pela política. - Responda aos comentários de revisão com alterações posteriores rastreáveis, a menos que as pessoas responsáveis pela manutenção solicitem outra estratégia de histórico. - Verifique todas as checagens automatizadas obrigatórias e investigue as falhas, em vez de ignorá-las. - Mantenha branches protegidas, branches de publicação e o histórico compartilhado inalterados sem autorização explícita. ## Revise o código em busca de mudanças incompatíveis e erros em arquivos gerados A revisão de código deve priorizar correção, compatibilidade, integridade da geração, qualidade dos testes, segurança e facilidade de manutenção. Aplique as orientações específicas do projeto, em vez de uma lista genérica de estilo. - Verifique se a alteração pertence ao módulo selecionado e segue sua arquitetura. - Procure alterações incompatíveis de API ou comportamento, incluindo mudanças sutis nos valores padrão. - Confirme se os testes cobrem sucesso, falha, limites e repetibilidade quando pertinente. - Confirme se os arquivos gerados vieram da fonte e do fluxo de geração aprovados. - Inspecione as alterações em dependências e manifestos para encontrar violações de políticas ou adições desnecessárias. - Verifique se a documentação e os registros de alterações estão completos e corretos. - Encaminhe os achados às pessoas responsáveis e diferencie defeitos bloqueadores de melhorias opcionais. ## Reporte falhas de segurança em privado e entregue os resultados dos testes Relatórios de segurança, publicações, aprovações de canais, licenças e credenciais exigem tratamento específico. Conclua o trabalho comum com uma entrega baseada em evidências e deixe as operações protegidas sob responsabilidade de pessoas autorizadas. - Relate vulnerabilidades de segurança pelo canal privado do projeto, e não em um problema ou conversa pública. - Nunca inclua segredos, dados de contato privados nem informações sensíveis de reprodução em materiais públicos. - Deixe os acionamentos de publicação, as aprovações de implantação e as decisões sobre licenças para responsáveis pela manutenção explicitamente autorizados. - Explique as decisões importantes de implementação e relacione-as às orientações aplicáveis do projeto. - Resuma os caminhos alterados, os testes realizados, os resultados observados e as limitações restantes. - Identifique as pessoas adequadas responsáveis pelo código ou serviço quando uma revisão adicional for necessária. - Indique claramente quando o acesso externo, ferramentas indisponíveis ou um limite de aprovação impedir uma verificação completa.