Adicione recursos a um serviço Go extensível com testes que resistam à sobrescrita da configuração

## Descubra qual pacote é dono da mudança antes de editar Classifique a alteração e localize a fonte oficial antes de modificar o código. - Identifique o ponto de entrada do comando, os pacotes de domínio, a camada de configuração, a camada de transporte e autorização, a implementação do protocolo, a camada de saída, o registro de capacidades e os metadados de versão. - Mantenha a lógica de negócios nos pacotes de código-fonte responsáveis por ela, não no encadeamento de comandos nem nos adaptadores de distribuição. - Trate os diretórios de pacotes de linguagem e instaladores como adaptadores leves para distribuição de binários; altere-os somente em trabalhos de empacotamento ou versão. - Leia as definições de compilação, a configuração de testes, as implementações próximas e a documentação voltada ao usuário que regem a área afetada. - Antes de editar, diferencie as fontes criadas manualmente dos arquivos gerados e artefatos de compilação. - Liste todos os manipuladores, tipos públicos, pontos de registro, caminhos de configuração, testes, documentos e superfícies de pacotes afetados. Use a estrutura e as convenções de nomenclatura estabelecidas pelo repositório em vez de introduzir uma estrutura paralela. ## Registre logs pelo wrapper de contexto para mantê-los ligados aos traces Use o adaptador de registro contextual do repositório sempre que o código de produção emitir um registro. - Propague o contexto da solicitação até o ponto em que ocorre o registro; adicione um parâmetro de contexto quando a cadeia de chamadas ainda não transportar um. - Não chame diretamente o registrador de contexto básico do framework quando o adaptador enriquecer os registros para correlação de telemetria. - Se uma função iniciar um novo segmento de rastreamento, obtenha novamente o registrador contextual depois que o segmento começar; um registrador capturado anteriormente retém o contexto do segmento anterior. - Mantenha os valores estruturados vinculados ao contexto ativo para que a ponte de registro possa associar os registros ao rastreamento correto. - Verifique e trate todo erro retornado no código de produção em vez de descartá-lo. - Preserve os limites estabelecidos pelo repositório para ocultação de dados, autorização e observabilidade ao adicionar diagnósticos. Verifique a correlação e o comportamento de erros por meio de resultados observáveis, em vez de depender apenas da presença de uma instrução de registro. ## Adicione novas ferramentas com handler, grupo e registro Projete uma nova capacidade antes de implementá-la: confirme seu nome, agrupamento, esquema de entrada, comportamento e cobertura de avaliação. 1. Implemente o manipulador responsável pela lógica da capacidade. 2. Defina o contrato público da ferramenta ou do comando e conecte-o ao manipulador. 3. Adicione a capacidade ao grupo apropriado ou crie um grupo específico quando nenhum for adequado. 4. Registre um novo grupo pelo caminho de inicialização do repositório. 5. Atualize em conjunto os testes de comportamento, as referências de configuração, os catálogos gerados e a documentação do usuário. Mantenha cada grupo de capacidades em seu próprio diretório sob responsabilidade definida. Evite caminhos de registro duplicados ou nomes que exponham detalhes internos de implementação. ## Use os targets de build declarados e só faça deploy se pedirem Use os alvos de compilação declarados pelo repositório em vez de reconstruir comandos de memória. - Antes de executar, saiba qual alvo de compilação formata o código-fonte, organiza os módulos, compila uma plataforma ou gera todas as plataformas compatíveis. - Inspecione as diferenças resultantes, pois um alvo de compilação pode reescrever intencionalmente metadados de dependência ou arquivos gerados. - Mantenha organizadas as declarações de dependência após introduzir um módulo e execute o alvo de análise estática na versão fixada pelo repositório. - Preserve os modos compatíveis de execução local e remota, incluindo a precedência documentada entre sinalizadores explícitos, variáveis de ambiente, arquivos padrão e configuração interna ao cluster. - Documente alvos de teste ou lint que baixem ferramentas ou ambientes no primeiro uso; a falta de acesso à rede pode causar falhas de preparação, não falhas de código. - Mantenha leves os adaptadores do gerenciador de pacotes e sincronizados com o binário compilado, em vez de duplicar a lógica do serviço. Trate alvos que baixam, publicam, enviam ou implantam como limites de operações externas. Primeiro inspecione seus contratos e nunca publique nem implante, a menos que a tarefa inclua explicitamente um trabalho de lançamento. ## Teste o comportamento público e os casos-limite, não funções privadas Exercite a API pública como uma caixa-preta e, quando viável, prefira implementações reais ou testes de integração. - Organize os testes segundo a convenção de conjuntos do repositório e forneça a cada arquivo de teste um conjunto correspondente. - Use subtestes aninhados para agrupar cenários relacionados e dê a cada caso um nome descritivo baseado no comportamento. - Idealmente, faça cada caso comprovar um único comportamento com uma asserção específica. - Cubra caminhos bem-sucedidos, retornos de chamada, mudanças de estado e saídas observáveis sem vincular os testes a funções privadas. - Adicione casos extremos para valores nil ou null, coleções vazias, índices inválidos, incompatibilidades de tipo, entradas malformadas e caminhos de erro. - Use asserções de pré-requisito para operações de preparação que precisem ser concluídas com êxito e depois verifique explicitamente os erros ou valores esperados. - Nunca ignore um erro apenas para manter um teste conciso. Para um defeito, comece com um teste específico que falhe, execute o pacote ou conjunto afetado após a correção e termine com o alvo completo de testes exigido pelo repositório. ## Faça os testes de configuração passarem mesmo com padrões e nomes sobrescritos Os testes de configuração devem continuar válidos quando compilações subsequentes sobrescreverem valores padrão, nomes de funcionalidades ou conjuntos de capacidades habilitadas. - Inicie os conjuntos comuns de testes com uma configuração base sem sobrescritas e depois sobreponha as definições específicas do teste. - Para configurações simples, mescle os valores decodificados à configuração existente do conjunto, de modo que permaneçam intactos os campos de execução já definidos pela infraestrutura de testes. - Quando uma seção armazenar valores adiados ou primitivos, use o leitor bifásico sensível a metadados exigido para analisar essas seções por completo. - Após uma leitura completa da configuração, restaure explicitamente os campos exclusivos de execução, como caminhos de conexão, opções de saída e estado somente leitura. - Para testes de recarga, construa deliberadamente o candidato a partir dos padrões sensíveis a sobrescritas usados pelo serviço em execução e depois herde os campos de execução ativos. - Acrescente as capacidades obrigatórias à lista existente; nunca substitua a lista por padrões da origem meramente presumidos. - Resolva dinamicamente nomes públicos passíveis de mudança de marca, mas mantenha fixa a chave literal de registro de um analisador quando o contrato dele assim exigir. - Nunca codifique rigidamente em asserções valores padrão, nomes públicos ou conjuntos de funcionalidades sujeitos a sobrescritas. Sempre que alterações de configuração cruzarem esses limites, teste tanto o comportamento base quanto pelo menos um caminho com sobrescrita. ## Reúna os helpers de teste em um só lugar e separe falhas de preparação Coloque auxiliares genéricos de teste na área interna compartilhada de testes do repositório e documente-os com propósito, entradas e exemplos claros. - Mantenha os auxiliares independentes de uma única funcionalidade para que vários pacotes possam reutilizá-los. - Prefira interações realistas de usuário ou protocolo a atalhos de baixo nível que contornem o comportamento de produção. - Explicite os pré-requisitos dos testes, incluindo simuladores locais de cluster, ambientes baixados, credenciais ou acesso necessário à rede. - Diferencie uma falha de preparação de uma falha do produto nos diagnósticos. - Busque uma cobertura elevada da API pública, especialmente de condições de limite e caminhos de falha, sem inflar métricas com casos de pouco valor. - Mantenha a configuração de testes, os aliases e os dados de teste gerados alinhados ao executor de testes ativo. Quando houver personalização subsequente, inclua testes representativos para capacidades renomeadas, padrões alterados e recargas de configuração. ## Atualize a documentação pelo gerador e mantenha os pacotes na mesma versão Atualize toda superfície oficial afetada por uma alteração de código ou configuração. - Use nomes de arquivo em letras minúsculas para a nova documentação quando essa for a convenção do repositório. - Atualize índices, referências de configuração e guias de instruções de entrada, registro, observabilidade, autenticação e integração conforme o impacto da funcionalidade. - Trate tabelas geradas e seções de referência como conteúdo gerado; preserve seus pares de marcadores e atualize-as por meio do gerador aprovado. - Não edite diretamente as seções geradas nem registre artefatos de compilação no controle de versão, a menos que a política do repositório exija isso explicitamente. - Mantenha binários nativos, imagens de contêiner e adaptadores de pacotes de linguagem alinhados ao mesmo comportamento versionado do serviço. - Execute as verificações documentadas de compilação, teste, lint, geração de documentação e empacotamento específico que forem relevantes para a alteração. Antes de apresentar a alteração, confirme que as diferenças finais contenham somente atualizações pretendidas de código-fonte, testes, documentação e pacotes. Execute alvos de lançamento ou publicação apenas quando a tarefa os incluir explicitamente e informe quaisquer verificações mais amplas deixadas deliberadamente fora do escopo.