Desenvolver uma CLI multiplataforma em uma árvore de trabalho compartilhada sem estragar o trabalho alheio

## Buscar e editar só dentro da árvore de trabalho atual Quando o desenvolvimento usa árvores de trabalho, o diretório de trabalho atual é o repositório completo da ramificação ativa. Pesquise, leia, compile, teste e edite somente dentro dessa raiz. - Use caminhos relativos ou caminhos resolvidos abaixo da raiz atual. - Não suponha que um diretório pai seja o repositório. - Não pesquise implementações nem configurações em árvores de trabalho irmãs. - Rejeite caminhos codificados de forma fixa que apontem para a pasta pessoal de um desenvolvedor. - Resolva os caminhos dos dados de teste e do código-fonte a partir da raiz ativa. Sair da árvore de trabalho pode misturar código desatualizado de outra ramificação à análise e às alterações. ## Não redefinir nem apagar as mudanças de outras sessões Presuma que arquivos e edições desconhecidos possam pertencer a outra sessão ativa. Nunca exclua, redefina, descarte ou sobrescreva um trabalho apenas por ele estar fora da tarefa atual. - Preserve os arquivos que você não criou. - Pergunte antes de remover arquivos não rastreados. - Não execute operações de `reset`, `checkout-discard`, `clean` ou `stash-deletion` sem aprovação explícita. - Se os hooks falharem por causa de arquivos que não foram alterados, relate o conflito em vez de modificá-los. - Limite as alterações ao escopo solicitado e examine o diff final. Trate o estado compartilhado da árvore de trabalho como dados do usuário cuja propriedade deve ser esclarecida antes de qualquer ação destrutiva. ## Adicionar comandos por um registro em vez de condicionais espalhadas Use um registro para tornar comandos, provedores e integrações extensíveis. Uma nova implementação deve satisfazer uma interface estável e ser registrada por uma única rota canônica, em vez de adicionar condicionais por toda a aplicação. - Defina interfaces para os comportamentos principais. - Injete dependências por meio de construtores ou campos. - Gere dublês de teste com o gerador aceito pelo repositório. - Use opções funcionais para configurações extensíveis com valores padrão. - Mantenha a implementação de cada comando em um arquivo específico. - Adicione pacotes com finalidade própria em vez de ampliar um pacote genérico de utilitários. Pesquise as camadas existentes de comandos, execução e pacotes antes de introduzir uma lógica paralela. ## Usar o contexto só para cancelamento e prazos, e passar os sinalizadores por um único analisador Use o contexto da solicitação somente para cancelamento, prazos e valores esparsos limitados à solicitação. Quando ele for aceito, passe-o como primeiro parâmetro. Não use o contexto para ocultar configurações, dependências ou parâmetros comuns. Modele a configuração como um fluxo de processamento determinístico: 1. carregue as fontes de configuração; 2. processe importações e herança; 3. aplique a precedência dos sinalizadores de comando, passando pelo ambiente e pelos arquivos, até os valores padrão; 4. renderize os modelos aceitos; 5. gere a configuração efetiva. Encaminhe os sinalizadores e a vinculação de variáveis de ambiente pelo analisador unificado. Ao adicionar uma opção, atualize todos os esquemas responsáveis e nunca contorne a camada central de vinculação. ## Enviar dados encadeáveis e mensagens para pessoas a fluxos de saída separados Grave somente no fluxo de dados os resultados que possam ser usados em pipes. Grave solicitações, progresso, avisos e mensagens formatadas para pessoas no fluxo da interface. Reserve o registro estruturado para eventos do sistema, não para saídas destinadas ao usuário. - Use abstrações compartilhadas de entrada/saída em vez de imprimir diretamente. - Deixe a camada da interface de usuário controlar cores, ícones, Markdown, largura do terminal e detecção de recursos. - Reduza os recursos automaticamente quando o terminal não aceitar estilos ou quando a execução ocorrer em integração contínua. - Mantenha os dados estruturados válidos quando a formatação para pessoas estiver desativada. - Aplique o mascaramento de segredos de forma consistente e não capture dados do usuário na telemetria. Sinalizadores de teste ou gravação podem forçar características do terminal, mas os padrões de produção devem continuar atentos ao ambiente. ## Manter funções pequenas e encapsular erros com categorias estáveis Mantenha arquivos e funções focados. Extraia etapas nomeadas de orquestrações muito complexas para que a função de nível superior seja lida como um fluxo de processamento linear. - Use a formatação, o agrupamento de importações, os aliases e a pontuação de comentários padronizados pelo repositório. - Preserve comentários úteis e atualize-os quando o comportamento mudar. - Aplique o monitoramento de desempenho padrão a operações públicas relevantes. - Isente acessores triviais, construtores, consultas puras e delegações simples quando a política permitir. - Encapsule erros em categorias estáveis e preserve suas causas. - Combine falhas independentes sem perder nenhuma das cadeias. - Verifique erros encapsulados por correspondência semântica, não por comparação de strings. Use construtores de erros detalhados quando os usuários precisarem de dicas, contexto ou semântica de saída. ## Testar o comportamento com mocks e testes que realmente possam falhar Prefira testes de unidade rápidos com dublês gerados para comportamentos isolados e, depois, adicione cobertura de integração ou aceitação onde o comportamento público do comando atravessar limites reais. - Use casos orientados por tabelas para cobrir entradas e erros. - Teste o comportamento, não a implementação interna. - Remova stubs, testes tautológicos e testes permanentemente ignorados. - Em coleções mescladas, modifique o resultado e a origem em verificações separadas para comprovar o isolamento nos dois sentidos. - Para resultados do tipo `slice`, verifique conteúdos representativos e também o comprimento. - Adicione testes negativos que comprovem que a recuperação não é acionada quando sua condição está ausente. - Use correspondência semântica de erros para falhas encapsuladas. A cobertura só serve como evidência quando as asserções podem falhar diante do comportamento protegido. ## Escrever testes que rodem em todos os sistemas e falhem claramente se faltar preparação Os testes devem ser executados nas plataformas de desktop e servidor aceitas sem pressupor um shell, um separador de caminhos ou um utilitário específico da plataforma. - Monte caminhos com componentes separados usando a biblioteca de caminhos padrão. - Normalize separadores somente para comparações portáteis de sufixos ou de exibição. - Use o executável de teste ou um executor injetado em vez de comandos específicos da plataforma. - Incorpore as verificações de subprocessos a um ponto de entrada de testes existente, em vez de definir outro. - Resolva as raízes dos dados de teste como caminhos absolutos antes de percorrê-las ou contá-las. - Faça as verificações de pré-requisitos e da quantidade de dados de teste falharem de forma explícita quando faltar a preparação. - Adicione sentinelas em tempo de compilação para campos de esquema cuja renomeação deva quebrar o teste. Verifique a propagação implícita do ambiente em um subteste explícito de pré-requisitos antes de testar o comportamento dependente de subprocessos. ## Regenerar snapshots com as ferramentas de teste em vez de editá-los à mão Snapshots de referência incluem formatação invisível, largura do terminal, estilos e saídas sensíveis ao ambiente. Nunca os edite manualmente. - Regenere os snapshots por meio do sinalizador de teste ou do gerador aceito. - Examine o diff resultante antes de aceitá-lo. - Não encaminhe testes de snapshots ou de terminal por pipes, pois o redirecionamento pode alterar a detecção de recursos. - Regenere juntas as gravações relacionadas quando a ajuda ou a saída do comando mudar. - Valide as gravações quanto a falhas de comando, referências ausentes e vazamento de caminhos específicos da máquina. - Não altere dados de teste protegidos sem que isso esteja explicitamente no escopo. A saída gerada deve ser alterada por meio da fonte responsável e do fluxo de trabalho canônico. ## Documentar cada comando novo e registrar como issue o trabalho adiado Todo novo comando, sinalizador, parâmetro ou superfície de configuração precisa de documentação para o usuário com os metadados, uso, exemplos, argumentos, sinalizadores e evidências visuais exigidos pelo repositório. - Verifique o identificador declarado da página em vez de deduzir uma URL pelo nome do arquivo. - Compile o site da documentação após as alterações e verifique links, imagens e componentes. - Regenere as capturas visuais quando o comportamento, a ajuda ou a saída do comando mudar, mas não em edições somente de prosa. - Coloque os documentos de requisitos no local designado e siga a convenção de nomes. - Quando um trabalho for adiado, registre uma issue e vincule seu identificador antes do merge. - Mantenha as notas de versão, os dados do roteiro e os rótulos alinhados à classe da alteração. A documentação fica incompleta quando promete um acompanhamento não rastreado. ## Atualizar as revisões sem pular hooks nem usar comandos Git destrutivos Use o fluxo de revisão do repositório e mantenha as automações de manutenção recorrente limitadas à sessão, a menos que um serviço durável seja explicitamente autorizado. - Faça `rebase` ou atualize somente pelo processo de ramificação aprovado. - Verifique a integração contínua e resolva os tópicos de revisão pendentes. - Responda no tópico de revisão original e confirme o vínculo. - Execute a análise estática e a cobertura de testes limitadas ao patch antes de atualizar a revisão. - Não contorne hooks nem use sinalizadores sem verificação. - Não inclua em commits notas temporárias, pesquisas ou marcadores ainda não resolvidos. Nunca execute comandos Git destrutivos nem remova o trabalho de outra sessão sem confirmação explícita do que será perdido. ## Reproduzir cada bug com um teste primeiro e corrigir a causa das verificações que falham Para um bug, primeiro escreva um teste que o reproduza, observe a falha, implemente a menor correção possível e verifique se há regressões. Antes de concluir, confirme: - o projeto compila com a cadeia de ferramentas fixada; - os arquivos alterados passam pelo formatador e pelo linter canônicos; - os testes curtos passam e os testes completos ou de aceitação são executados quando o caminho afetado os exige; - a cobertura atinge o limite imposto sem asserções meramente teatrais; - os dublês gerados, esquemas, snapshots, documentos e capturas visuais estão atualizados; - os limites de complexidade e tamanho de arquivos continuam atendidos; - os caminhos multiplataforma e os testes de subprocessos são portáteis; - nenhum segredo, dado do usuário ou trabalho não relacionado entrou no diff. Corrija a causa de cada verificação que falhar, em vez de enfraquecê-la.