Ingénierie de Harness

L'ingénierie de harness transforme les erreurs répétées des agents de codage en artefacts durables du repository :

Harness = Instructions + Contraintes + Retours + Mémoire + Évaluation + Gouvernance

Utilise cette compétence quand l'utilisateur demande de :

• rendre un repository plus fiable pour GitHub Copilot ou d'autres agents de codage
• ajouter des instructions d'agent durables, des règles de repository ou des garde-fous
• prévenir les erreurs répétées des agents de codage IA
• enregistrer les chemins d'échec connus et les vérifications qui préviennent la récurrence
• ajouter des vérifications légères de dérive pour les règles du projet
• examiner, rafraîchir ou mettre à jour un harness d'agent existant

N'utilise pas cette compétence pour une implémentation de fonctionnalité ordinaire sauf si l'utilisateur demande d'améliorer l'environnement d'exploitation du repository pour les agents.

Principes fondamentaux

• Traite le repository cible comme source de vérité.
• Inspecte avant de modifier. Préserve la stack existante, le gestionnaire de paquets, la CI, la documentation, les conventions de nommage et l'architecture.
• Ajoute le plus petit harness utile. Préfère mettre à jour les fichiers existants plutôt que d'ajouter des guidances dupliquées.
• Rends les règles importantes exécutoires où c'est pratique via des tests, des linters, des vérifications de type, la CI, des pre-commit hooks ou des scripts de dérive.
• Utilise les points de revue manuelle uniquement quand l'automatisation serait fragile ou trompeuse.
• Enregistre les défaillances à haut risque qui ne doivent pas se reproduire, et nomme la vérification ou le point de revue qui détecte la récurrence.
• Ne copie pas les templates génériques aveuglément. Adapte chaque artefact aux preuves réelles du repository cible.

Découverte

Avant de proposer ou d'apporter des modifications de harness, inspecte le repository pour les règles et preuves existantes.

Lis ces fichiers et dossiers quand ils existent :

• README.md
• AGENTS.md
• .github/copilot-instructions.md
• .github/instructions/
• .github/workflows/
• CONTRIBUTING.md
• les manifestes de paquets comme package.json, pyproject.toml, go.mod, Cargo.toml, pom.xml ou build.gradle
• la documentation existante sous docs/
• les scripts existants sous scripts/
• les tests existants et les vérifications de CI

Ensuite, résume :

• la stack, le gestionnaire de paquets et les points d'entrée
• les commandes de développement et de vérification existantes
• les instructions d'agent actuelles ou les conventions de repository
• les défaillances connues, incidents, chemins instables ou commentaires de revue répétés
• les écarts où les règles du projet ne sont pas exécutoires

Workflow d'adoption

Suis cette séquence :

1. Choisis la surface de harness qui convient au repository cible.
2. Écris les instructions d'agent spécifiques à la cible.
3. Ajoute des vérifications exécutoires pour les règles de haute valeur.
4. Enregistre la mémoire de défaillance pour les défaillances à haut risque ou récurrentes.
5. Ajoute des vérifications de dérive pour la guidance qui peut devenir silencieusement obsolète.
6. Rapporte l'adoption avec preuves, hypothèses et suivi.

1. Choisis la surface de Harness

Choisis uniquement les surfaces qui conviennent au repository cible :

Si le repository a déjà un emplacement équivalent, mets-le à jour au lieu de créer un système parallèle.

2. Écris les instructions d'agent

Les instructions d'agent doivent être concrètes et opérationnelles. Inclus :

• le but du projet et les grandes frontières de propriété
• les commandes de setup, test, lint, build et vérification
• le gestionnaire de paquets et les règles de dépendance
• les règles d'édition sûre, les règles de fichier généré et les chemins interdits
• les attentes de test pour le code modifié
• les conventions de PR et commit si le repo les a
• comment enregistrer les nouvelles défaillances ou décisions

Évite les guidances de personnalité larges, les bonnes pratiques génériques et les règles qui ne peuvent pas être vérifiées ou révisées.

3. Ajoute des vérifications exécutoires

Convertis les règles de haute valeur en vérifications. Les bonnes vérifications de harness sont :

