research-harness

Arnés de investigación

Lo que rara vez se rompe en un trabajo experimental largo es el modelo. Lo que se rompe es el espacio que lo rodea: una división que cambió silenciosamente, un número tecleado a mano, un conjunto de prueba que se filtró al entrenamiento, una sexta variante de una idea que ya falló, un bucle de sondeo que bloqueó la cuenta. Esta habilidad traslada esas reglas de la prosa a archivos, código y ganchos, siguiendo el marco de arnés / bucle / gráfico de la ingeniería de agentes.

Las tres capas, mapeadas a experimentos

Arnés (el espacio).

• contract.json: afirmación, protocolo, compuerta, reglas de cómputo. Congelado.
• CLAUDE.md: un mapa corto del proyecto, no un manual.
• frozen/: listas de divisiones, eval.py, cifras de referencia copiadas. Bloqueado por hash y de solo lectura.
• harness/launch.py: la única forma de iniciar una ejecución. Impone la lista blanca de GPU y la regla de inactividad, e inicia el trabajo de forma desacoplada.
• traces.jsonl: una línea por evento.
• state.json: la decisión de la compuerta.
• lessons.md: errores que han costado una corrección dos veces.

Bucle (el tiempo).

• Bucle de verificación L1: frozen/eval.py puntúa cada ejecución. Es la única fuente de métricas.

• Las salidas las decide el código (harness/gate.py):

  • APROBADO: el candidato supera la referencia por el margen.
  • SALIDA_POR_PRESUPUESTO: se alcanzó el máximo de variantes.
  • SALIDA_POR_ESTANCAMIENTO: sin mejora durante N rondas.
  • FALLO_DE_REPRODUCCIÓN: nuestra reimplementación de la línea base está demasiado lejos del artículo.

  El modelo nunca declara "terminado" por sí mismo.

• L4 esperar cambio: cada trabajo escribe runs/<id>/DONE al final. Espera ese archivo con un único observador en segundo plano, no sondeos repetidos.

Gráfico (la ruta). Se mantiene deliberadamente pequeño: divisiones → congelar → características → ejecución de referencia (reimplementación de línea base) → variantes candidatas → compuerta → redacción. Cada flecha es un contrato de archivo (un TSV de divisiones, un DONE.json de características, un scores/ de ejecución).

Configuración de un proyecto

1. Copia template/ en el proyecto del servidor. Copia el código de la tarea en src/ (examples/aigi/ es un ejemplo completo para detección de imágenes generadas por IA).
2. Escribe contract.json a partir de template/contract.example.json:
   • afirmación: una frase con un número;
   • protocolo: exactamente como lo define el artículo fuente; enumera cada detalle no especificado y la decisión tomada en open_questions;
   • compuerta: etiqueta de referencia, valor del artículo, margen, presupuesto;
   • cómputo: ruta de Python, lista blanca de nodos/GPU, regla de inactividad.
3. Escribe paths.json (raíces de conjuntos de datos) y copia las cifras de referencia en frozen/baselines.json. Párseas del PDF con un script que vuelva a verificar los promedios; nunca las reescribas a mano.
4. Congela: python harness/freeze.py add contract.json frozen/eval.py frozen/baselines.json.
5. Genera las divisiones mediante launch.py, lee los conteos del manifiesto y luego congela las divisiones.
6. Instala el gancho de guardia en la máquina que ejecuta Claude Code:
   • copia hooks/research_guard.py a <project>/.claude/hooks/;
   • escribe <project>/.claude/research_guard.json, usando el nombre del directorio del proyecto remoto como entrada de project_markers;
   • fusiona hooks/settings.snippet.json en <project>/.claude/settings.json.

Reglas de operación

• Los números provienen únicamente de result.json o la línea de la compuerta. Cítalos; nunca calcules ni reescribas métricas en el chat. Si un número no está en un archivo que eval.py escribió, aún no existe.
• Inicia las ejecuciones solo mediante launch.py. Rechaza IDs de ejecución reutilizados, archivos congelados modificados y GPU ocupadas, y registra los hashes de código para cada ejecución.
• Una ejecución, una pregunta. Usa el ID de ejecución y la etiqueta para indicar lo que prueba (gfre_repro_s0, ml_l12-24_k256). Las variantes de la idea candidata comparten candidate_tag de la compuerta. Cualquier otra cosa, como depuración o pruebas de humo, usa una etiqueta diferente para que no consuma presupuesto.
• Respeta la compuerta.
  • CONTINUAR significa que puedes probar otra variante.
  • SALIDA_POR_PRESUPUESTO, SALIDA_POR_ESTANCAMIENTO y FALLO_DE_REPRODUCCIÓN significan detente y lleva la evidencia al humano. No remiendes la idea por sexta vez.
• El protocolo congelado nunca cambia a mitad del proyecto. Si debe cambiar (un error en una división, un detalle del protocolo aprendido de los autores), un humano edita FROZEN.sha256 y comienza una nueva congelación. Los resultados anteriores permanecen en results.jsonl con su propio historial.
• Espera los archivos DONE con un único observador en segundo plano. Cada llamada ssh dentro de un bucle usa -o BatchMode=yes y se detiene en el código de salida 255.
• Después de cada ejecución, lee la salida de status.py, no los registros sin procesar. Abre log.txt solo en caso de fallo.
• Cuando un error se repite, añade una línea a lessons.md y conviértelo en una verificación si es posible (una aserción en src/, una regla de gancho, una verificación de manifiesto).

Revisión (antes de confiar en un APROBADO)

Genera un subagente revisor por cada lente. Entrégale a cada uno el código y los archivos, no tu conclusión:

1. Fuga: ¿se superponen los archivos de entrenamiento, validación y prueba? ¿Están realmente excluidos los patrones excluidos? ¿Llegan alguna vez las etiquetas de prueba al código de entrenamiento?
2. Protocolo: ¿coinciden las divisiones, los conjuntos de prueba, el umbral y la métrica con el artículo fuente y contract.json? ¿Se divulgan las decisiones de open_questions?
3. Comparación justa: ¿está la reimplementación de referencia dentro de la tolerancia? ¿Provienen las cifras de referencia copiadas del mismo protocolo? ¿Están marcadas las líneas base rehechas?

Un revisor vale exactamente tanto como las decisiones que cambia. Cada lente devuelve evidencia concreta de archivo/línea o nada.

Archivos

template/                 copiar en un nuevo proyecto
  CLAUDE.md               mapa (editar el título)
  contract.example.json   afirmación / protocolo / compuerta / cómputo
  lessons.md
  harness/                launch.py job.sh gate.py status.py freeze.py check_frozen.py trace.py common.py
  frozen/eval.py          evaluador de detección binaria (ACC en umbral + AP por conjunto de prueba)
hooks/                    research_guard.py + configuración de ejemplo + fragmento de configuración
examples/aigi/            Detección de imágenes generadas por IA: divisiones GenImage + CNNDetection, almacenamiento en caché de características CLIP,
                          detector de reconstrucción estilo GFRE, analizador de tablas GFRE

Crédito: el marco arnés / bucle / gráfico sigue el "Harness, Loop and Graph" de @0xwhrrari (noviembre de 2026).