Spec-to-Code Ratio

A Razão de Especificação para Código (SCR) mede a porcentagem de Especificações Vivas que resultam em um pull request funcional sem a necessidade de reescrita de código humano. É calculada da seguinte forma:

PRs mesclados sem alterações de código humano / Total de PRs gerados por agente

Um PR é considerado "sem alterações humanas" quando passa pelo Eval Harness, passa pela revisão humana e é mesclado sem modificações além de formatação trivial. Qualquer edição substancial de código por um revisor humano — correção de lógica, adição de tratamento de erros ausente, reestruturação de uma abordagem — desqualifica o PR do numerador.

Intervalos-alvo para equipes maduras:

• Acima de 0.7 — as especificações da equipe são precisas o suficiente para que os agentes produzam código pronto para mesclagem em mais de 70% do tempo. Este é o alvo para equipes com fluxos de trabalho agentivos estabelecidos.
• 0.5 a 0.7 — funcional, mas com espaço para melhorias. As especificações são geralmente sólidas, mas casos de borda ou restrições arquitetônicas são rotineiramente subespecificados.
• Abaixo de 0.5 — as especificações não são detalhadas o suficiente para uma execução confiável do agente. Mais da metade da saída do agente requer reescrita humana, o que anula grande parte do benefício de produtividade dos fluxos de trabalho agentivos.

A SCR é a métrica mais acionável para a função de Arquiteto de Contexto. Quando ela cai, a causa quase sempre remonta à qualidade da especificação, e não à capacidade do agente:

1. Critérios de aceitação ambíguos — a especificação não define condições claras de aprovação/reprovação, deixando o agente adivinhar a intenção.
2. Casos de borda ausentes — a especificação cobre o caminho feliz, mas omite o tratamento de erros, condições de limite ou cenários de concorrência.
3. Golden Samples Desatualizados — os Golden Samples incluídos no Pacote de Contexto não refletem mais os padrões atuais da base de código, fazendo com que o agente produza código estruturalmente desatualizado.

Acompanhar a SCR juntamente com a Taxa de Correção fornece uma imagem completa: a SCR mede se a especificação foi boa o suficiente para acertar na primeira vez, enquanto a Taxa de Correção mede quanto esforço foi necessário para corrigi-la quando não foi.