Engenharia de Harness
A engenharia de harness projeta o sistema de controle em torno de um agente: o que ele pode editar, como recebe feedback, onde escreve estado, como as falhas se recuperam e quem pode aprovar ações irreversíveis. O harness é a diferença entre uma sessão de agente útil e um loop autônomo que pode rodar por dias sem corromper seu objetivo.
Quando Ativar
Ative esta skill quando:
- Construir loops autônomos de pesquisa ou experimentação
- Projetar um ambiente de agente com métricas travadas e código ou conteúdo editável
- Criar agentes que produzem PRs ou agentes em segundo plano
- Avaliar se um agente pode rodar com segurança sem solicitações humanas frequentes
- Adicionar novidade, ablação, poda, rollback ou registro durável a um fluxo de trabalho de agente
- Impedir que agentes manipulem benchmarks, enfraqueçam rubricas ou percam estado durante compactação
Não ative esta skill para trabalhos adjacentes de propriedade de outras skills:
- Portões de qualidade gerais, suítes de regressão ou métricas de resultado sem superfícies de controle autônomo:
avaliação. - Esquemas de ferramentas, formatos de resposta e erros de recuperação para ferramentas de harness:
design-de-ferramentas. - Ajuste modelo-tarefa em nível de projeto, formato do pipeline e planejamento de custos:
desenvolvimento-de-projeto. - Infraestrutura de sandbox remoto, pool aquecido e sessão hospedada:
agentes-hospedados.
Conceitos Principais
Limite do Harness
Separe o agente do ambiente em que ele opera. O agente propõe ações; o harness define superfícies permitidas, feedback, persistência e regras de promoção.
Use quatro classes de superfície:
| Superfície | Exemplos | Regra |
|---|---|---|
| Travada | Métrica de avaliação, rubrica, script de validação, política de merge | O agente pode ler e propor alterações, mas não pode se autoavaliar com regras modificadas |
| Editável | Rascunho de skill, arquivo de experimento, prompt, configuração sob teste | O agente pode alterar durante o loop |
| Append-only | Log de resultados, thread de pesquisa, ideias rejeitadas | O agente pode anexar, não reescrever |
| Controlada por humano | Merge, deploy de produção, credenciais, operações destrutivas | Requer aprovação humana explícita |
Loops de Feedback Apertados
A autonomia funciona quando o feedback é rápido, inequívoco e difícil de manipular. O autoresearch de Karpathy é o padrão mínimo: um arquivo editável, um arquivo de avaliação travado, orçamento de tempo fixo, uma métrica escalar, rollback via git e um log de resultados durável. A lição não é que todo harness precise de uma métrica; é que feedback ambíguo gera autonomia ambígua.
Para trabalhos abertos de pesquisa-para-skill, substitua a métrica escalar por rubricas travadas, verificações estruturais determinísticas, rastreabilidade de fontes e limites de revisão humana.
Estado Durável
Agentes de longa duração devem externalizar o estado. Armazene planos, filas de fontes, resultados, falhas e passagens em arquivos para que agentes futuros possam continuar sem depender do histórico do chat. O trabalho autônomo nanoGPT da Prime Intellect mostrou o valor de blocos de rascunho duráveis e logs no estilo THREAD.md para recuperação, monitoramento e auditoria.
Use logs append-only para:
- O que foi tentado
- O que melhorou ou falhou
- Por que um candidato foi mantido, descartado ou encaminhado para revisão
- Quais fontes upstream foram verificadas
- O que o próximo agente deve fazer
Disciplina de Busca
Agentes tendem a explorar a superfície mais próxima, acumular complexidade e executar pouca poda. Adicione regras de busca explícitas:
- Atualize fontes upstream em um cronograma.
- Exija verificações de novidade antes de gastar grandes orçamentos.
- Preserve tentativas rejeitadas para evitar redescoberta.
- Execute poda leave-one-out quando uma pilha tiver múltiplas adições.
- Recompense simplificação quando a qualidade for igual.
- Use verificação separada antes da promoção.
Registro de Mecanismos
Para sistemas de pesquisa-para-skill, rastreie mecanismos aceitos separadamente da prosa. Um registro de mecanismo deve incluir um mechanism_id estável, owning_skill, status, cenário de ativação, mudança de comportamento, evidência e modos de falha. Portas de novidade devem comparar com este registro antes de usar sobreposição mais ampla de corpus, porque a sobreposição de palavras-chave captura frases obsoletas, enquanto a comparação de mecanismos captura duplicação real.
Governança
Agentes autônomos podem preparar PRs, mas a governança deve ser explícita. Eles podem rascunhar alterações, executar verificações e escrever resumos de PR. Eles não devem fazer merge, deploy ou push sem aprovação humana, a menos que o usuário tenha concedido explicitamente essa permissão para a ação específica.
Tópicos Detalhados
Loop Estilo Autoresearch
Use este padrão ao otimizar um artefato contra um avaliador estável:
ler contexto travado -> escolher hipótese -> editar superfície permitida -> commit/checkpoint
-> executar avaliador -> registrar resultado -> manter se melhor -> descartar ou reverter se pior
-> repetir
Propriedades necessárias:
- O avaliador está fora da superfície editável.
- A cadência de feedback é fixa o suficiente para comparar tentativas.
- Tentativas fracassadas deixam uma trilha de auditoria.
- Rollback é barato.
- O agente tem uma política para falhas e timeouts.
Loop Pesquisa-Para-Skill
Use este padrão quando as fontes se tornam alterações de skill:
descobrir -> recuperar -> portão -> pontuar -> extrair mecanismo
-> mapear para skill existente ou nova -> rascunhar proposta -> validar estrutura
-> preparar PR -> revisão humana
O avaliador travado é uma combinação de rubricas de fonte, rubricas de mudança de skill, verificações estruturais e aprovação do revisor. O artefato editável é o delta proposto da skill.
Resistência a Manipulação de Métricas
Presuma que um agente otimizador aprenderá o harness. Proteja-se contra:
- Editar código de avaliação ou rubricas e depois usar a nova versão para autoaprovação
- Adicionar conteúdo prolixo que agrada um juiz, mas prejudica a ativação da skill
- Citar fontes não recuperadas
- Otimizar pontuações agregadas enquanto falha em uma dimensão crítica
- Omitir resultados fracassados no log
Mitigação: trave rubricas por execução, reporte pontuações por dimensão, exija evidência de recuperação de fonte, preserve tentativas rejeitadas e encaminhe mudanças de governança para revisão humana.
Agentes de Monitoramento
Use agentes de monitoramento para execuções longas, mas restrinja-os a relatórios somente leitura, a menos que explicitamente encarregados de outra forma. A saída do monitoramento deve relatar:
- Melhor candidato atual
- Trabalhos ou rascunhos ativos
- Última atualização upstream
- Loops com falha ou obsoletos
- Discrepâncias entre logs e estado declarado
- Próxima ação e bloqueador
Orientação Prática
Checklist de Design de Harness
- Defina o objetivo em uma frase.
- Identifique superfícies travadas, editáveis, append-only e controladas por humano.
- Escolha o mecanismo de feedback: métrica escalar, rubrica, testes determinísticos, revisão humana ou combinação.
- Defina estados de manter, descartar, crash, timeout e revisão.
- Crie um log de thread durável antes do loop começar.
- Adicione regras de atualização de fonte, novidade via registro de mecanismo e poda para loops de longa duração.
- Defina o que o agente pode fazer sem perguntar e o que requer aprovação.
- Valide o harness em um artefato sabidamente bom e um sabidamente ruim.
Estrutura de Arquivos
pesquisa-run/
THREAD.md
fontes/
queue.md
avaliacoes/
propostas/
logs/
resultados.tsv
rejeitadas.md
rascunhos/
Use TSV ou JSONL para logs append-only legíveis por máquina. Use Markdown para passagens e resumos voltados para revisores.
Exemplos
Exemplo 1: Métrica travada
Um agente otimiza train.py, mas prepare.py é dono do carregamento de dados e da avaliação. O agente pode editar o modelo, mas não pode alterar a métrica. Experimentos fracassados são registrados e revertidos.
Exemplo 2: Rubrica travada
Um agente avalia um novo post de engenharia da Anthropic ou OpenAI, mas a rubrica de curadoria de fonte está travada para a execução. Se a fonte passar, o agente rascunha uma proposta de skill. Ele não pode reduzir o limite da rubrica para admitir a fonte.
Exemplo 3: Auto-PR sem auto-merge
Um agente prepara uma branch e o corpo do PR após passar nas verificações de fonte, skill e estrutura. O PR declara riscos não resolvidos e aguarda aprovação humana para merge.
Diretrizes
- Trave avaliadores antes de iniciar o loop.
- Mantenha superfícies editáveis estreitas o suficiente para diffs confiáveis.
- Escreva logs duráveis antes que a compactação de contexto possa apagar o estado.
- Reporte pontuações por dimensão em vez de apenas pontuações agregadas.
- Exija recuperação de fonte antes da citação.
- Adicione portas de novidade para busca ampla e portas de poda para pilhas complexas.
- Prefira simplificação quando a qualidade for igual.
- Separe a preparação de PR da autoridade de merge.
- Revalide alterações de harness com avaliadores antigos e novos.
- Trate loops autônomos interrompidos como falhas de harness, não peculiaridades de personalidade do agente.
Pegadinhas
- Avaliador mutável: Se o agente pode editar a métrica, ele pode otimizar o benchmark em vez da tarefa. Mantenha rubricas e código de avaliação travados durante a execução.
- Memória só do chat: Execuções longas falham após compactação quando os planos vivem apenas no histórico da conversa. Escreva logs de thread e arquivos de resultado desde o início.
- Sem registro de descarte: Sem logs de tentativas rejeitadas, agentes repetem ideias fracassadas. Preserve falhas com detalhes suficientes para evitar redescoberta.
- Acúmulo de complexidade: Agentes acumulam mudanças e raramente as removem. Exija rodadas de poda e recompense simplificação com qualidade igual.
- Alegações prematuras de novidade: Agentes rotulam recombinações como novidade. Compare com skills existentes do repositório, fila de fontes e logs rejeitados antes de alegar novidade.
- Relatório incorreto do monitor: Agentes de monitoramento podem resumir estado obsoleto ou inconsistente. Exija que citem os arquivos ou logs por trás das alegações.
- Ambiguidade de aprovação humana: "Preparar um PR" não é "fazer merge de um PR." Torne os limites de aprovação explícitos no harness.
- Desvio volátil de fonte: Reivindicações de laboratórios em rápida evolução envelhecem rapidamente. Coloque evidências datadas nas referências e agende revalidação.
Integração
Esta skill se conecta com:
- avaliação - Rubricas e portões de qualidade fornecem a superfície de feedback travada
- avaliação-avançada - Comparação pareada e mitigação de viés melhoram a revisão de propostas
- contexto-de-sistema-de-arquivos - Logs duráveis, blocos de rascunho e arquivos de thread preservam estado
- padrões-multi-agente - Agentes pesquisador, verificador, monitor e escritor precisam de contextos isolados
- design-de-ferramentas - Ferramentas de harness devem expor contratos claros e erros de recuperação
- desenvolvimento-de-projeto - Pipelines baseados em arquivos e análise de ajuste modelo-tarefa mantêm os loops simples
- agentes-hospedados - Execução em segundo plano precisa de sandbox, snapshot e limites de aprovação
Referências
Referências internas:
researcher/README.md- Leia ao implementar o sistema operacional pesquisa-para-skill nativo do repositórioresearcher/rubrics/mudanca-harness.md- Leia ao avaliar mudanças em um harness de agenteresearcher/runbooks/loop-autonomo-de-pesquisa.md- Leia ao executar um loop fonte-para-skill
Recursos externos:
- Karpathy
autoresearch- Loop de experimento autônomo restrito com avaliação travada - Prime Intellect autonomous nanoGPT speedrun - Blocos de rascunho duráveis, passagens, monitoramento e modos de falha de autonomia
- AlphaEvolve e FunSearch - Candidatos gerados por LLM emparelhados com avaliadores sistemáticos
- HELM e LM Evaluation Harness - Infraestrutura de avaliação transparente e reproduzível
Metadados da Skill
Criado: 2026-05-14 Última atualização: 2026-05-15 Autor: Contribuidores de Skills de Contexto para Engenharia de Agentes Versão: 1.1.0