Faça mudanças em um monorepo full-stack sem quebrar os pacotes compartilhados

## Coloque cada mudança no módulo responsável Antes de editar, mapeie o workspace. Diferencie aplicações de produto, pacotes de UI reutilizáveis, lógica de negócio compartilhada, schemas e migrations de dados, pacotes de tipos, presets de configuração, documentação, recursos de implantação e estruturas de teste. Coloque o comportamento específico de uma funcionalidade na aplicação ou no módulo responsável por ela. Coloque a lógica de domínio reutilizável e os tipos compartilhados em pacotes com consumidores explícitos. Mantenha a infraestrutura e os materiais auxiliares de implantação separados do código-fonte de runtime. Posicione os testes unitários junto da lógica estável que exercitam, enquanto as especificações de fluxos do navegador devem ficar na área end-to-end da aplicação. Não duplique lógica compartilhada dentro de uma aplicação apenas para evitar a alteração de um pacote. Respeite a direção das dependências e verifique todos os consumidores downstream quando um pacote compartilhado for alterado. ## Recompile os pacotes pré-compilados e evite caches antigos Identifique os pacotes que são pré-compilados e copiados para os recursos públicos de uma aplicação. Uma aplicação em execução pode importar a saída de distribuição do pacote em vez do código-fonte; por isso, uma alteração apenas no código-fonte pode não ser observável. Depois de alterar um pacote pré-compilado ou qualquer dependência que afete seu bundle: 1. remova somente as saídas de distribuição conhecidas do pacote e os artefatos copiados; 2. ignore o cache do sistema de build no grafo de dependências afetado; 3. recompile o pacote por meio de sua tarefa oficial do workspace; 4. atualize ou desative o cache do navegador; 5. reinicie o servidor de desenvolvimento somente se o recurso recompilado ainda não for carregado. Nunca edite manualmente bundles copiados nem artefatos gerados. Trate a invalidação do cache como parte do procedimento de verificação, não como evidência de que a alteração no código-fonte falhou. ## Siga as regras compartilhadas de lint e de tipos Use os presets compartilhados de lint, formatação e compilação do repositório em vez de sobrescritas locais. Siga as regras estabelecidas de indentação, largura de linha, aspas, ponto e vírgula e agrupamento de imports. Nomeie componentes e pastas de componentes de forma consistente, use lower camel case para funções e variáveis e reserve upper snake case para constantes verdadeiras. Coloque os mocks no local designado para manter estáveis a resolução e a ordem dos imports. Prefira tipos inferidos quando continuarem claros, use os tipos de domínio compartilhados e evite escapes sem tipagem. Trate as props dos componentes como imutáveis. Mantenha os componentes focados, os efeitos restritos e as dependências dos hooks corretas, e justifique a memoização por uma necessidade medida, não por hábito. ## Separe a lógica do servidor e crie as chaves de cache com uma só fábrica Mantenha separados a composição de rotas, a lógica de serviços e os módulos de funcionalidades. As ações do servidor devem chamar serviços e retornar uma estrutura consistente de sucesso ou erro. Os provedores de contexto devem falhar de forma clara quando usados fora de seu provider e devem limpar os efeitos usando snapshots estáveis em vez de referências mutáveis. Use memoização limitada à requisição para trabalhos duplicados dentro de uma mesma requisição. Para trabalhos caros entre requisições, use a abstração de cache compartilhado aprovada ou um cache distribuído explícito. Não introduza uma API de cache instável do framework quando o repositório a tiver rejeitado. Crie todas as chaves de cache por meio da fábrica de chaves canônica. A chave deve incluir todas as dimensões capazes de alterar o resultado, para impedir que usuários, tenants, ambientes, locales ou modos de funcionalidade compartilhem entradas incompatíveis. ## Passe os textos pela tradução e separe o fuso horário do idioma Encaminhe todo o texto voltado ao usuário pela função de tradução e siga a convenção estabelecida de chaves em letras minúsculas separadas por pontos. Mantenha um arquivo do locale de origem como a única fonte de tradução escrita manualmente. Nunca edite manualmente os arquivos de locale gerados; execute o gerador de localização e o validador de chaves depois de alterar o texto de origem. Renderize datas e horas voltadas ao usuário por meio dos helpers compartilhados. Obtenha o locale de exibição da fonte oficial de idioma da aplicação, nunca de um padrão implícito do navegador. Trate locale e fuso horário como elementos independentes: o locale controla a formatação, enquanto o fuso horário controla o instante representado. Nunca deduza o fuso horário a partir do locale. Preserve a semântica existente dos valores armazenados, a menos que o produto defina uma fonte oficial para o fuso horário. Mantenha armazenamento, APIs, exports, integrações e logs em formatos estáveis e não localizados, como uma representação UTC ou ISO explícita. ## Não misture os dados de cada organização e mantenha as consultas rápidas Limite todas as operações de dados pela fronteira de tenant do repositório, como organização e ambiente. Aplique os filtros de exclusão lógica de forma consistente para que registros inativos ou excluídos não reapareçam por caminhos de consulta alternativos. Para contagens, use uma consulta de contagem filtrada em vez de argumentos de paginação por offset. Execute simultaneamente as consultas independentes de contagem e de dados. Prefira paginação por cursor para conjuntos de dados grandes e inclua campos de propriedade indexados ao filtrar por tempo. Revise alterações de schema e migration junto de todos os caminhos de consulta afetados. O isolamento de dados é uma invariante transversal: a ausência de um predicado de tenant não é um pequeno problema de desempenho, mas uma possível falha do limite de dados. ## Escolha os testes pelo risco ao usuário, não pela cobertura Otimize a confiança, não uma porcentagem de cobertura: - Use testes end-to-end no navegador para jornadas críticas do usuário, regressões de UI e comportamento de componentes. - Use testes unitários para lógica pura e estável, como validadores, transformadores, avaliadores, cálculos e casos extremos. - Use verificações manuais em staging para avaliar a prontidão da release, com um ciclo de correção de bug, backport e repetição de testes para descobertas críticas. Mantenha os testes de navegador focados, bem nomeados e explícitos quanto às suítes lentas. Simule os limites de rede e armazenamento por meio de helpers compartilhados. Não adicione snapshots frágeis de componentes, asserções de markup, testes de detalhes de implementação, artifícios de temporização, fluxos gigantescos nem testes de baixo valor criados apenas para aumentar a cobertura. Execute a suíte unitária padrão antes da revisão, a cobertura quando fluxos críticos mudarem e a suíte end-to-end diretamente afetada quando houver risco para uma jornada. ## Mantenha a documentação e os exemplos de componentes em dia Siga o contrato de arquivos, os campos de metadados, as regras de títulos e os componentes aprovados de etapas ou avisos do sistema de documentação. Marque conteúdos de edição restrita com o aviso padrão em vez de inventar um novo badge ou uma nova redação. Mantenha os exemplos de componentes junto do componente e importe-os por seu ponto de entrada público. Organize os controles nos grupos padrão do repositório. Cubra o estado padrão, o estado desativado quando disponível, o estado com ícone quando disponível, todas as variantes e os casos extremos relevantes. Antes de criar ou revisar uma UI, carregue o contexto de design da superfície afetada. As diretrizes compartilhadas de design complementam as convenções de código e continuam sendo a fonte oficial para tokens, componentes, movimento e qualidade visual. ## Dê aos fluxos de CI só as permissões necessárias Conceda aos tokens de automação somente as permissões exigidas por cada workflow. Inicie os jobs Linux hospedados com a etapa aprovada de reforço do runner, para que os comportamentos de rede e processo sejam restringidos antes da execução do código do projeto. Mantenha os arquivos de lock de dependências como fonte oficial e execute os comandos do workspace por meio do gerenciador de pacotes escolhido pelo repositório. Evite comandos avulsos de instalação ou build que ignorem o grafo de tarefas, o ambiente compartilhado ou os metadados do cache. Ao alterar um workflow, verifique os gatilhos de eventos, as permissões, a exposição de secrets, as chaves de cache, os artefatos e a propagação de falhas. Uma etapa downstream bem-sucedida não deve ocultar a falha de um pré-requisito. ## Entregue um pull request com resultados de testes e capturas de tela Antes de concluir, remova código morto e imports não usados, execute o comando oficial de lint e realize o menor conjunto de testes que comprove a alteração, além de qualquer fluxo mais amplo diretamente afetado. Mantenha os commits focados e coerentes com a convenção de commits do repositório. Um pull request deve expor o problema, resumir a solução, vincular a issue ou a especificação aplicável e identificar migrations ou alterações de ambiente. Anexe evidências visuais para trabalhos de UI e inclua os resultados dos comandos relevantes de lint, teste, build e migration. Os revisores devem conseguir determinar o que mudou, por que a alteração pertence àquele módulo, como os resultados gerados foram atualizados e quais riscos foram verificados sem precisar reconstruir o trabalho apenas a partir do diff.