research-harness

Harnais de recherche

Le modèle est rarement ce qui casse dans un long travail d'expérimentation. Ce qui casse, c'est l'espace autour : un split modifié silencieusement, un nombre tapé à la main, un ensemble de test qui a fuité dans l'entraînement, une sixième variante d'une idée qui a déjà échoué, une boucle de polling qui verrouille le compte. Ce skill déplace ces règles hors de la prose et dans des fichiers, du code et des crochets, en suivant le cadre harnais / boucle / graphe de l'ingénierie d'agents.

Les trois couches, appliquées aux expériences

Harnais (l'espace).

• contract.json : revendication, protocole, porte, règles de calcul. Figé.
• CLAUDE.md : une courte carte du projet, pas un manuel.
• frozen/ : listes de splits, eval.py, nombres de référence copiés. Verrouillés par hachage et en lecture seule.
• harness/launch.py : la seule façon de lancer une exécution. Il applique la liste blanche GPU et la règle d'inactivité, et démarre le travail de façon détachée.
• traces.jsonl : une ligne par événement.
• state.json : la décision de la porte.
• lessons.md : les erreurs qui ont coûté deux corrections.

Boucle (le temps).

• Boucle de vérification L1 : frozen/eval.py évalue chaque exécution. C'est la seule source de métriques.

• Les sorties sont décidées par le code (harness/gate.py) :

  • PASS : le candidat bat la référence avec la marge.
  • BUDGET_EXIT : nombre maximal de variantes atteint.
  • STALL_EXIT : aucun gain pendant N tours.
  • REPRO_FAIL : notre réimplémentation de la référence est trop éloignée de l'article.

  Le modèle ne déclare jamais lui-même « terminé ».

• Attente L4 sur changement : chaque travail écrit runs/<id>/DONE en dernier. Attendez ce fichier avec un seul observateur en arrière-plan, pas des interrogations répétées.

Graphe (le chemin). Volontairement petit : splits → geler → caractéristiques → exécution de référence (réimplémentation de la référence) → variantes candidates → porte → compte rendu. Chaque flèche est un contrat de fichier (un TSV de splits, un DONE.json de caractéristiques, un scores/ d'exécution).

Configuration d'un projet

1. Copier template/ dans le projet sur le serveur. Copier le code de la tâche dans src/ (examples/aigi/ est un exemple complet pour la détection d'images générées par IA).
2. Écrire contract.json à partir de template/contract.example.json :
   • revendication : une phrase avec un nombre ;
   • protocole : exactement comme défini dans l'article source ; lister chaque détail non spécifié et le choix effectué dans open_questions ;
   • porte : tag de référence, valeur de l'article, marge, budget ;
   • calcul : chemin Python, liste blanche nœuds/GPU, règle d'inactivité.
3. Écrire paths.json (racines des ensembles de données) et copier les nombres de référence dans frozen/baselines.json. Les extraire du PDF avec un script qui revérifie les moyennes ; ne jamais les retaper à la main.
4. Geler : python harness/freeze.py add contract.json frozen/eval.py frozen/baselines.json.
5. Générer les splits via launch.py, lire les comptes du manifeste, puis geler les splits.
6. Installer le crochet de garde sur la machine exécutant Claude Code :
   • copier hooks/research_guard.py dans <projet>/.claude/hooks/ ;
   • écrire <projet>/.claude/research_guard.json, en utilisant le nom du répertoire distant du projet comme entrée project_markers ;
   • fusionner hooks/settings.snippet.json dans <projet>/.claude/settings.json.

Règles d'exploitation

• Les nombres proviennent uniquement de result.json ou de la ligne de porte. Les citer ; ne jamais calculer ou retaper des métriques dans le chat. Si un nombre n'est pas dans un fichier écrit par eval.py, il n'existe pas encore.
• Lancer les exécutions uniquement via launch.py. Il refuse les IDs d'exécution réutilisés, les fichiers figés modifiés et les GPU occupés, et enregistre les hachages de code pour chaque exécution.
• Une exécution, une question. Utiliser l'ID d'exécution et le tag pour dire ce qu'elle teste (gfre_repro_s0, ml_l12-24_k256). Les variantes de l'idée candidate partagent le candidate_tag de la porte. Tout le reste (débogage, tests de fumée) utilise un tag différent pour ne pas consommer le budget.
• Respecter la porte.
  • CONTINUE signifie que vous pouvez essayer une autre variante.
  • BUDGET_EXIT, STALL_EXIT et REPRO_FAIL signifient arrêter et apporter les preuves à l'humain. Ne pas corriger l'idée une sixième fois.
• Le protocole figé ne change jamais en cours de projet. S'il doit changer (un bug dans un split, un détail de protocole appris des auteurs), un humain édite FROZEN.sha256 et un nouveau gel commence. Les résultats antérieurs restent dans results.jsonl avec leur propre historique.
• Attendre les fichiers DONE avec un seul observateur en arrière-plan. Chaque appel ssh dans une boucle utilise -o BatchMode=yes et s'arrête sur le code de sortie 255.
• Après chaque exécution, lire la sortie de status.py, pas les logs bruts. Ouvrir log.txt uniquement en cas d'échec.
• Quand une erreur se répète, ajouter une ligne à lessons.md, et si possible la transformer en vérification (une assertion dans src/, une règle de crochet, une vérification de manifeste).

Passage du réviseur (avant de faire confiance à un PASS)

Lancer un sous-agent réviseur par lentille. Donner à chacun le code et les fichiers, pas votre conclusion :

1. Fuite : les fichiers d'entraînement, de validation et de test se chevauchent-ils ? Les motifs exclus sont-ils vraiment exclus ? Les étiquettes de test atteignent-elles jamais le code d'entraînement ?
2. Protocole : les splits, les ensembles de test, le seuil et la métrique correspondent-ils à l'article source et à contract.json ? Les choix de open_questions sont-ils divulgués ?
3. Comparaison équitable : la réimplémentation de référence est-elle dans la tolérance ? Les nombres de référence copiés proviennent-ils du même protocole ? Les références relancées sont-elles marquées ?

Un réviseur vaut exactement autant que les décisions qu'il modifie. Chaque lentille retourne des preuves concrètes (fichier/ligne) ou rien.

Fichiers

template/                 copier dans un nouveau projet
  CLAUDE.md               carte (éditer le titre)
  contract.example.json   revendication / protocole / porte / calcul
  lessons.md
  harness/                launch.py job.sh gate.py status.py freeze.py check_frozen.py trace.py common.py
  frozen/eval.py          évaluateur de détection binaire (ACC au seuil + AP par ensemble de test)
hooks/                    research_guard.py + exemple de configuration + extrait de paramètres
examples/aigi/            Détection d'images générées par IA : splits GenImage + CNNDetection, mise en cache
                          des caractéristiques CLIP, détecteur de reconstruction type GFRE, analyseur de tableau GFRE

Crédit : le cadre harnais / boucle / graphe suit « Harness, Loop and Graph » (nov. 2026) de @0xwhrrari.