• assez étroites pour éviter les faux positifs
• assez rapides pour s'exécuter localement et en CI
• nommées clairement pour que les agents puissent les exécuter avant de terminer
• documentées avec la règle qu'elles protègent

Exemples :

Règle : Ne modifie pas les clients API générés.
Vérification : le script analyse les diffs pour les chemins générés et échoue avec un message clair.

Règle : Chaque note de mémoire de défaillance nomme une vérification de régression.
Vérification : le script valide docs/failures/*.md pour une section "Detection".

Règle : Les docs de profil et les templates doivent rester alignés.
Vérification : le test compare les fichiers README du profil aux fichiers template attendus.

4. Enregistre la mémoire de défaillance

Enregistre les défaillances quand elles sont visibles par l'utilisateur, à haut risque ou susceptibles de se reproduire. Utilise un nouveau fichier sous docs/failures/ sauf si une note existante couvre déjà la même cause racine.

Structure recommandée :

# Titre court de la défaillance

## Résumé

Ce qui a échoué, qui l'a vu et pourquoi c'est important.

## Cause racine

La cause technique ou de processus. Évite le blâme.

## Prévention

Instruction, test, vérification de dérive, gate de CI, fixture ou point de revue manuelle qui prévient ou détecte la récurrence.

## Preuves

Liens vers issue, PR, test, log, sortie de commande ou chemins de fichiers.

Si aucune vérification automatisée n'est pratique, enregistre le point de revue manuelle et pourquoi l'automatisation serait dangereuse ou trompeuse.

5. Ajoute des vérifications de dérive

Utilise les vérifications de dérive pour la guidance qui peut devenir silencieusement obsolète. Exemples courants :

• la documentation mentionne des commandes qui n'existent plus
• les snippets de profil et les exemples générés divergent
• les notes de défaillance omettent les vérifications de régression
• les records de décision manquent pour les changements structurels
• la CI référence des scripts ou des commandes de paquets obsolètes

Préfère les petits scripts utilisant le langage existant du repository. Si le repo n'a pas de convention de script, Python avec uniquement la standard library est un défaut portable.

6. Rapporte l'adoption

Termine le travail substantiel de harness avec un rapport d'adoption qui inclut :

• fichiers modifiés
• règles ajoutées ou mises à jour
• vérifications ajoutées ou réutilisées
• commandes exécutées et résultats
• hypothèses et suivi manuel
• mémoire de défaillance créée ou intentionnellement ignorée
• comment l'efficacité sera mesurée

Workflow de revue

Quand tu es demandé de revoir un changement de harness, prends une perspective opposée. Cherche :

• des règles génériques copiées sans preuve du repository cible
• des fichiers d'instruction dupliqués ou conflictuels
• des vérifications larges susceptibles d'échouer sur des changements valides
• des règles à haut risque non exécutoires
• la mémoire de défaillance manquante pour les erreurs répétées ou les défaillances d'exécution
• les docs générées non rafraîchies après les changements source
• les gates de CI qui n'exécutent pas les vérifications pertinentes
• les conventions de repository cible étant écrasées par les défauts de harness

Rapporte les résultats d'abord, ordonnés par sévérité, avec références de fichier et ligne quand disponible. Ne modifie pas les fichiers pendant une revue sauf si l'utilisateur demande explicitement les corrections.

Contrat de sortie

Avant de terminer le travail d'adoption de harness, vérifie :

• le repository cible a été inspecté avant les modifications
• la nouvelle guidance est spécifique au repository cible
• les vérifications modifiées peuvent être exécutées localement ou avoir un substitut manuel documenté
• la mémoire de défaillance a été enregistrée quand nécessaire, ou la réponse finale explique pourquoi elle a été ignorée
• les docs générées ou les index sont rafraîchis
• le rapport final nomme chaque commande exécutée et son résultat

Référence optionnelle

Le workflow prompt-first dans https://github.com/baskduf/harness-starter-kit est une implémentation de référence de ces idées. Utilise-le comme matériel de référence uniquement quand l'utilisateur le demande ou quand le repository l'inclut déjà. Le repository cible reste la source de vérité.