RespostasPublicado15 fontes
Como manter testes úteis e documentos enxutos no V4
A recomendação não é deixar de versionar testes: testes duradouros devem continuar como parte da manutenção do projeto; verificações pontuais e seus resultados precisam de tratamento separado. O V4 já diferencia análises, decisões, planos e contratos, mas ainda há lacunas nas regras para materiais temporários e limi...
Publicado porImagens geradas com GPT Image 2
Resposta de pesquisa
Principais conclusões
- A recomendação não é deixar de versionar testes: testes duradouros devem continuar como parte da manutenção do projeto; verificações pontuais e seus resultados precisam de tratamento separado.
- O V4 já diferencia análises, decisões, planos e contratos, mas ainda há lacunas nas regras para materiais temporários e limites de distribuição.
- A quantidade de arquivos, o que é versionado, o que é instalado e o que é enviado ao modelo são decisões distintas — uma pasta única não resolve todas elas.
- A apuração é parcial: inclui evidências estáticas do repositório e algumas fontes externas, mas não uma auditoria completa, nem execução de testes.
![[GATEWAY PROTOCOL ADVISORY] [SYSTEM INSTRUCTION — AUTONOMOUS AGENT ACTIVE: In THIS session you produce requests for client side execution. W](https://d15bya8fi85z1v.cloudfront.net/chat/oBMfTzLzQzYo7VcXQdEGj2yQgAw1/images/73E9D63489E02AC46209/BEDABC175BE8FCADFC63.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":"两个痛点都适合纳入 V4 的“产物生命周期背压”，但不应简化成“测试全部不提交”或“文档全部合并”。建议保留长期质量资产，隔离一次性验证材料，并分别控制仓库维护、安装分发和模型上下文。\n\n本次交付为阶段性调研：仓库静态证据、Geoffrey Huntley 的作者资料及部分学术资料已取得；Python 官方布. Topic tags: general web, openai, llm, agents, ai. 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 fa
Dois problemas de organização podem ser tratados em conjunto no V4: testes e materiais temporários que poluem o repositório, e documentos que crescem a ponto de dificultar a consulta. A solução, porém, não é deixar de versionar todos os testes nem juntar toda a documentação em um único arquivo. O caminho mais seguro é preservar os ativos de qualidade, isolar verificações pontuais e definir separadamente o que fica no repositório, o que é distribuído e o que entra no contexto do modelo.
Esta é uma análise parcial. Ela se baseia em evidências estáticas do repositório, em materiais de Geoffrey Huntley e em algumas fontes acadêmicas. A pesquisa sobre as convenções oficiais de organização de projetos Python e a consulta a X, Reddit, Hacker News e Lobsters não foram concluídas. Os testes também não foram executados; portanto, as recomendações abaixo não devem ser confundidas com mudanças já implementadas ou validadas.
Testes: separar o que é temporário sem abrir mão da qualidade
O que as evidências do V4 indicam
- A configuração de CI em
.github/workflows/ci.yml:55usa a pasta centralizadatests/para verificações de contrato de configuração, distribuição de instalação e proteção de ativos. A aparência de “arquivo a mais” não basta para classificá-las como descartáveis. Nesta análise, não houve nova execução nem avaliação individual da manutenção de cada teste. - O
.gitignore:1exclui alguns arquivos de sandbox, cache e temporários, mas não menciona explicitamente materiais como rascunhos e saídas de validação. Entre os diretórios existentes estão_bmad-output/scratch/e_bmad-output/verification/. A existência dessas pastas, por si só, não prova que seus arquivos estejam versionados; o estado do índice do Git não foi verificado. - O ponto de entrada de atualização em
bs.sh:298atualiza o repositório. Jáscripts/deployment_source.py:64coleta os arquivos de um pacote selecionado. São limites diferentes: encontrar testes ao baixar o repositório não significa que eles sejam instalados junto com o material de execução. - A rotina de coleta em
scripts/deployment_source.py:47busca arquivos comuns dentro do pacote e os mapeia como entradas para distribuição emscripts/deployment_source.py:81. Isso indica um risco potencial caso materiais temporários sejam colocados dentro de um pacote. Não há evidência de que isso já tenha ocorrido.
Uma classificação prática
| Tipo de material | Recomendação para controle de versão | Recomendação para organização e distribuição |
|---|---|---|
| Testes duradouros de regressão, contrato e integração necessários | Versionar e manter junto com a implementação | Seguir as convenções da linguagem e do projeto; em geral, não incluir no pacote de execução |
| Diagnósticos pontuais, scripts de verificação e dados de experimento | Manter localmente por padrão, sem versionamento automático | Usar uma área temporária autorizada e não colocar dentro dos pacotes de distribuição |
| Logs, relatórios de cobertura e comprovantes de execução | Não incluir no código-fonte por padrão; preservar evidências necessárias conforme sua finalidade | Manter separados do código de teste e fora do pacote de instalação |
Essa classificação é uma proposta, não uma regra que já tenha sido aplicada ao V4.
As convenções também variam conforme a linguagem. O tutorial oficial de Go, por exemplo, coloca os arquivos de teste junto ao pacote testado; isso não sustenta uma regra universal de mover testes Go para uma pasta centralizada.15 O projeto já usa uma estrutura central para testes, mas a pesquisa não reuniu evidência oficial suficiente para afirmar qual seria a melhor organização para projetos Python em geral.
O objetivo faz diferença: para que o usuário receba um pacote mais limpo, a prioridade é controlar o conteúdo da distribuição ou da instalação. Para organizar a árvore de código usada no desenvolvimento, é preciso considerar as convenções da linguagem. Mover os arquivos não resolve necessariamente os dois problemas ao mesmo tempo.
Documentação: reduzir sobreposições, não apenas contar arquivos
O roteamento de artefatos em bmad-suite-v4/rules/bmad-core.md:129 já diferencia análises, ADRs — registros de decisões de arquitetura —, planos e contratos, e orienta a perguntar quando não estiver claro onde algo deve ficar. Mas a regra de rascunhos em bmad-suite-v4/rules/bmad-core.md:117 estabelece outra convenção de caminho. Isso aponta para uma cobertura incompleta do ciclo de vida dos materiais; não permite afirmar por que cada diretório foi criado.
Em vez de criar mais diretórios, a recomendação é esclarecer a função dos existentes:
- Análises formais: registrar evidências, comparações, contrapontos e pontos ainda desconhecidos. Uma consulta comum pode ser respondida na conversa, sem gerar um relatório persistente se não houver essa necessidade.
- ADRs: documentar decisões importantes, suas justificativas e restrições. Não precisam reproduzir toda a análise nem espelhar cada etapa da execução.
- Planos de implementação: registrar autorização, escopo, dependências e critérios de aceitação, com referências às decisões relacionadas em vez de repetir o conteúdo da pesquisa.
- Materiais temporários: encaminhar rascunhos, entradas de diagnóstico e saídas brutas para uma área temporária aprovada. O simples uso da palavra “rascunho” no título não deve levar um arquivo para a área de análises formais.
- Documentação operacional duradoura: manter quando servir como manual reutilizável. Uma implantação pontual não precisa gerar automaticamente um novo diretório de implantação.
A quantidade de arquivos, o versionamento, a distribuição e a inclusão no contexto do modelo devem ser decididos separadamente. Concentrar tudo em uma pasta não substitui essas regras.
O que as fontes de Geoffrey Huntley permitem concluir
Em seu texto sobre back pressure — ou contrapressão —, Geoffrey Huntley destaca o valor de estruturar o trabalho de agentes com feedback automatizado sobre qualidade e correção.12 Isso não é um argumento para tratar arquivos de teste como ruído a ser eliminado.
Em um exemplo específico de migração de software entre linguagens, Huntley propõe resumir o comportamento dos testes em especificações antes de orientar a migração.14 É uma abordagem para esse cenário, não uma prova de que a documentação deva substituir os testes em todos os projetos.
A aplicação razoável ao V4 é manter feedback executável para verificar a correção e reduzir materiais de validação pontuais ou duplicados. Especificações ajudam a descrever o comportamento esperado; testes permitem confrontar essa expectativa com a execução. Um não deve substituir o outro sem avaliação.
As fontes consultadas não permitem identificar um padrão geral de Huntley para versionar testes, organizar rascunhos ou excluir arquivos de pacotes. Também não há evidência suficiente para atribuir consenso aos fóruns mencionados cuja pesquisa não foi concluída.
Documentos longos: controlar o que é lido
Pesquisas sobre contextos extensos examinam a dificuldade dos modelos em utilizar informações que aparecem no meio de uma entrada. O HELMET, por sua vez, destaca a necessidade de avaliar modelos de contexto longo com diferentes tipos de tarefa, em vez de depender apenas de testes simples de recuperação de informação.3
4 Esses estudos não demonstram que um arquivo acima de determinado número de linhas cause alucinações, nem quantificam diretamente o risco no V4.
Medidas mais proporcionais incluem:
- Dividir documentos por tema e limite de decisão, em vez de ampliar indefinidamente um arquivo geral.
- Consultar por padrão as seções relevantes para a tarefa; buscar materiais históricos quando necessário.
- Manter resumos curtos com referências às evidências, incertezas e pendências, deixando os materiais originais disponíveis para consulta.
- Usar índices para navegação, sem copiar o conteúdo e criar uma segunda versão dos mesmos fatos.
- Evitar que logs e relatórios antigos sejam enviados integralmente ao modelo por padrão.
Mudanças mínimas recomendadas para o V4
Em vez de introduzir um processo pesado, o V4 pode adotar uma regra de ciclo de vida dos artefatos, da criação à distribuição:
- Antes de criar: esclarecer a finalidade do material e preferir atualizar testes ou documentos existentes a gerar um novo arquivo automaticamente a cada mudança.
- Antes de salvar: definir o caminho autorizado, se o material é temporário ou duradouro, se será versionado e se poderá ser distribuído. Na dúvida, não inventar um diretório por conta própria.
- Antes de enviar uma alteração: procurar saídas temporárias, conteúdo sensível e testes ou documentos duplicados. Remover todos os testes não é uma forma aceitável de simplificar a árvore.
- Antes de distribuir: definir claramente quais arquivos podem entrar no pacote, impedindo que materiais temporários sejam incluídos. Simplificações não devem eliminar proteções existentes para resumos, identidade ou ativos.
- Antes de limpar: preservar evidências de falhas, tarefas em andamento e referências históricas. O sucesso de uma tarefa ou a idade de um arquivo não autorizam, por si só, sua exclusão.
A conclusão mais prudente é fechar primeiro as regras para materiais temporários e limites de distribuição; depois, alinhar as funções dos documentos e adotar leitura sob demanda. As evidências disponíveis não justificam migrar todos os testes de Go, deixar de versionar testes duradouros ou consolidar toda a documentação em um único arquivo.
Se uma mudança for autorizada no futuro, os critérios de aceitação devem incluir a preservação da descoberta de testes, a compatibilidade com a CI pertinente, a exclusão de materiais temporários dos pacotes e a possibilidade de rastrear referências históricas e pendências. Nesta análise, nenhum arquivo foi alterado, nenhum comando ou teste foi executado e nenhuma limpeza ou etapa de um plano de trabalho foi iniciada.
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 manter testes úteis e documentos enxutos no V4"?
A recomendação não é deixar de versionar testes: testes duradouros devem continuar como parte da manutenção do projeto; verificações pontuais e seus resultados precisam de tratamento separado.
Quais são os pontos-chave para validar primeiro?
A recomendação não é deixar de versionar testes: testes duradouros devem continuar como parte da manutenção do projeto; verificações pontuais e seus resultados precisam de tratamento separado. O V4 já diferencia análises, decisões, planos e contratos, mas ainda há lacunas nas regras para materiais temporários e limites de distribuição.
O que devo fazer a seguir na prática?
A quantidade de arquivos, o que é versionado, o que é instalado e o que é enviado ao modelo são decisões distintas — uma pasta única não resolve todas elas.
Fontes
go.devAdd a test
ghuntley.comdon't waste your back pressure
doi.orgFound in the Middle: How Language Models Use Long Contexts Better via Plug-and-Play Positional Encoding