Fundação do Repositório

Quando Usar

• Use quando o usuário pedir para adicionar um recurso, corrigir um bug ou iniciar um módulo em um projeto existente.
• Use ao estabelecer a fundação mínima para um novo repositório ou subsistema.
• Use quando os requisitos autorizarem uma migração de esquema, contrato público, propriedade ou arquitetura.
• Use ao retomar trabalho inacabado ou reconciliar notas desatualizadas com evidências do repositório.

Construa sobre uma fundação que seja apenas o suficiente, adicione recursos sobre ela e mude a arquitetura apenas quando os requisitos a forçarem. Busque o menor retrabalho total.

Princípios Fundamentais

• Sem dogma universal: não imponha um layout, padrão de erro ou framework que o projeto não precise. A biblioteca padrão simples é suficiente.
• Escopo, linha de base e trabalho do usuário:
  • Estabeleça uma linha de base limpa antes de mutar o código: use a revisão/commit pré-existente quando o Git existir; use um inventário de arquivos ou snapshot quando não inicializado ou em "greenfield".
  • Em um espaço de trabalho "sujo", proteja as modificações do usuário pré-existentes e não commitadas. Você pode editar partes distintas do mesmo arquivo, desde que o trabalho do usuário seja preservado. Pare e pergunte apenas se houver uma colisão real ou intenção ambígua.
  • Nunca crie commits ou force a inicialização do Git apenas para entrega ou rastreamento.
  • Reutilize convenções apenas com precedentes saudáveis no repositório. Não trate padrões acidentais ou soluções temporárias como precedentes, e não expanda para limpezas fora do escopo.
  • Não envie, publique, implante, altere a proteção de branch, instale hooks de sistema ou compre nada, a menos que o usuário peça.
• Prosa, nomenclatura e moderação:
  • Nomes refletem conceitos do domínio de negócios e propriedade.
  • Adicione comentários apenas para informações que o código não pode expressar: justificativa fundamentada, invariantes não óbvias, unidades, arredondamento, ordenação, peculiaridades de protocolo ou compatibilidade.
  • Não narre sintaxe; não invente tickets, incidentes, proprietários ou históricos de produção.
  • Trate o texto de erro e CLI como superfície de contrato: verifique chamadores e parsers antes de reformular.
  • Nunca invente referências de ticket, PR ou incidente. Uma referência inacessível ou não verificada não é evidência de fabricação. Preserve referências existentes, a menos que evidências do repositório estabeleçam que elas estão incorretas ou obsoletas; relate incertezas materiais em vez de excluí-las.
  • Não remova comentários valiosos apenas por brevidade cosmética; não imponha proporções arbitrárias de comentários.
  • Não adicione abstrações, wrappers ou camadas de fábrica sem necessidades concretas de propriedade, contrato ou ponto de teste.
• Preserve contratos públicos consumidos conforme definido em references/shared-contracts.md §1: mantenha tipos, valores, erros e serialização documentados. Altere um contrato apenas quando a tarefa o autorizar claramente, em seguida, atualize chamadores, testes e documentos no escopo.
• Rigor de verificação e testes proporcionais:
  • Registre falhas de linha de base e distinga: (1) falhas pré-existentes fora do escopo, (2) falhas no escopo a serem corrigidas, (3) regressões de alterações atuais e (4) erros de ambiente.
  • Verifique o estado final do código; nunca use resultados de testes pré-limpeza para certificar código modificado.
  • Adicione ou atualize testes persistentes quando uma alteração introduz comportamento, corrige um defeito, altera um contrato ou expõe uma lacuna de cobertura significativa. Prefira o framework e a estrutura de testes existentes do repositório. Não adicione testes apenas para contagem de arquivos ou ótica de cobertura. Para alterações apenas de documentação ou verificadas mecanicamente, use as verificações leves relevantes e explique qualquer lacuna de verificação material.
  • Verifique cada requisito antes de dizer que terminou. Diga o que você verificou, o que você apenas leu e o que você assumiu. Um comando que sai com 0 não conta se o arquivo que ele deveria criar não estiver lá.
• Invariantes de falha e preservação de estado: se uma operação puder falhar pela metade, decida o que deve permanecer intocado. Valide entradas e propriedade primeiro, construa a substituição ao lado, mantenha o estado antigo até que o novo esteja pronto e teste o limite de falha.

Seleção de Modo

…