Mantenha organizado o repositório de código de um produto com app e linha de comando

## Siga primeiro o arquivo de regras principal e depois as regras de cada pasta Trate o arquivo de orientação da raiz como a fonte de verdade de todo o repositório para limites transversais, fluxo de trabalho e comandos. Mantenha-o conciso o suficiente para orientar uma nova pessoa colaboradora sem duplicar detalhes dos módulos. - Publique um índice curto para os documentos de produto, arquitetura, contribuição, revisão e planejamento atual. - Marque explicitamente as especificações arquivadas e nunca trate decisões antigas como comportamento atual. - Direcione cada diretório principal para seu próprio arquivo de orientação sobre responsabilidade e restrições locais. - Antes de trabalhar em um diretório regido por regras, leia sua orientação local além das regras da raiz. - Quando dois documentos divergirem, siga a fonte de verdade designada e informe o conflito, em vez de misturá-los. Não copie regras de módulos de volta para o documento da raiz. Atualize uma regra no nível mais específico que a abranja por completo e vincule-a em documentos mais gerais quando isso for necessário para encontrá-la. ## Decida onde ficam o código e os testes novos antes de fazer mudanças Mantenha um mapa do repositório que explique o que cada área de nível superior possui e quais dependências podem atravessar seus limites. Use o mapa para decidir onde devem ficar novos códigos, testes, modelos, documentos e dados de execução. - Separe aplicativos de usuário, contratos compartilhados, componentes básicos da plataforma, ferramentas de orquestração, testes de ponta a ponta e extensões de conteúdo. - Mantenha a lógica de negócio dos aplicativos independente dos detalhes internos de controle de processos e empacotamento. - Impeça que um aplicativo importe o código-fonte privado ou os testes de outro aplicativo. - Promova DTOs, eventos, erros e formatos de tarefa entre ambientes de execução para uma camada pura de contratos compartilhados. - Mantenha os testes no diretório pertencente à camada que eles verificam; coloque testes de consistência entre aplicativos na camada de ponta a ponta. - Registre diretórios removidos ou inativos para que colaboradores não recriem por engano uma arquitetura obsoleta. Se uma questão reutilizável não tiver uma responsabilidade clara, pare e obtenha uma decisão de responsabilidade antes de criar outro local compartilhado. ## Decida em um só lugar onde os dados são guardados e repasse isso adiante Resolva cada raiz, espaço de nomes e identidade de execução uma vez no limite responsável e depois transmita o valor resolvido aos componentes posteriores. Os componentes devem consumir esse valor em vez de reconstruí-lo com base em portas, diretórios de trabalho, nomes de aplicativos ou valores alternativos do ambiente. - Derive todos os caminhos de dados pertencentes ao ambiente de execução da raiz de dados resolvida ou de constantes derivadas dela. - Trate substituições limitadas e fontes de migração como exceções explícitas, e não como raízes alternativas. - Separe detalhes transitórios de transporte da identidade persistente do ambiente de execução. - Atribua espaços de nomes ao estado empacotado e ao estado de desenvolvimento antes de iniciar processos secundários. - Transmita o estado resolvido aos processos secundários; não permita que eles adivinhem seus próprios locais de armazenamento. - Documente caminhos de escape legados conhecidos como candidatos à remoção e nunca os use como exemplos. Quando houver uma correção evidente, encaminhe o caminho pela raiz canônica ou por um argumento explícito. Quando a responsabilidade correta não estiver clara, solicite uma decisão do mantenedor em vez de inventar uma nova convenção. ## Adicione cada recurso novo ao app e à linha de comando Projete recursos de usuário em torno de um único contrato de serviço e disponibilize-os em todas as interfaces de interação compatíveis. A equivalência entre interfaces faz parte da conclusão do recurso; não é um aprimoramento para depois. Para cada novo recurso: 1. Defina ou atualize os contratos compartilhados de solicitação, resposta, erro e evento. 2. Implemente o ponto de acesso do serviço como a única fonte de comportamento. 3. Adicione a interface gráfica que chama esse ponto de acesso. 4. Adicione a interface de linha de comando que chama o mesmo ponto de acesso. 5. Quando aplicável, forneça resultados de comandos legíveis por máquina e entrada por arquivo para instruções longas. 6. Atualize a lista de verificação da alteração para identificar todas as interfaces afetadas. Não implemente comportamentos divergentes em clientes diferentes. Se uma interface realmente não for aplicável, explique o motivo no registro da alteração em vez de omiti-la silenciosamente. ## Crie peças de tela reutilizáveis e fáceis de usar para todos Atribua a responsabilidade visual ao menor componente estável enquanto preserva contratos globais deliberados. Reutilize componentes básicos compartilhados antes de criar novas variantes locais. - Mantenha a folha de estilos global como um limite intencional de importações e variáveis de design. - Coloque estilos pertencentes a componentes ao lado de seus componentes e use módulos com escopo por padrão. - Reserve seletores globais para redefinições, variáveis de design, estruturas de aplicativos, contratos de conteúdo compartilhados e pontos de integração com terceiros. - Preserve a ordem da cascata ao dividir folhas de estilos e verifique que a especificidade não mude por acidente. - Use controles semânticos e componentes básicos acessíveis compartilhados para botões, rótulos ocultos e comportamentos comuns de formulários. - Adicione um componente básico compartilhado somente quando a necessidade for realmente reutilizável; mantenha o leiaute específico do produto na camada do produto. - Mantenha elementos condicionais montados quando a animação de saída for importante e alterne o estado por meio de classes. - Prefira movimentos rápidos de desaceleração, saídas mais curtas que entradas e uma escala inicial diferente de zero. Quando um estilo global próximo puder ser migrado com segurança em uma alteração pequena e testável, mova-o junto com o componente. Não combine uma migração mecânica ampla com alterações de comportamento não relacionadas. ## Confira as mudanças com o teste mais leve que encontre o problema Escolha a camada de validação mais leve que consiga observar o requisito e adicione verificações mais amplas somente quando o risco atravessar limites. A verificação deve corresponder à responsabilidade e ao impacto da alteração para o usuário. - Para defeitos, comece com um teste de regressão refutável e confirme que ele falha antes da correção. - Limite o teste ao comportamento relatado; registre defeitos adjacentes como trabalhos posteriores separados. - Execute as proteções do repositório e as verificações estáticas, além de testes ou compilações direcionados aos pacotes alterados. - Reproduza sessões gravadas para alterações em analisadores ou fluxos de eventos de agentes antes de consumir chamadas reais a provedores. - Use verificações no navegador para interações visíveis, animações ou condições de corrida que testes unitários não possam comprovar. - Para alterações no espaço de trabalho ou nas dependências, atualize os links gerados e os códigos hash de empacotamento exigidos pelo repositório. - Compare com o estado de referência quando conjuntos de testes próximos tiverem falhas conhecidas. Faça a implementação expressar uma invariante duradoura em vez de uma exceção histórica. Não afirme que algo está pronto apenas porque as verificações automatizadas passaram quando o critério de aceitação exigir uma comparação visual humana. ## Separe as versões de teste e estáveis e confira cada versão antes do lançamento Torne explícitos a identidade do lançamento, o comportamento de empacotamento e as evidências de revisão para cada canal de entrega. Não permita que atalhos convenientes eliminem a separação entre canais ou contornem uma validação confiável. - Dê propósitos e identidades públicas diferentes aos canais de desenvolvimento, validação interna, prévia e versão estável. - Defina explicitamente as dependências de promoção; não faça um canal estável depender de uma etapa de prévia não relacionada. - Mantenha os caminhos do ambiente de execução empacotado separados por espaço de nomes e independentes de portas temporárias. - Encaminhe a orquestração por meio dos componentes básicos dos pacotes responsáveis, em vez de reconstruir argumentos de processos ou regras de varredura nos chamadores. - Exija que as descrições de alterações informem o caso de uso que as motivou, o efeito visível para o usuário, as interfaces afetadas e as evidências de validação. - Anexe capturas de tela que mostrem o ponto de entrada para alterações visíveis na interface, e não apenas imagens isoladas do componente. - Vincule correções de defeitos a seus testes de regressão e registros de problemas. - Mantenha descobertas não relacionadas fora da alteração atual, a menos que bloqueiem a correção, a segurança, a integridade dos dados ou a compatibilidade dos contratos. Antes do lançamento, verifique o artefato pelo mesmo caminho que os usuários executarão. Não aprove alterações que violem os limites do repositório, omitam validações obrigatórias, exponham segredos ou possam corromper dados persistentes.