research-harness

Harness de pesquisa

O modelo raramente é o que quebra em trabalhos longos de experimentação. O que quebra é o espaço ao redor dele: uma divisão que mudou silenciosamente, um número digitado à mão, um conjunto de teste que vazou para o treinamento, uma sexta variante de uma ideia que já falhou, um loop de polling que travou a conta. Este skill move essas regras para fora da prosa e para dentro de arquivos, código e ganchos, seguindo a estrutura de harness / loop / graph da engenharia de agentes.

As três camadas, mapeadas para experimentos

Harness (o espaço).

• contract.json: afirmação, protocolo, porta, regras de computação. Congelado.
• CLAUDE.md: um mapa curto do projeto, não um manual.
• frozen/: listas de divisão, eval.py, números de linha de base copiados. Bloqueados por hash e somente leitura.
• harness/launch.py: a única maneira de iniciar uma execução. Ele impõe a lista de permissões de GPU e a regra de inatividade e inicia o job de forma destacada.
• traces.jsonl: uma linha por evento.
• state.json: a decisão da porta.
• lessons.md: erros que custaram uma correção duas vezes.

Loop (o tempo).

• L1 loop de verificação: frozen/eval.py pontua cada execução. É a única fonte de métricas.

• As saídas são decididas pelo código (harness/gate.py):

  • PASS: o candidato supera a referência pela margem.
  • BUDGET_EXIT: número máximo de variantes atingido.
  • STALL_EXIT: nenhum ganho por N rodadas.
  • REPRO_FAIL: nossa reimplementação da linha de base está muito distante do artigo.

  O modelo nunca declara "pronto" por conta própria.

• L4 espera por mudança: cada job escreve runs/<id>/DONE por último. Espere por esse arquivo com um único observador em segundo plano, não com polling repetido.

Graph (a rota). Mantido deliberadamente pequeno: divisões → congelar → características → execução de referência (reimplementação da linha de base) → variantes candidatas → porta → redação. Cada seta é um contrato de arquivo (um TSV de divisão, um DONE.json de características, um scores/ de execução).

Configurando um projeto

1. Copie template/ para o projeto no servidor. Copie o código da tarefa para src/ (examples/aigi/ é um exemplo completo para detecção de imagem gerada por IA).
2. Escreva contract.json a partir de template/contract.example.json:
   • claim: uma frase com um número;
   • protocol: exatamente como o artigo de origem define; liste cada detalhe não especificado e a escolha feita em open_questions;
   • gate: tag de referência, valor do artigo, margem, orçamento;
   • compute: caminho do python, lista de permissões de nó/GPU, regra de inatividade.
3. Escreva paths.json (raízes do conjunto de dados) e copie os números de linha de base para frozen/baselines.json. Analise-os do PDF com um script que verifique novamente as médias; nunca os redigite manualmente.
4. Congele: python harness/freeze.py add contract.json frozen/eval.py frozen/baselines.json.
5. Gere divisões através de launch.py, leia as contagens do manifesto e, em seguida, congele as divisões.
6. Instale o gancho de proteção na máquina que executa o Claude Code:
   • copie hooks/research_guard.py para <project>/.claude/hooks/;
   • escreva <project>/.claude/research_guard.json, usando o nome do diretório do projeto remoto como uma entrada project_markers;
   • mescle hooks/settings.snippet.json em <project>/.claude/settings.json.

Regras operacionais

• Os números vêm apenas de result.json ou da linha da porta. Cite-os; nunca calcule ou redigite métricas no chat. Se um número não estiver em um arquivo que eval.py escreveu, ele ainda não existe.
• Inicie execuções apenas através de launch.py. Ele recusa IDs de execução reutilizados, arquivos congelados alterados e GPUs ocupadas, e registra os hashes de código para cada execução.
• Uma execução, uma pergunta. Use o ID de execução e a tag para dizer o que está testando (gfre_repro_s0, ml_l12-24_k256). Variantes da ideia candidata compartilham a candidate_tag da porta. Qualquer outra coisa, como depuração ou testes de fumaça, usa uma tag diferente para não consumir orçamento.
• Respeite a porta.
  • CONTINUE significa que você pode tentar outra variante.
  • BUDGET_EXIT, STALL_EXIT e REPRO_FAIL significam pare e leve as evidências ao humano. Não remende a ideia uma sexta vez.
• O protocolo congelado nunca muda no meio do projeto. Se precisar mudar (um bug em uma divisão, um detalhe do protocolo aprendido com os autores), um humano edita FROZEN.sha256 e um novo congelamento começa. Resultados anteriores permanecem em results.jsonl com seu próprio histórico.
• Espere por arquivos DONE com um único observador em segundo plano. Toda chamada ssh dentro de um loop usa -o BatchMode=yes e para no código de saída 255.
• Após cada execução, leia a saída de status.py, não os logs brutos. Abra log.txt apenas em caso de falha.
• Quando um erro se repetir, adicione uma linha a lessons.md e transforme-o em uma verificação, se possível (um assert em src/, uma regra de gancho, uma verificação de manifesto).

Revisão (antes de confiar em um PASS)

Gere um subagente revisor por lente. Dê a cada um o código e os arquivos, não sua conclusão:

1. Vazamento: os arquivos de treino, validação e teste se sobrepõem? Os padrões excluídos são realmente excluídos? Os rótulos de teste alguma vez chegam ao código de treinamento?
2. Protocolo: as divisões, conjuntos de teste, limiar e métrica correspondem ao artigo de origem e ao contract.json? As escolhas de open_questions são divulgadas?
3. Comparação justa: a reimplementação da referência está dentro da tolerância? Os números de linha de base copiados são do mesmo protocolo? Quaisquer linhas de base reexecutadas estão marcadas?

Um revisor vale exatamente tanto quanto as decisões que ele muda. Cada lente retorna evidências concretas de arquivo/linha ou nada.

Arquivos

template/                 copie para um novo projeto
  CLAUDE.md               mapa (edite o título)
  contract.example.json   afirmação / protocolo / porta / computação
  lessons.md
  harness/                launch.py job.sh gate.py status.py freeze.py check_frozen.py trace.py common.py
  frozen/eval.py          avaliador de detecção binária (ACC no limiar + AP por conjunto de teste)
hooks/                    research_guard.py + configuração de exemplo + snippet de configuração
examples/aigi/            Detecção de imagem gerada por IA: divisões GenImage + CNNDetection, cache de
                          características CLIP, detector de reconstrução estilo GFRE, analisador de tabela GFRE

Crédito: a estrutura harness / loop / graph segue o "Harness, Loop and Graph" de @0xwhrrari (Novembro 2026).