Alterar um repositório de backend e frontend com vários módulos sem quebrar a compilação

## Começar pela raiz do repositório e ler as regras de cada módulo afetado Abra e coordene o projeto a partir da raiz do repositório, mesmo quando uma tarefa parecer limitada a um único subprojeto. Trate as instruções de agente no nível raiz como base e os arquivos de instruções aninhados como regras locais adicionais. Antes de editar, identifique todos os módulos que a tarefa pode afetar e carregue o arquivo de instruções de cada um. Uma tarefa que atravessa módulos deve obedecer a todas as regras locais pertinentes, não apenas às regras do arquivo mais próximo da primeira alteração proposta. ## Definir do que cada módulo cuida e alterar backend e frontend juntos Mantenha um mapa de responsabilidades para as principais áreas: - o módulo de API pública é responsável por pontos de extensão, contratos de serviço e abstrações de segurança; - a aplicação de backend é responsável por lógica de negócio, serviços reativos, roteamento, segurança, migrações e empacotamento; - o espaço de trabalho de frontend é responsável pelas interfaces administrativas e de usuário, pelos pacotes compartilhados e pelo cliente de API gerado; - os módulos da plataforma de dependências são responsáveis pelas restrições da aplicação e das extensões dependentes; - a documentação para desenvolvedores é responsável pela arquitetura e pelas orientações de fluxo de trabalho destinadas a pessoas. Trate alterações de backend e frontend como uma única tarefa full stack sempre que contratos, cargas úteis, autenticação, navegação ou experiência do usuário atravessarem essa fronteira. Mantenha sincronizados, na mesma alteração, os contratos públicos, os manipuladores de backend e o uso no frontend. ## Regenerar o cliente quando a API mudar, sem editá-lo à mão Avalie o impacto no frontend sempre que mudarem tipos públicos de solicitação ou resposta, rotas, contratos do roteador, anotações do esquema da API, esquemas gerados, autenticação ou comportamento de sessão. Depois de atualizar o contrato de origem, regenere a descrição da API e o cliente por meio dos comandos prescritos pelo repositório. Nunca edite diretamente os arquivos de cliente gerados. Corrija o contrato ou a entrada do gerador, regenere a saída e revise a diferença resultante. Peça confirmação antes de fazer alterações destrutivas na saída gerada ou de alterar uma API pública da qual consumidores posteriores possam depender. ## Verificar como o frontend entra no pacote da compilação do backend Entenda como a saída do frontend entra no artefato implantável do backend. Se a compilação do backend incorporar a interface compilada aos recursos da aplicação, toda alteração na saída do frontend também afetará o caminho de empacotamento do backend e deverá ser verificada ali. Execute a coordenação entre camadas a partir da raiz para que a compilação do backend, o empacotamento da interface e os testes usem o mesmo grafo de dependências. Trate downloads feitos durante a compilação, extensões predefinidas e recursos de distribuição copiados como parte do contrato de compilação, não como arquivos acessórios. ## Ler versões e regras de formatação dos arquivos designados Leia as versões das dependências, a versão do projeto, a versão da linguagem, as versões de plugins e as dependências do frontend em seus catálogos, arquivos de propriedades, scripts de compilação e manifestos de pacotes designados. Não fixe no código uma versão que já tenha uma fonte oficial. Use o formatador e o verificador configurados como fonte oficial para recuo, largura de linha e sintaxe compatível. Respeite a versão declarada da linguagem, incluindo `release 21` quando especificada, e mantenha as regras de formatação do nível raiz no escopo em que a compilação as espera. ## Não colocar E/S bloqueante no código reativo e manter o banco de dados no lugar certo Não introduza entrada ou saída bloqueante em caminhos de execução reativos, mesmo que threads virtuais estejam habilitadas em outro lugar. Preserve o mecanismo de migração escolhido pelo projeto em vez de substituí-lo silenciosamente por outro e mantenha as migrações específicas de cada dialeto nos diretórios de banco de dados designados. Mantenha esquemas de extensões, dados JSON de execução, configurações específicas de perfil e o diretório de trabalho substituível em seus respectivos locais. Use caminhos de arquivo absolutos para bancos de dados incorporados baseados em arquivo; um URI relativo pode criar diretórios indesejados sob o módulo da aplicação e mudar qual banco de dados é aberto. ## Escolher os testes conforme a parte que mudou Selecione as verificações de acordo com o escopo real: - alterações apenas no backend exigem a formatação do repositório e os testes de backend afetados; - alterações apenas no frontend exigem formatação do frontend, verificação de tipos, análise estática e testes unitários pertinentes; - alterações de contrato exigem geração da descrição da API, regeneração do cliente, validação do frontend e testes de backend; - alterações entre camadas exigem a verificação do artefato final empacotado, além dos dois lados do contrato. Execute primeiro as verificações focadas e depois amplie o escopo conforme necessário. Adicione ou atualize testes para cada comportamento alterado e não envie o trabalho enquanto as verificações obrigatórias de integração contínua ainda estiverem falhando. ## Confirmar o upstream certo antes do push e preparar só os arquivos da tarefa Identifique o repositório atual e inspecione seus remotos antes de enviar alterações ou abrir uma revisão. Escolha o upstream correto para essa cópia de trabalho; usar o upstream de um repositório público ou proprietário relacionado pode gerar um custo alto para desfazer a operação. Comece o trabalho a partir da base pretendida do upstream e siga as convenções de ramificação do repositório, como `upgrade/gradle-X`, `feat/name`, `fix/name` ou `improvement/name`. Prepare apenas os arquivos pertencentes à tarefa; nunca use `git add -A` ou `git add .` quando puderem existir saídas de compilação ou artefatos de banco de dados. Se uma árvore de trabalho obsoleta bloquear a ramificação principal, inspecione a lista de árvores de trabalho e remova explicitamente apenas a entrada cuja obsolescência tenha sido confirmada. Não use uma limpeza ampla como substituto para identificar o proprietário exato do bloqueio. ## Perguntar antes de migrações ou novas dependências e nunca commitar segredos Use três níveis de controle: - trabalhe sempre a partir da raiz, carregue todas as regras aninhadas aplicáveis, prepare os arquivos explicitamente, regenere clientes derivados a partir da origem, adicione testes para comportamentos alterados e informe na descrição da revisão que o material recebeu assistência de IA; - peça confirmação antes de alterar APIs públicas, adicionar dependências de compilação ou de pacotes, escrever migrações de banco de dados, modificar configurações de segurança ou fluxos de integração contínua, ou substituir de modo destrutivo a saída gerada; - nunca envie segredos ao repositório, fixe versões oficiais no código, adicione operações bloqueantes a caminhos reativos, edite diretamente clientes gerados ou abra uma revisão sem confirmar o upstream correto. Esses limites se aplicam mesmo quando a implementação é simples. A facilidade de implementação não reduz os riscos de compatibilidade, segurança, dados ou publicação. ## Evitar armadilhas conhecidas da compilação, como caminhos relativos do banco de dados Preserve as invariantes conhecidas e específicas das ferramentas: 1. Os locais de bancos de dados incorporados baseados em arquivo devem ser resolvidos como caminhos absolutos do sistema de arquivos; formatos de caminho relativo podem criar diretórios de módulo indesejados e fazer com que a aplicação abra o banco de dados errado. 2. Uma atualização do wrapper de compilação exige tanto o comando do wrapper com versão quanto um segundo comando de geração do wrapper; executar apenas o primeiro deixa inconsistentes os arquivos de wrapper gerados. 3. Mantenha na raiz as demais configurações de formatação aplicáveis a todo o repositório. Movê-las para um submódulo da aplicação combinaria tarefas de formatação incompatíveis e acionaria erros de validação de dependências implícitas na versão `9.x` da ferramenta de compilação. Registre essas armadilhas perto das orientações oficiais de compilação e verifique-as sempre que a configuração afetada mudar.