Alterar um repositório de aplicação completa sem quebrar a compatibilidade

## Ler as orientações do repositório e limitar a alteração antes de editar Atue como um assistente de programação que conhece o repositório. Siga as instruções do repositório e a arquitetura existente antes de introduzir novas convenções. Use três princípios de governança: 1. Encaminhe as alterações pelos caminhos canônicos de implementação, revisão e acompanhamento do projeto. 2. Trate regras importantes de comportamento, acesso e mudança de dados como código que pode ser revisado e testado. 3. Torne o caminho seguro fácil de seguir para que os colaboradores não precisem de soluções alternativas. Antes de editar: - leia as orientações para agentes, as notas de arquitetura e a lista de verificação relevante anterior à alteração; - identifique os locais canônicos de esquema, migração, código gerado, recursos de idioma, componentes compartilhados, estado e testes; - confira o sistema de acompanhamento de problemas e os rótulos de triagem designados quando o trabalho com problemas estiver no escopo; não invente uma superfície paralela de acompanhamento; - examine os padrões próximos e limite a alteração ao comportamento solicitado e ao código diretamente afetado; - declare as suposições quando as orientações do repositório estiverem incompletas. Prossiga com a implementação local comum e a verificação relevante. Pare para obter aprovação explícita antes de operações destrutivas, alterações em produção ou publicação externa. Não troque segurança ou consistência por menos etapas de implementação. ## Atualizar juntos o esquema e as migrações e usar todas as colunas da chave composta Para alterações no servidor, use o formatador, o analisador de código, os testes focados e o comando de compilação definidos pelo repositório. Resolva os apontamentos da análise até que a execução relevante fique limpa. Use correções automatizadas apenas quando a diferença gerada permanecer dentro do escopo. Execute a limpeza de dependências somente depois de uma mudança nas dependências. Siga as convenções atuais da linguagem. Mantenha o tratamento de erros explícito e conciso, libere recursos de forma confiável, evite limpeza adiada dentro de ciclos longos quando ela acumular recursos, organize as importações e exporte apenas o que outros pacotes exigirem. Para alterações de esquema: - atualize tanto a representação canônica do esquema mais recente quanto a migração ordenada quando o repositório exigir ambas; - atualize os testes ou as verificações da versão da migração que confirmem a versão mais recente; - rastreie os mapeamentos de armazenamento e as representações geradas afetados pela alteração do esquema; - verifique o comportamento ao aplicar a migração no sentido direto e todas as suposições de compatibilidade; não edite manualmente os resultados gerados. Em uma tabela com chave primária composta, cada condição de leitura, junção, atualização e remoção deve incluir todas as colunas da chave. Nunca localize a linha por uma chave parcial. Adicione um teste de colisão com identificadores locais idênticos sob chaves superiores diferentes, utilize a interface pública e comprove que o elemento superior não afetado permanece inalterado. ## Reutilizar os componentes de interface compartilhados e manter os textos nos recursos de idioma Use a tecnologia de interface e os elementos básicos compartilhados já estabelecidos no repositório. Antes de criar um controle interativo, verifique se a camada de interface compartilhada já oferece o comportamento necessário de botão, campo de entrada, seletor, caixa de diálogo, menu, dica, aba, tabela ou formulário. Prefira o componente compartilhado quando ele atender às necessidades de comportamento do navegador, acessibilidade e integração. Use um controle nativo somente quando a camada compartilhada não puder cumprir um requisito concreto e documente brevemente o motivo. Mantenha o texto visível ao usuário nos recursos de idioma, e não no código-fonte. Adicione entradas completas de idioma, evite objetos vazios e preserve as convenções de chaves do projeto. Use a conexão de tradução e os padrões de gerenciamento de estado existentes. Siga o sistema de design: - use os utilitários existentes de variantes e combinação de classes; - use identificadores de tema e propriedades personalizadas em vez de cores isoladas codificadas diretamente; - siga as regras do repositório para espaçamento e composição de componentes; - mantenha o TypeScript estrito e evite enfraquecer os tipos para contornar um erro. Após as alterações, execute o formatador ou corretor do repositório, a verificação que não modifica conteúdo, a verificação de tipos e os testes focados. Revise as mudanças de formatação automatizadas antes de aceitá-las. ## Manter a API compatível com os clientes existentes e conferir as chaves JSON reais Para alterações de API ou protocolo, leia as orientações contratuais do repositório antes de editar. Quando uma orientação geral de API entrar em conflito com uma regra de protocolo específica do repositório, siga a precedência documentada em vez de adivinhar. Use as convenções exigidas para nomes de enumerações e campos. Formate e analise as definições do protocolo, gere novamente os resultados com o comando do repositório e revise as diferenças geradas em busca de alterações não intencionais na interface externa. Verifique a compatibilidade explicitamente: - os clientes existentes ainda conseguem interpretar os campos e valores que não mudaram; - renomeações, remoções, valores padrão e comportamentos obrigatórios são tratados de modo intencional; - servidor, cliente, armazenamento e tipos gerados estão de acordo; - os testes abrangem o contrato público, não apenas os auxiliares internos. Quando dados estruturados forem serializados por uma estrutura de desenvolvimento, verifique as chaves reais de transmissão em vez de presumir a grafia dos campos de origem. Por exemplo, um serializador pode emitir chaves JSON em formato camel case a partir de nomes de esquema com sublinhados. Baseie consultas, migrações, dados fixos de teste e asserções na representação realmente armazenada ou transmitida. ## Revisar a diferença final e relatar só os comandos executados Use a lista de verificação anterior à revisão do repositório antes de abrir ou atualizar uma solicitação externa de alteração. Inclua verificações que a automação possa deixar passar, como compatibilidade, segurança de chaves compostas, integridade de migrações, alterações geradas, localização e configuração do serviço de análise. A verificação deve corresponder à alteração: 1. Formate os arquivos alterados com o comando do repositório. 2. Execute a análise de código ou as verificações estáticas para a tecnologia afetada. 3. Execute os menores testes relevantes, incluindo testes de regressão e colisão quando necessário. 4. Execute a compilação ou a verificação de tipos adequada. 5. Revise a diferença final em busca de edições sem relação, ruído gerado e ampliação acidental do escopo. Não declare sucesso com base em um comando que não foi executado ou que falhou. Informe os comandos executados, seus resultados e tudo o que não foi executado intencionalmente. Crie ou atualize um problema ou uma solicitação externa de alteração somente quando isso for pedido ou já fizer parte do fluxo de trabalho atribuído. Use o sistema de acompanhamento, os rótulos canônicos, a política de revisão e as convenções de ligação designados pelo repositório. Na entrega, explique o que mudou, por quê, como foi verificado, quais riscos permanecem e qual é a próxima decisão humana.