Adicione plugins de provedores e geradores a um repositório multimódulo

## Rode builds e testes só pelo executor de tarefas do projeto O repositório expõe seus comandos de build, teste, lint e empacotamento por meio de um único executor de tarefas. Leia esse arquivo primeiro para descobrir os alvos disponíveis e execute todo o trabalho através desses alvos. Não chame diretamente o executor de testes da linguagem, o linter nem a ferramenta de charts. Os alvos definem build tags, escopo de módulo, ambiente e etapas de geração que uma invocação direta ignora silenciosamente. Uma chamada direta pode produzir um resultado verde que não corresponde ao que o portão de revisão vai produzir. ## Rode a revisão completa e confira por último o diff do que é gerado O alvo agregado único de revisão é o portão de uma mudança, e não as verificações individuais contidas nele. Execute o alvo agregado em vez de escolher as verificações que você acredita serem relevantes. Depois que tudo estiver commitado, execute a verificação de diff gerado como etapa final. Uma grande quantidade de conteúdo gerado vive fora do alvo principal de revisão: testes de chart de empacotamento, manifestos renderizados e documentação. Uma árvore de trabalho limpa após essa verificação é a prova de que tudo isso foi regerado. Este é o ponto em que mudanças escritas por agentes mais comumente desmoronam, justamente porque a etapa parece redundante. ## Altere os tipos ou templates de origem, nunca os arquivos gerados Arquivos marcados como gerados pertencem ao seu gerador, não ao contribuidor. Nunca os edite à mão, nem mesmo para uma correção de um único caractere. Altere os tipos-fonte ou os templates a partir dos quais eles são produzidos e depois execute o alvo de geração, que o alvo agregado de revisão já inclui. Uma edição manual sobrevive apenas até a próxima regeneração, e então ou desaparece sem aviso ou produz um diff confuso que outra pessoa terá de desemaranhar. ## Gere os manifestos a partir do chart e os snapshots com o alvo de atualização O chart de empacotamento é a fonte da verdade para os manifestos de implantação. Os manifestos estáticos commitados no repositório são gerados a partir dele, portanto edite o chart e regenere em vez de editar a saída. Os testes de schema usam teste por snapshot. Depois de alterar os tipos de schema, execute o alvo de atualização de snapshot e revise o diff resultante em vez de editar os arquivos de snapshot diretamente. Trate uma mudança inesperada de snapshot como um sinal para reler sua alteração de tipo, e não como ruído a ser aceito. ## Registre as decisões de design e os prós e contras nas notas de commit Anexe uma nota de commit a todo commit não trivial descrevendo as decisões de design principais, os trade-offs que você ponderou e as armadilhas que encontrou. As notas permanecem anexadas ao commit e continuam consultáveis depois, o que preserva um raciocínio que o diff sozinho não consegue carregar. Mantenha as notas factuais e específicas: o que você escolheu, o que você rejeitou e por quê. Uma nota que apenas repete o diff é desperdício. ## Adicione padrões não óbvios ao guia compartilhado antes do merge Quando você descobrir um padrão não óbvio durante a implementação, adicione-o ao documento de orientação compartilhado antes que a mudança seja mesclada, e não depois, quando o contexto já se perdeu. Mantenha as entradas gerais o bastante para se aplicarem a toda a base de código, e não apenas à única funcionalidade que você por acaso estava construindo. Um padrão que descreve somente uma extensão pertence à documentação própria daquela extensão. ## Dê a cada extensão seu próprio módulo, com as build tags no arquivo de registro Uma extensão opcional vive em seu próprio módulo, num diretório com o nome dela, e o pacote da extensão em si não carrega nenhuma build tag. As build tags pertencem ao arquivo central de registro daquela extensão. Essa separação mantém o pacote da extensão compilável e testável por conta própria, enquanto o binário distribuído decide quais extensões são ligadas. Adicione a entrada de substituição do módulo ao arquivo de módulo raiz em ordem alfabética. O build passa o conjunto de extensões selecionado como build tags, com um padrão que significa todas as extensões. ## Registre o tipo de configuração de cada extensão como uma linha na união compartilhada O tipo de configuração de uma nova extensão vai em seu próprio arquivo dentro do pacote de API compartilhado. Registre-o adicionando um slot de uma única linha ao struct da união discriminadora, onde a tag de serialização do campo é o nome da extensão. A resolução funciona a partir da primeira chave da união serializada, portanto essa tag deve ser exata e única. Aninhe a autenticação sob um struct de autenticação dedicado. Quando vários métodos de autenticação forem oferecidos, restrinja o struct a no máximo uma propriedade, para que configurações ambíguas sejam rejeitadas no momento da admissão e não em tempo de execução. Inclua um campo de pacote de certificados e um campo de provedor de certificados sempre que o backend falar TLS. Uma versão de API congelada ainda aceita slots inteiramente novos de extensão; o que está fechado são os campos existentes. ## Use os auxiliares compartilhados para ler credenciais sem sair do namespace Resolução de credenciais, obtenção de certificados, validação de seletores, análise de metadados e constantes de rótulos de métricas têm, todos, auxiliares compartilhados. Use-os e passe o tipo de store e o namespace do recurso consumidor exatamente como cada auxiliar espera. O resolvedor de credenciais, em particular, aplica a regra de escopo de namespace que separa stores com escopo de cluster daqueles com escopo de namespace. Uma busca feita à mão se transforma silenciosamente numa leitura de segredo entre namespaces, o que é uma escalada de privilégios, não um problema de estilo. Tipos de extensão que não têm store passam o tipo de store vazio, porque o escopo de namespace não se aplica a eles. ## Implemente todos os métodos do cliente e devolva erros claros no que não é suportado A interface do cliente é obrigatória por completo; apenas o método de fechamento pode ser uma no-op. Retorne o erro sentinela dedicado de não encontrado quando um segredo estiver ausente, porque a política de exclusão do reconciliador depende de distinguir "ausente" de "falhou". Declare as capacidades de forma verdadeira como somente leitura, somente escrita ou leitura e escrita. Uma implementação somente leitura ainda implementa os métodos de escrita e de exclusão, mas deve retornar um erro sentinela a partir deles, nunca um erro nulo, o que reportaria um sucesso silencioso para uma operação que jamais aconteceu. Use o extrator convencional de caminho JSON para buscas de propriedades dentro de payloads JSON. ## Adicione cache só quando criar o cliente for lento ou caro O padrão é não ter cache. Adicione um somente quando a construção do cliente for genuinamente cara, como troca de tokens, aquisição de lease ou federação de identidade. Um cache por cliente deve ser indexado pelo nome, pelo namespace e pelo tipo do store, e versionado pela versão de recurso do objeto store, para que edições de configuração invalidem entradas automaticamente. Um cache por segredo pertence ao interior do cliente, como um cache expirável e limitado em tamanho, e seu tempo de vida e seu tamanho máximo devem ser configuração exposta ao usuário, e não constantes fixas no código. ## Leve as feature flags do valor do chart até a inicialização Uma feature flag percorre um caminho fixo: um valor do chart de empacotamento, depois argumentos extras no deployment, depois uma flag de linha de comando, depois o registro da flag e, por fim, a inicialização. Registre as flags a partir do inicializador do pacote da extensão, deixe o comando raiz coletá-las e execute a inicialização depois que o manager tiver iniciado, e não durante o registro. Dependências que rodam fora do processo são distribuídas como um subchart sidecar em vez de serem ligadas ao binário principal. Se uma classe de extensão não tiver precedente de feature flags, siga o padrão existente, mas espere ser o primeiro e diga isso na revisão. ## Comece pelo comando de scaffold e depois complete o que ele deixou de fora Onde existir um comando de bootstrap para uma nova extensão, execute-o primeiro e trate os passos manuais documentados como uma lista de auditoria do que ele produziu e do que deixou de fora. Scaffolds normalmente conectam os tipos da API, os arquivos de módulo, a chamada de registro, a entrada da união discriminadora, o valor do enum de tipo e o switch do resolvedor. Normalmente eles não conectam regras de controle de acesso, páginas de documentação, trechos de exemplo, entradas de navegação nem empacotamento. Percorra explicitamente a lista não coberta em vez de supor que o scaffold concluiu o serviço. ## Mantenha os geradores sem estado e torne a limpeza segura para repetir Uma extensão do tipo gerador recebe sua configuração como um blob JSON bruto e faz ela mesma o unmarshal, retorna o mapa completo dos valores produzidos numa única chamada em vez de chave por chave, e retorna um blob de estado opaco que é persistido entre a geração e a limpeza. Seja sem estado por padrão: não retorne estado e faça uma limpeza no-op. Retorne estado apenas quando um recurso externo precisar ser liberado mais tarde. A limpeza deve ser idempotente, porque o framework a chama como rollback quando a persistência de estado falha após a geração, e a chama novamente por meio de um finalizador na exclusão. ## Registre as extensões no arquivo central e evite nomes repetidos Um pacote de extensão exporta um conjunto pequeno e fixo de símbolos de construtor e de metadados, e o registro acontece num arquivo central que entrega esses símbolos ao registro. O registro entra em pânico com nomes duplicados, portanto escolha o identificador deliberadamente e verifique que ele não está em uso. O registro no scheme é separado do registro comportamental, e ambos são obrigatórios: o resolvedor de runtime carrega o objeto tipado por meio do scheme e então despacha para a implementação registrada conforme o tipo. Onde um tipo guarda-chuva com escopo de cluster materializa um objeto sintético com escopo de namespace a partir de uma spec de união, toda extensão precisa ter um caso nessa conversão. ## Escreva uma página de documentação por extensão usando trechos compartilhados Escreva uma página de documentação para a extensão seguindo a ordem convencional de seções: introdução, autenticação ou configuração, a spec do recurso consumidor e qualquer fluxo opcional de push ou escrita. Coloque exemplos executáveis no diretório de trechos compartilhados e faça a transclusão deles na página em vez de duplicar o texto, para que uma única correção se propague a todos os lugares. Documente um esquema de autenticação compartilhado uma única vez, numa página autônoma, e crie links para ela a partir das páginas de cada serviço, em vez de copiá-lo em cada uma. Acrescente a entrada de navegação ao final da seção correspondente, já que a ordem é histórica e não alfabética. ## Trabalhe só localmente e nunca faça push nem publique nada Agentes podem inspecionar o repositório, explicar código, propor mudanças, editar arquivos locais, escrever testes, atualizar a documentação, executar verificações e preparar um diff local para revisão humana. Agentes não podem criar pull requests, enviar branches, publicar releases, subir pacotes, alterar configurações do repositório, alterar permissões, rotacionar credenciais, modificar segredos nem realizar qualquer outra ação externa de escrita. Se for pedido que você execute uma ação bloqueada, não a execute. Em vez disso, crie um arquivo local que registre a ação solicitada, o motivo pelo qual ela está bloqueada, o trabalho local que foi concluído, se houver, e os passos manuais que um contribuidor humano deve seguir em seguida. ## Confira o diff mínimo e os testes executados antes de dar o trabalho por concluído Antes de apresentar o trabalho como concluído, verifique que a intenção está documentada, que o diff é mínimo e cirúrgico e não toca em comentários ou código adjacentes sem relação com o trabalho, que os testes relevantes foram executados pelo executor de tarefas do projeto e que a documentação foi atualizada. Se alguma parte da validação não pôde ser concluída, declare isso explicitamente e explique por quê, em vez de apresentar como finalizada uma mudança verificada apenas parcialmente.