QA da Cloud.ru reduziu uma tarefa de autotestes de meio dia para 1 a 1,5 hora com o OpenSpec

O agente escreveu os testes, o código está limpo, o pytest mostra verde. Dá para fechar a tarefa? Nem sempre. Um engenheiro de QA da Cloud.ru contou como, depois de vários casos assim, montou um processo com quatro agentes e especificações. Agora ele gasta mais tempo com requisitos e riscos do que com o código em si.

Um teste verde que não prova nada

No projeto existe uma funcionalidade de publicação da estrutura da documentação no Git. Se, em uma nova publicação, uma seção desaparece da estrutura, o arquivo correspondente deve ser removido do repositório. O agente escreveu o teste test_update_structure_removes_orphan_doc_file. Ele publica a estrutura com as seções overview e setup, depois a publica novamente sem setup, clona o repositório e verifica que o arquivo setup não existe.

Parece razoável: verifica-se o estado real do Git, e não apenas a resposta da API. Mas, antes da remoção, o agente nunca confirmou que o arquivo estava lá. A presença do documento era confirmada por get_repowiki_docs(), e esse método pode retornar metadados sem olhar o repositório em si. Se o arquivo não tiver aparecido na primeira publicação, o teste passa de qualquer forma: depois da segunda publicação ele também não existe. O teste verifica o estado final, mas não a transição «o arquivo existia — o arquivo não existe mais».

A autoverificação do agente desenvolvedor não percebeu isso: ele analisou a lógica do teste, mas não fez experimentos. O problema foi encontrado por outro agente, o revisor. Depois disso, foi adicionado ao teste um passo com repowiki_repo_clone() as clone_before, que verifica a presença do arquivo antes da nova publicação. A mesma classe de erros aparece em casos simples: o agente verifica o HTTP 400, mas não olha a estrutura do corpo do erro.

Como o processo funciona

O autor abre o Claude Code e entrega ao agente principal, o orquestrador, o número da tarefa do Jira. As regras estão descritas no arquivo CLAUDE.md do repositório: quais agentes existem, pelo que respondem, como passar de uma etapa para outra e quando é necessária a confirmação humana. Atualmente são quatro agentes:

• test-planner pesquisa a tarefa e os testes existentes e cria um OpenSpec change. Nele ficam proposal.md (por quê), design.md (abordagem e restrições) e tasks.md (passos concretos). Em seguida, o plano passa por openspec validate --strict.
• test-qa-writer implementa os testes conforme o tasks.md e marca os itens concluídos.
• test-reviewer confronta a implementação com a especificação e os acordos de arquitetura. Ele mesmo não executa os testes, trabalhando apenas com o código e os artefatos.
• docs-writer atualiza a documentação.

O humano entra em dois momentos. O primeiro é depois do plano: ele verifica se o agente entendeu corretamente a tarefa, se não há casos esquecidos e se a solução se encaixa na arquitetura do projeto de testes. Dúvidas sobre a lógica de negócio ele esclarece com os desenvolvedores. O segundo é depois da revisão: o orquestrador traz a conclusão, e a decisão de refazer ou arquivar é tomada pelo humano.

No change permanecem qa-report.md e review.md. Assim, a tarefa mantém um histórico: o que foi planejado, o que foi feito e quais observações surgiram.

Verificação de que não é «bobagem»

Além da revisão, o autor faz execuções reais e verifica a sensibilidade dos testes. Por exemplo, altera de propósito o valor esperado no assert e observa se o teste falha. Não é um teste de mutação completo do serviço, mas uma forma barata de garantir que as asserções realmente verificam alguma coisa.

Há também uma ressalva honesta. O desenvolvedor e o revisor podem trabalhar com o mesmo modelo. A separação de papéis não torna a verificação totalmente independente, mas muda a posição e os critérios de avaliação. Foi exatamente esse esquema que pegou o caso do arquivo setup.

O que levar daqui

O autor avalia o ganho assim: em vez de meio dia de trabalho, a tarefa leva cerca de uma a uma hora e meia, e parte do trabalho os agentes fazem enquanto ele está ocupado com outra coisa. A estimativa é aproximada e reflete a experiência de uma pessoa em um projeto. Para tarefas pequenas, ele próprio admite simplificar o processo.

Conclusões práticas para equipes que delegam testes a agentes:

• Inclua nos critérios de aceitação a verificação do estado inicial, e não apenas do final. Para qualquer teste do tipo «depois da ação X algo mudou», é preciso um passo que confirme que, antes de X, isso não existia.
• Não confunda a autoverificação do executor com revisão. Uma passagem separada, com outro papel e outro prompt, pega o que o autor do código não vê.
• Guarde as especificações e as conclusões de revisão no repositório, junto do código.
• Mantenha o humano em dois pontos de decisão: aprovação do plano e aceitação do resultado.

O artigo original segue analisando o caso do CRUD para tags do Git: havia três testes para GET /tags que verificavam apenas o campo name, e não havia cobertura para POST e DELETE. Mas a principal conclusão já é visível pela descrição do processo. Os agentes assumem a implementação, mas os requisitos e a qualidade final continuam sendo responsabilidade do humano.