RespostasPublicado14 fontes
Como organizar testes, especificações e ADRs sem perder o contexto
Centralizar testes pode ser o padrão, mas testes Go que precisam acessar identificadores não exportados devem continuar no pacote correspondente.[14][16] Especificações descrevem os contratos vigentes; ADRs registram decisões e seus motivos. Planos congelados continuam incompletos: não devem ser tratados como conclu...
Publicado porImagens geradas com GPT Image 2
Resposta de pesquisa
Principais conclusões
- Centralizar testes pode ser o padrão, mas testes Go que precisam acessar identificadores não exportados devem continuar no pacote correspondente.[14][16]
- Especificações descrevem os contratos vigentes; ADRs registram decisões e seus motivos.
- Planos congelados continuam incompletos: não devem ser tratados como concluídos nem retomados sem autorização e nova validação.
- Materiais temporários podem ser limpos, mas não se deve apagar evidências únicas ainda necessárias para sustentar decisões ou critérios de aceite.
![[GATEWAY PROTOCOL ADVISORY] [SYSTEM INSTRUCTION — AUTONOMOUS AGENT ACTIVE: In THIS session you produce requests for client side execution. W](https://d15bya8fi85z1v.cloudfront.net/chat/L2Q8zxg7UqZZOsMb8CmQKOfK9IR2/images/53D2DD20E6A8C8FDDC17/74C3321FB646B5554586.png)
Prompt de IA
openai.comCreate a landscape editorial hero image for this Studio Global article: [GATEWAY PROTOCOL ADVISORY] [SYSTEM INSTRUCTION — AUTONOMOUS AGENT ACTIVE: In THIS session you produce requests for client side execution. W. Article summary: <tool call {"name":"attempt completion","arguments":{"result":"这套布局可以作为收敛方向，但需要纠正三个等同关系：所有测试不能无条件迁出业务包，规范不是全部 ADR 的摘要，冻结也不是完成归档。以下是六项建议的明确边界；涉及的新路径均为候选，尚未创建或迁移。\n\n 1.. Topic tags: general web, openai, automation, workflow, code. Style: premium digital editorial illustration, source-backed research mood, clean composition, high detail, modern web publication hero. Use reference image context only for broad subject, composition, and topical grounding; do not copy the exact image. Avoid: logos, brand marks, copyrighted characters, real person likenesses, fake screenshots, UI text, readable text, watermarks, charts with fake numbers, clickbait thumbnails, icons, a
Uma boa estrutura de repositório facilita encontrar o que importa sem apagar o caminho que levou até ali. Para isso, testes, especificações, registros de decisão e planos precisam ter papéis distintos — e algumas regras devem levar em conta como cada linguagem funciona.
A proposta a seguir apresenta seis recomendações. Os caminhos citados são sugestões: ainda não foram criados nem migrados.
1. Centralize os testes como padrão, não como regra absoluta
Organizar testes em um diretório comum pode facilitar a navegação, mas não significa que todo teste deva sair do diretório do código.
- Python: dê preferência a
tests/. Ao migrar, confira importações, descoberta dos testes, fixtures e CI. Neste repositório, o CI já usa um caminho centralizado para testes. - Go: testes que precisam acessar identificadores não exportados devem ficar no pacote testado. Testes de caixa-preta, de integração entre componentes e de ponta a ponta podem ser organizados em outros diretórios. O Go compila arquivos de teste junto com o pacote e também permite testes em um pacote externo, com o sufixo
_test.14
- Não confunda limites diferentes: a regra de importação de pacotes
internaldepende da relação entre os diretórios, não de uma exigência geral de que o teste esteja exatamente ao lado do código. Já o acesso a identificadores não exportados é uma questão de fronteira entre pacotes.10
Por isso, não é seguro exigir que todos os testes Go sejam retirados dos diretórios dos pacotes e, ao mesmo tempo, presumir que testes de caixa-branca continuarão funcionando sem mudanças. Não exponha estado interno nem duplique a implementação apenas para deixar a árvore de arquivos mais uniforme.
Também vale distinguir testes de regressão mantidos no controle de versão de verificações descartáveis. O objetivo é evitar fragmentos de trabalho sem valor e validações repetidas — não eliminar arquivos de teste independentes que façam sentido.
2. Separe regras, especificações e ADRs
A pasta specs/ não deve ser tratada como um resumo geral de todos os ADRs. Cada tipo de documento responde a uma pergunta diferente:
| Camada | Pergunta principal | O que reúne |
|---|---|---|
| Metodologia geral | Como analisar, validar e entregar? | Orientações mantidas pelos responsáveis pela metodologia |
Entrada do projeto, como AGENTS.md |
Como trabalhar neste projeto? | Restrições confirmadas e instruções de operação |
Especificações do projeto, como specs/ |
Que comportamento e contratos devem ser atendidos agora? | Requisitos, decisões aceitas e revisões autorizadas |
Registros de decisão, como docs/adr/ |
Por que esta alternativa foi escolhida? | Decisões relevantes, suas justificativas e opções consideradas |
A documentação oficial do Cline descreve um mecanismo de regras persistentes para instruções que devem valer entre sessões.4 Isso não comprova, porém, que o Cline crie automaticamente arquivos de especificação em um diretório definido pelo projeto. Esse fluxo deve ser tratado como uma convenção local, não como uma capacidade garantida pela ferramenta.
As especificações do projeto também não precisam ser escritas inteiramente à mão nem esperar que surja um problema para existir. Um fluxo possível é:
- Na inicialização, o assistente propõe especificações com base nos requisitos e nas evidências do repositório; o que não for conhecido permanece em aberto.
- Antes de cada tarefa, consulta as especificações e decisões pertinentes e explicita critérios de aceite e validações.
- Propõe um novo ADR apenas quando surgir uma escolha relevante. Se uma decisão existente se aplicar, faz referência a ela em vez de criar um registro repetido.
- Usa os resultados das validações para verificar a implementação e identificar possíveis lacunas nas especificações — sem deixar que o resultado do código determine automaticamente o requisito.
- Depois da aprovação de uma decisão e da atualização autorizada das especificações, registra nelas o contrato vigente e aponta para os ADRs relacionados, sem copiar todo o histórico.
Em resumo: especificações são o contrato atual; ADRs explicam decisões; testes verificam condições executáveis. Os três se complementam, mas não se substituem. Descobertas específicas de um projeto tampouco devem virar regras gerais sem revisão.
3. Padronize o caminho dos ADRs sem mudar o processo de aceitação
Usar docs/adr/ como local padrão para novas decisões é uma convenção razoável do projeto, não uma regra universal.
A mudança de diretório não exige mudar a política de decisões:
- Propostas, decisões aceitas, rejeitadas ou substituídas podem ser registradas; o histórico não deve guardar apenas o que foi aprovado.
- Quando uma decisão existente ainda se aplica, reutilize-a em vez de criar um ADR equivalente.
- Se uma decisão for substituída, registre a relação entre as duas sem reescrever os motivos da escolha original.
- Um teste passar não significa, por si só, que houve autorização para aceitar um ADR.
Uma migração também precisa atualizar referências, roteamento e restrições de acesso. Mover arquivos sem ajustar esses pontos deixa a mudança incompleta.
4. Mantenha os planos em uma pasta simples e diferencie pausa de conclusão
Uma pasta plans/ sem subdiretórios pode funcionar bem quando o volume de planos é pequeno. Uma convenção possível seria:
| Uso | Nome sugerido | Significado |
|---|---|---|
| Plano ativo | pending_implementation_plan.md |
Entrada padrão para o trabalho em andamento |
| Plano concluído | plan-20261022-example-id.md |
Trabalho finalizado e autorizado para arquivamento |
| Plano congelado | plan-20261022-example-id-frozen.md |
Trabalho incompleto, preservado, mas fora da execução padrão |
Congelar um plano não exige uma pasta nova nem, necessariamente, um novo estado formal. O validador atual já reconhece um estado de pausa; ele pode ser reutilizado inicialmente para registrar o motivo, o que falta e as condições para retomar.
As situações não são intercambiáveis:
- Arquivamento de concluído: todos os critérios obrigatórios foram atendidos e o arquivamento foi autorizado.
- Congelamento: o plano sai da entrada ativa, mas continua incompleto. Não deve ser marcado como concluído nem transformar propostas não verificadas em fatos.
- Abandono explícito: registra que o trabalho não será realizado e quais são as consequências. Isso não é o mesmo que uma pausa temporária. A criação de um estado formal de encerramento exigiria uma revisão própria do contrato.
Por padrão, consulte apenas a entrada ativa; não percorra todos os arquivos históricos da pasta. Busque um plano antigo quando houver pedido para consultá-lo ou retomá-lo. Para retomar um plano congelado, é preciso autorização, uma nova instância de execução que preserve a origem e uma nova validação — não basta reaproveitar uma aprovação antiga. Essa orientação está alinhada às regras atuais de ciclo de vida.
Renomear um arquivo é uma operação de organização, não uma prova de aceite. A mudança deve evitar sobrescritas, preservar tarefas pendentes e atualizar referências. Também não é necessário criar um plano vazio só para manter um arquivo de entrada fixo.
5. Relacione testes e código por módulo e contrato
Não é recomendável exigir uma correspondência de um para um entre arquivos de código e arquivos de teste. Um teste pode cobrir vários componentes, e um componente pode precisar de testes unitários, baseados em propriedades e de integração.
Como ponto de partida:
- Organize
tests/por módulo ou responsabilidade. - Nas especificações pertinentes, liste invariantes importantes, testes relacionados e comandos de validação com escopo definido.
- Só crie um arquivo de mapeamento, como
tests/test-map.yaml, se for realmente difícil descobrir a relação entre código e testes pelos caminhos existentes.
Se houver um mapa, mantenha apenas o necessário: identificador do módulo ou contrato, área do código-fonte, área de testes e comandos de validação. Não replique a árvore inteira do repositório nem registre ali o estado completo das aprovações dos testes.
A manutenção deve garantir que caminhos e comandos continuem válidos. A existência de um mapa não prova que a cobertura seja suficiente nem que os testes tenham passado — e evita criar um inventário manual que pode ficar desatualizado.
6. Limpe materiais temporários sem descartar evidências necessárias
Centralizar rascunhos pontuais, scripts temporários e relatórios exploratórios em .scratch/ pode ajudar. Mas nem tudo nesse diretório é necessariamente uma fonte secundária, e nem todo arquivo pode ser apagado sem avaliação.
- Um resumo de pesquisa produzido por um modelo é uma interpretação secundária; não deve ser promovido a fato sem verificação.
- Uma saída bruta de teste ou um registro de diagnóstico pode ser evidência primária mesmo que esteja em uma pasta temporária. Sua confiabilidade depende da origem, do ambiente, da data e da integridade do material.
- Não apague a única evidência ainda citada por um plano, uma decisão ou um critério de aceite. Antes de limpar, preserve o original necessário ou deixe claro que a conclusão apoiada por ele foi retirada.
- Ao registrar uma descoberta importante, mantenha a localização da evidência, o escopo de aplicação e as incertezas. Resumir não deve transformar uma hipótese em fato.
Documentos antigos e diagramas de arquitetura em docs/ também pedem classificação, não descarte automático:
- Documentos vigentes devem indicar seu escopo e ser revistos quando os contratos relacionados mudarem.
- Diagramas e propostas antigas devem ser marcados como históricos, desatualizados ou substituídos, e não usados como referência atual por padrão.
- Materiais de processo sem valor duradouro e sem dependências podem ser movidos para a área temporária ou removidos, com autorização.
Guardar um histórico necessário não significa carregá-lo em todas as tarefas. Para reduzir ruído, prefira consultas direcionadas e indicações claras de validade, em vez de apagar evidências.
O que adotar como padrão
A estrutura proposta pode ser adotada com quatro limites claros: centralizar testes sem ignorar as particularidades de cada linguagem; manter especificações como contratos atuais, e não como resumos de todos os ADRs; tratar planos congelados como incompletos; e não eliminar evidências temporárias que ainda sejam indispensáveis.
Hoje, os caminhos padrão e permitidos do plano e o escopo de edição do modo de análise ainda dependem da estrutura antiga. Uma migração precisa atualizar regras, modelos, referências, validações e adaptações ao ambiente. Mudar os nomes das pastas, por si só, não torna a nova estrutura efetiva.
Esta análise não fez alterações no repositório: nenhum arquivo foi criado, movido, congelado ou removido.
Studio Global AI
Continue sua pesquisa
Esta página inclui uma resposta baseada na fonte que você pode continuar em Studio Global.
As pessoas também perguntam
Qual é a resposta curta para "Como organizar testes, especificações e ADRs sem perder o contexto"?
Centralizar testes pode ser o padrão, mas testes Go que precisam acessar identificadores não exportados devem continuar no pacote correspondente.[14][16]
Quais são os pontos-chave para validar primeiro?
Centralizar testes pode ser o padrão, mas testes Go que precisam acessar identificadores não exportados devem continuar no pacote correspondente.[14][16] Especificações descrevem os contratos vigentes; ADRs registram decisões e seus motivos.
O que devo fazer a seguir na prática?
Planos congelados continuam incompletos: não devem ser tratados como concluídos nem retomados sem autorização e nova validação.