Mude um grande monorepo de plataforma e mantenha todos os clientes afetados em sincronia

## Leia as regras da raiz e depois as instruções de cada pasta Use a raiz do repositório como ponto de coordenação e o arquivo de instruções local mais próximo como autoridade específica da tarefa. Aplique primeiro as regras da raiz e depois acrescente as regras mantidas por cada diretório afetado, em vez de presumir que as convenções de um único módulo regem toda a mudança. Nas áreas sem um arquivo de instruções local, use o guia de desenvolvimento mantido mais próximo, o `README` do módulo e o fluxo de integração contínua como as próximas fontes oficiais. Leia todos os guias aplicáveis antes de editar uma mudança transversal. ## Descubra qual módulo cuida de cada parte antes de editar Identifique quais módulos são responsáveis pelo plano de controle, componentes de execução, especificações públicas, bibliotecas de cliente, recursos de implantação, interface de linha de comando, testes de ponta a ponta, documentação, exemplos e propostas de arquitetura. Encaminhe o comportamento do ciclo de vida e da configuração ao responsável pelo plano de controle, o comportamento dos processos de execução ao guia de componente mais próximo, as mudanças de esquema público ao responsável pela especificação, a geração de clientes ao responsável pela biblioteca, o comportamento de implantação ao operador ou responsável pelo empacotamento e o comportamento dos comandos ao responsável pela `CLI`. Para uma mudança que abranja contrato, implementação e clientes, comece pela especificação pública e depois carregue os guias de todos os consumidores afetados. Mantenha as `API` dos componentes, as premissas de teste e a integração da implantação alinhadas ao mesmo contrato. ## Confirme o objetivo e mude só as linhas necessárias Declare as premissas, exponha as ambiguidades e peça orientação quando a solicitação admitir interpretações conflitantes. Antes da implementação, converta trabalhos não triviais em critérios de sucesso observáveis e interrompa quando uma decisão for necessária. Escolha a menor solução que atenda à solicitação. Evite funcionalidades especulativas, abstrações de uso único, configurabilidade desnecessária, refatoração não relacionada e exclusão de trabalho preexistente. Altere somente os arquivos e as linhas exigidos pela tarefa, siga o estilo local, acrescente ou atualize testes específicos quando o comportamento mudar e repita até que as verificações passem ou o impedimento restante esteja explícito. ## Atualize clientes e documentação quando a especificação pública mudar Trate as especificações públicas como fontes oficiais dos contratos. Quando o comportamento visível ao usuário mudar, mantenha sincronizados a especificação, a implementação, as bibliotecas de cliente, a documentação, os exemplos, a configuração, o comportamento dos comandos e os artefatos de lançamento. Quando as `API` de implantação ou os recursos do orquestrador mudarem, também atualize ou verifique os manifestos gerados, os pacotes de implantação, o comportamento do controlador, a integração com o servidor e a documentação operacional. Não permita que um contrato se afaste intencionalmente da implementação sem aprovação explícita. Atualize a documentação voltada a usuários e operações antes da implementação ou junto com ela, para que o comportamento documentado continue sendo a promessa pública vigente. ## Corrija a fonte e gere de novo os arquivos gerados Nunca edite apenas o resultado gerado como forma de correção. Localize e altere o esquema oficial, o modelo, a configuração ou a entrada do gerador e, em seguida, gere novamente todos os clientes, manifestos, materiais de referência, exemplos e artefatos empacotados afetados por meio do fluxo de trabalho suportado. Revise as diferenças geradas em busca de mudanças inesperadas e verifique os consumidores posteriores em relação ao contrato regenerado. Mantenha os adaptadores escritos manualmente separados do código gerado e preserve entre eles o limite de responsabilidade do repositório. Se a nova geração estiver bloqueada, informe a ferramenta ou o ambiente ausente e deixe a fonte e os resultados derivados em um estado incompleto claramente identificado, em vez de apresentá-los como sincronizados. ## Pergunte antes de fazer mudanças públicas incompatíveis Prefira mudanças aditivas e retrocompatíveis para `API` públicas, interfaces de cliente, configuração, protocolos, comportamento de comandos, recursos de implantação, anotações, rótulos e valores de pacotes. Pergunte antes de fazer uma mudança pública incompatível, introduzir um afastamento intencional do contrato ou alterar o comportamento visível sem um caminho claro de migração. Descreva os consumidores afetados, o impacto na compatibilidade, os requisitos de migração e as consequências para o lançamento antes de solicitar aprovação. Nunca oculte uma mudança incompatível em diferenças geradas nem misture trabalho não relacionado de outros componentes na mesma mudança. Mantenha explícita a decisão de compatibilidade aprovada na implementação, documentação, testes e notas da versão. ## Verifique primeiro o menor escopo e depois amplie Execute formatadores, analisadores estáticos, testes unitários, verificações de contrato e asserções da saída de comandos com escopo de arquivo ou pacote antes de uma validação mais ampla. Expanda para compilações de integração, entre linguagens, de implantação ou de documentação quando a mudança atravessar esses limites. Verifique a ajuda e a saída dos comandos junto com os testes da `CLI`, os exemplos de contrato junto com as verificações de esquema, o comportamento dos clientes em todas as linguagens compatíveis e a saída da implantação na plataforma afetada. Atualize testes específicos sempre que o comportamento mudar ou um defeito for corrigido. Mencione na entrega final todas as verificações não executadas ou bloqueadas. Não declare a conclusão enquanto uma verificação obrigatória estiver falhando ou enquanto um consumidor afetado permanecer sem verificação e sem uma limitação explícita. ## Mantenha cada documento em um só lugar e use links em vez de copiar Mantenha orientações detalhadas para usuários e operações na árvore de documentação designada. Reserve o `README` da raiz para o ponto de entrada do repositório e os `README` de pacotes publicáveis para instalação, início rápido e pontos de entrada dos pacotes. Mantenha os `README` de componentes internos no mínimo quando houver uma página de documentação mantida. Armazene exemplos executáveis na árvore de exemplos e suas páginas explicativas na árvore de documentação; use documentos de proposta como autoridade e páginas da comunidade apenas como índices quando essa for a convenção do repositório. Crie links para as políticas da comunidade e de desenvolvimento em vez de duplicá-las. Prefira links relativos à versão nos arquivos do repositório para que a documentação acompanhe a ramificação ou etiqueta selecionada e não use um site público como única fonte a partir do código versionado. ## Siga as regras de páginas do site de documentação e compile sem erros Use o mecanismo de documentação e a configuração do site estático definidos sem introduzir geração não documentada durante a compilação. Coloque as imagens no diretório público de recursos designado e faça referência a elas segundo a convenção de caminhos aprovada pelo site. Forneça a cada página publicada as informações descritivas obrigatórias, use o estilo configurado de links internos e use links completos para o código-fonte ao apontar para fora da árvore de documentação. Aplique de maneira uniforme os avisos em destaque, os grupos de código e as convenções de navegação aprovados. Mantenha fora do site publicado as instruções exclusivas para colaboradores. Acrescente cópias localizadas apenas onde a política de localização permitir e execute a compilação da documentação sem erros antes de considerar concluídas as mudanças prontas para publicação. ## Revise mudanças incompatíveis e informe os riscos que restam Priorize a revisão de mudanças incompatíveis em especificações públicas, interfaces de cliente, configuração, comportamento de comandos, recursos de implantação e protocolos. Sinalize mudanças desnecessárias, internamente inconsistentes, difíceis de implementar pelos consumidores ou sem um caminho de migração confiável. Verifique se há limites rompidos da fonte oficial, violações de camadas, resultados gerados desatualizados, testes ausentes, comportamento não documentado e regressões de compatibilidade. Separe defeitos confirmados de riscos não verificados e cite o contrato ou consumidor afetado. Encerre com um relatório baseado em evidências que abranja áreas alteradas, consumidores sincronizados, verificações executadas, validações bloqueadas, decisões de compatibilidade e riscos restantes.