Harness: o nome do que estou construindo
Na última reunião do TCC ficou definido o próximo passo: uma versão final do orquestrador, mais madura, em formato de CLI, que não sirva apenas para gerar código do zero mas também para dar manutenção em código que já existe.
Assim que escrevi isso, percebi que estava descrevendo o funcionamento de ferramentas tipo o Codex/Claude Code/Agentes via terminal. Fui atrás de entender melhor e o nome disso já existe: harness.
Definição
A definição curta que passei a usar:
Harness := ambiente onde a LLM sugere mudanças, não executa livremente.
A LangChain diz a mesma
coisa por outro ângulo, com uma equação: Agente = Modelo + Harness, onde o harness é
"todo pedaço de código, configuração e lógica de execução que não é o modelo em si".
É uma definição mais ampla que a minha. A minha é mais focada na parte que
interessa ao TCC: quem realmente tem autoridade para aplicar a mudança.
O repositório open source agents-best-practices resume essa parte em uma frase:
"The model proposes actions; the harness validates, authorizes, executes, records, and returns observations."
O loop
O loop padrão descrito no SKILL.md do agents-best-practices:
tarefa do usuário
-> montagem de instrução e contexto
-> chamada ao modelo
-> proposta de ação/ferramenta
-> validação de schema
-> decisão de permissão
-> execução ou pausa para aprovação
-> observação estruturada
-> atualização de contexto
-> repete dentro do orçamento ou termina
Os meus orquestradores já implementam pedaços disso.
O y/n entre etapas do v2 e do v3 é a pausa para aprovação,
e os schemas Pydantic (Criterios, VeredictoCUA) são a validação de schema.
O que falta é o resto: orçamento de passos e custo, permissão por ferramenta,
trace de eventos e uma forma de operar sobre um repositório que já existe.
Onde o TDD entra
Num harness genérico, a observação estruturada pode ser qualquer coisa: saída de shell, resposta de API, print de tela. No meu caso ela tem nome e formato desde o v1, que são os testes. O TDD deixa de ser só a metodologia do pipeline e passa a ser o sinal de feedback do loop. O CUA continua onde sempre esteve, como avaliador comportamental final. Isso não muda a pergunta de pesquisa, muda o vocabulário que uso para descrever o artefato.
Referência de implementação
O mini-swe-agent, feito pelo time de Princeton e Stanford por trás do SWE-bench e do SWE-agent, é o melhor argumento de que o harness final pode ser simples:
| Decisão | Consequência |
|---|---|
| ~100 linhas na classe do agente | dá para ler inteiro de forma simples |
| nenhuma ferramenta além do bash | roda com qualquer modelo, sem interface de tool calling |
| histórico linear | a trajetória é literalmente a lista de mensagens |
subprocess.run por ação, sem sessão de shell persistente | trocar por docker exec é trocar uma linha |
E ainda assim marca mais de 74% no SWE-bench verified, o que é um bom argumento para não começar por uma arquitetura enorme que cresça de forma descontrolada.
O OpenHarness está no extremo oposto:
43 ferramentas, hooks de PreToolUse e PostToolUse, modos de permissão em vários níveis
e coordenação multiagente. Serve mais como catálogo do que como base.
Dá para ver ali tudo que um harness pode ter, escolher o pouco que o experimento precisa
e ignorar o resto.
Próximos passos
- Levantar as boas práticas aplicáveis ao meu caso (orçamento, permissões, trace)
- Definir o contrato de entrada do modo manutenção (repositório existente + requisito)
- Só então escrever o orquestrador final em CLI, com o mini-swe-agent como base estrutural