Desenvolvi ckdn para que agentes de codificação nunca precisem adivinhar se os testes passaram

Se você executa um agente de codificação em um projeto real, provavelmente já viveu todos esses três momentos.

Momento um. O agente executa sua suíte de testes. O terminal responde com milhares de linhas — pontos de progresso, uma linha de cobertura por módulo, listas de linhas ausentes, avisos, rastreamentos de pilha. O agente lê isso com diligência. Você assiste a um pedaço de contexto de cinco dígitos evaporar em ruído de formatação. Então o loop de correção itera, e isso acontece novamente. E novamente.

Momento dois. O agente lê aquela parede e alegremente relata que tudo passou. Não passou. Um erro de coleta matou a execução antes que um único teste fosse executado — código de saída diferente de zero, mas sem linhas FAILED em lugar algum. Nada parecia ter falhado, então o agente chamou isso de verde.

Momento três. A verificação finalmente fica verde — porque o agente silenciosamente abaixou o limite de cobertura. Ou deletou o teste inconveniente. Tecnicamente, você pediu para que ele fizesse o CI passar.

Três falhas diferentes, uma causa raiz: na maioria dos loops de agentes, verificação é interpretação de texto. O modelo lê a saída do terminal e decide, a partir da prosa, se a execução parece verde. Essa decisão é cara a cada vez, errada ocasionalmente e manipulável sempre.

Eu continuei enfrentando os três momentos em meus próprios projetos, cansei disso e construí ckdn. Ele atingiu a versão v1.0.0 esta semana. Este post é o porquê e o como — na ordem desses três momentos.

Por que "checkdown"?

É um ano de Copa do Mundo, então perdoe uma metáfora de futebol — futebol errado, ideia certa. No jogo americano, um checkdown é o passe curto e seguro que um quarterback lança em vez de forçar uma jogada longa arriscada.

Esse é exatamente o trabalho desta ferramenta. Em vez de jogar um log inteiro do terminal no contexto do modelo e esperar que a jogada longa se conecte, o ckdn entrega ao agente um resultado curto, seguro e pegável. O nome do pacote é encurtado para ckdn; a ideia permanece a mesma:

Deixe os agentes se moverem rapidamente. Dê a eles um caminho de verificação seguro.

Momento um, resolvido: resumos em vez de logs

ckdn fica entre o agente e suas ferramentas de verificação. Cada verificação configurada passa por um orquestrador que executa o subprocesso real, arquiva a saída completa como evidência, analisa o relatório legível por máquina e emite um resumo limitado e determinístico — a única coisa que o agente lê.

Em um dos meus projetos, uma única execução de teste mais cobertura bem-sucedida produziu aproximadamente 14.000 tokens de saída do terminal. A conclusão útil foi de quatro linhas:

4250 testes passaram
cobertura: 99.18%
requerido: 99%
status: passar

Aqui está como uma verificação bem-sucedida se parece através do ckdn — este é o stdout completo:

{
  "check": "pytest",
  "rc": 0,
  "run_dir": ".agent-runs/20260710T173400Z-pytest",
  "schema": "ckdn.digest/2",
  "status": "pass",
  "summary": {
    "counts": {
      "tests": 144
    }
  }
}

Dupla ordem de magnitude mais barata — e o loop de correção paga esse preço por iteração, então as economias se multiplicam. Resultados verdes permanecem pequenos. Falhas carregam evidências limitadas: principais descobertas com locais e trechos, contagens, contadores de truncamento explícitos. O log completo permanece no disco para o raro caso em que alguém realmente precise dele.

Momento dois, resolvido: código de saída e evidência devem concordar

A história do falso verde da introdução não é hipotética — é a falha canônica de qualquer verificador "leia o texto e decida", e está a um desvio de formato a qualquer momento.

ckdn recusa isso estruturalmente, combinando duas fontes independentes de verdade:

• o código de saída do subprocesso real, de propriedade do orquestrador;
• evidência extraída por um analisador ciente de formato — JUnit XML, cobertura XML, relatórios JSON; artefatos legíveis por máquina sempre que a ferramenta oferecer um, texto do terminal apenas como último recurso e então com guardas de desvio.

Os dois devem concordar antes que um resultado se torne pass.

ckdn pode rebaixar o verde. Ele nunca eleva o vermelho.

Cada execução termina em exatamente um dos quatro estados:

parse_mismatch é o status que a maioria das ferramentas não tem e a razão pela qual esta existe. Quando o código de saída diz "tudo bem" e o relatório JUnit diz "uma falha", algo está errado — com a ferramenta, o analisador ou a invocação — e a resposta certa é um alarme alto, não um veredicto silencioso de qualquer forma.

Um analisador nunca decide o status final. Ele relata fatos; uma camada de reconciliação separada possui o veredicto, e testes de contrato fixam suas invariantes: um código de saída diferente de zero nunca pode se tornar pass; evidências contraditórias invalidam um código de saída zero; desvio do analisador se torna um error alto, nunca um limpo silencioso.

Momento três, resolvido: o repositório possui as verificações

ckdn não é um shell arbitrário entregue a um agente de IA. As verificações são declaradas pelo repositório em ckdn.toml:

[check.pytest]
command = "uv run pytest -q --junitxml {run_dir}/junit.xml"
parser = "pytest"

[check.coverage]
command = "uv run pytest -q --junitxml {run_dir}/junit.xml --cov=src --cov-report=xml:{run_dir}/coverage.xml"
parser = "coverage"