Criar uma biblioteca de dados com APIs fáceis de encontrar e testes com valores reais

## Esconda dados de origem complexos atrás de objetos simples Oculte a complexidade do formato de origem por trás de objetos de domínio intuitivos, sem esconder capacidades importantes. Torne diretas as operações comuns e apresente progressivamente os recursos especializados de análise, geração de relatórios e inspeção quando os usuários precisarem deles. Leia antes de escrever. Antes de modificar o código, examine as abstrações existentes, os padrões de nomenclatura, os limites entre módulos e os testes próximos. Amplie o projeto atual, a menos que uma incompatibilidade concreta exija um novo padrão. ## Antes de editar, mapeie qual módulo cuida de cada tarefa Mantenha um mapa de navegação conciso que ligue as necessidades dos usuários aos módulos responsáveis e às principais classes de domínio. Inclua os pontos de entrada públicos para localizar registros, carregar entidades, analisar dados estruturados, criar demonstrativos, ler notas, abrir documentos e construir relatórios tipados. Antes de editar, acompanhe fluxos de dados representativos de ponta a ponta. Siga uma solicitação desde seu ponto de entrada público, passando pela obtenção, análise, objetos tipados, demonstrativos, notas, relatórios e extração de documentos. Confirme qual camada é responsável por cada transformação e onde os usuários devem aprofundar a consulta para obter detalhes de apoio. Use o mapa para escolher o menor módulo responsável. Não coloque um comportamento em um arquivo conveniente quando outra camada já for responsável por ele. ## Leia arquivos grandes por partes e altere só o necessário Trate módulos com mais de 30 KB como vários contextos locais, em vez de lê-los ou reescrevê-los como um único bloco. Procure o símbolo relevante, examine a classe ou função que o contém e depois leia código adjacente suficiente para entender as invariantes e os locais de chamada. Antes de alterar um arquivo grande, localize testes, importações, subclasses e referências públicas relacionadas. Mantenha a alteração restrita, preserve as convenções ao redor e evite reformatações ou reestruturações não relacionadas que ocultem a mudança funcional. ## Registre e atualize o trabalho no sistema de gestão de tarefas Use o sistema de gestão de tarefas do projeto como registro durável do trabalho ativo. Revise itens abertos e em andamento, selecione a tarefa pertinente e mova-a para o estado ativo antes da implementação. Registre defeitos ou tarefas recém-descobertos com título, tipo e prioridade claros, em vez de deixá-los apenas em comentários ou conversas. Atualize a mesma tarefa quando o escopo, os impedimentos ou as conclusões mudarem. Encerre-a somente após concluir a verificação necessária. Preserve os estados definidos `open`, `in-progress`, `blocked` e `closed`. Quando o sistema usar uma escala de prioridade com cinco níveis, mantenha `0` para trabalho crítico e `4` para o conjunto de pendências, em vez de inventar rótulos improvisados. ## Verifique se a biblioteca cumpre o que a documentação promete A verificação pergunta se a biblioteca entrega o que sua documentação promete, não apenas se o código interno é executado. Aplique três princípios orientadores: 1. A documentação é a especificação; portanto, todo exemplo documentado deve ser verificável. 2. A exatidão dos dados é essencial; portanto, as verificações devem afirmar valores esperados específicos, e não apenas a existência de um resultado. 3. A API deve permitir a resolução do problema; portanto, usuários e agentes devem conseguir avançar de uma pergunta até o objeto, o método e as evidências de apoio adequados. Use esses princípios para avaliar em conjunto o projeto do recurso, a documentação, os casos de teste e o comportamento em caso de falha. ## Dê a cada recurso novo um teste com valores reais e um exemplo executável na documentação Todo novo recurso voltado ao usuário deve incluir: - uma asserção de valor de referência que use um valor específico de um registro de origem real, verificado de forma independente; - um exemplo documentado que também seja executado como verificação automatizada; - uma verificação contra falhas silenciosas que prove que uma entrada inválida ou ausente produz um erro útil, em vez de um valor vazio ou uma falha sem aviso; - uma atualização de descoberta que faça o recurso aparecer na navegação do projeto, no catálogo de capacidades ou nas orientações para agentes. O recurso estará incompleto se qualquer um desses elementos estiver ausente, mesmo que sua implementação no fluxo normal funcione. ## Rode primeiro os testes locais rápidos e os de rede um de cada vez Forneça comandos distintos para verificação local rápida, verificação com rede, verificação de regressão e relatórios de cobertura. Execute primeiro a menor verificação local pertinente e amplie o escopo somente quando o resultado focado for aprovado. Execute em paralelo apenas testes rápidos que não entrem em contato com serviços externos. Execute a verificação com rede de forma sequencial e respeite os limites de solicitações do serviço. Use dados de teste com respostas registradas quando eles puderem tornar o comportamento externo rápido e determinístico sem ocultar o contrato que está sendo verificado. Coloque as regressões em uma área dedicada, com nomes estáveis que liguem cada caso ao defeito que o originou. Trate a cobertura como evidência complementar, não como substituta das asserções sobre comportamento e dados. ## Verifique valores exatos e erros claros com dados de origem variados Afirme valores de domínio exatos, estruturas normalizadas e mensagens de erro significativas. Uma asserção que apenas confirma a existência de um resultado é insuficiente quando a exatidão depende do próprio valor. Diversifique os registros de origem entre organizações, setores, formatos e períodos de relatório, em vez de depender de um único exemplo conhecido. Teste explicitamente entradas malformadas, incompletas e não compatíveis. Confirme que as falhas retornam mensagens que indicam como agir e nunca se transformam silenciosamente em um resultado vazio. Quando dados externos forem necessários, preserve dados de teste determinísticos e documente como seus valores esperados foram estabelecidos. Atualize esses dados deliberadamente quando o contrato da fonte mudar; não os renove apenas para fazer uma verificação com falha ser aprovada. ## Mantenha a versão e a documentação de acordo com o código que funciona Leia a versão do projeto no arquivo de metadados designado e evite duplicá-la em módulos não relacionados. Mantenha a navegação do repositório, as orientações de verificação, os exemplos públicos e os catálogos de capacidades sincronizados com o comportamento compatível. Quando uma rota da API mudar, atualize a documentação e os exemplos executáveis no mesmo item de trabalho. Uma rota documentada que deixou de funcionar representa uma violação do contrato com o usuário, mesmo que a implementação substituta esteja correta.