Harness Bootstrap

Installe un harnais d'agent complet et prêt pour l'équipe dans n'importe quel dépôt git : fichier d'entrée (CLAUDE.md/AGENTS.md), documentation d'architecture et de fiabilité, scripts de vérification en couches, règles d'architecture exécutables, une liste de fonctionnalités par tâche dont seul un vérifieur peut modifier l'état, fichiers de transfert de session et de progression locaux (gitignorés), une checklist d'état propre, un évaluateur indépendant, et des vérifications d'intégrité qui imposent le tout. Fonctionne avec n'importe quel agent de codage (Claude Code, Codex, Cursor, Copilot, Devin, Pi et autres). Utilisez-le chaque fois que quelqu'un veut « mettre en place un harnais », rendre un dépôt prêt pour un agent, empêcher les agents d'oublier le contexte entre les sessions, empêcher les agents d'affirmer que quelque chose est « fait » avant d'être fonctionnel, organiser les transferts entre développeurs ou worktrees, ou créer les fichiers AGENTS.md / CLAUDE.md / feature_list.json / init.sh / session-handoff pour un projet, même sans jamais prononcer le mot « harnais ».

Qu'est-ce que Harness Bootstrap ?

Le skill Harness Bootstrap transforme n'importe quel dépôt git en un environnement où tout agent de codage – Claude Code, Codex, Cursor, Copilot, Devin, Pi ou autres – peut immédiatement comprendre le contexte, exécuter des vérifications et travailler efficacement. Il installe un contrat complet (fichier d'entrée, documentation d'architecture, règles d'exécution, scripts de vérification, évaluateur indépendant) ainsi que des skills de cycle de vie (harness-start, harness-handoff, harness-cleanup, harness-evaluate) qui vivent dans le dépôt lui-même. L'objectif est de résoudre les problèmes courants des agents : oubli du contexte entre sessions, fausses déclarations de « fait » et difficulté à reprendre le travail d'un autre développeur. Le bootstrap ne s'exécute qu'une seule fois par dépôt ; il analyse l'existant (README, CI, autres fichiers de règles d'agent), pose des questions ciblées pour combler les lacunes, puis copie et adapte automatiquement la structure du harnais. Le tout est conçu pour être non destructif, respecter les conventions existantes du projet et n'ajouter que ce qui manque réellement.

Compatible avec✓Claude Code✓Codex CLI✓Cursor✓Gemini CLI✓OpenCode✓Windsurf
npx skills add https://github.com/Gabriel-Valin/harness-bootstrap/tree/HEAD

Installed? Explore more Développement et programmation skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Que fait Harness Bootstrap ?

Transformez un dépôt en un endroit où toute nouvelle session d'agent, sur n'importe quelle machine de développeur, peut répondre à cinq questions à partir du seul dépôt : qu'est-ce que c'est, comment c'est organisé, comment je l'exécute, comment je le vérifie, et où nous sommes-nous arrêtés. Ensuite, faites en sorte que « fait » soit décidé par un script, et non par l'agent.

Ce skill s'exécute une seule fois par dépôt. Il installe un contrat que l'équipe valide (par PR), ainsi que des skills de cycle de vie (harness-start, harness-handoff, harness-cleanup, harness-evaluate) qui vivent dans le dépôt afin que chaque membre de l'équipe les récupère au clone, quel que soit l'agent de codage qu'il utilise.

Les chemins dans ce fichier (scripts/, references/, assets/) sont relatifs au répertoire qui contient ce SKILL.md. L'emplacement de ce répertoire dépend de l'agent et de la façon dont le skill a été installé ; résolvez-le donc à partir de l'endroit où vous avez chargé ce fichier ; ne présumez jamais d'un chemin fixe comme ~/.claude/skills/.

Consultez references/principles.md si vous avez besoin du raisonnement derrière un artefact (par exemple, pour l'expliquer à l'utilisateur ou pour l'adapter à un dépôt inhabituel).

Le modèle que vous installez

CoucheEmplacementValidé ?Objectif
Fichier d'entréeCLAUDE.md et/ou AGENTS.mdouiCarte courte : quoi, comment exécuter, comment vérifier, règles strictes, liens
Documentationdocs/ARCHITECTURE.md, PRODUCT.md, RELIABILITY.md, docs/decisions/ouiConnaissances que l'agent ne peut déduire du code
Contratharness/ (config, règles, checklist, grille d'évaluation, doc qualité, modèles, README)ouiMêmes règles pour tout le monde, modifiées uniquement par PR
Vérificationscripts/harness/ouiinit.sh, verify.sh, feature.py, check_architecture.py, cleanup-scan.sh
Cycle de vie.agents/skills/harness-*, miroirs pour les agents qui lisent un autre dossierouiDémarrer, transférer, nettoyer, évaluer
AdaptateursPar agent, par exemple .claude/agents/, .claude/hooks/ pour Claude CodeouiExtras optionnels : sous-agent, hooks
État de la tâche.harness/tasks/<TASK-ID>/nonListe de fonctionnalités, contrat, progression, transfert, journaux d'exécution pour une tâche

L'état de la tâche est local car il change à chaque session et appartient à la branche d'une seule personne. Le valider provoque des conflits de fusion et permet à l'état obsolète d'un développeur d'induire en erreur l'agent d'un autre développeur. C'est un cache : tout ce qui est durable est promu en code, tests, docs, PR ou suivi des problèmes avant la fin de la tâche. harness/README.md explique cela à l'équipe.

Flux de travail

1. Confirmer la cible

Exécutez git rev-parse --show-toplevel dans le répertoire que l'utilisateur vise. Si ce n'est pas un dépôt git, arrêtez-vous et dites-le : l'isolation du worktree et les vérifications de la branche de base dépendent de git. Notez si l'arbre de travail est sale ; suggérez de faire le bootstrap sur sa propre branche afin qu'il puisse être examiné comme une seule PR.

2. Inventorier ce qui existe déjà

Regardez avant d'écrire. Trouvez et lisez :

  • Fichiers d'instructions : AGENTS.md, CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md, GEMINI.md, .cursorrules, .cursor/rules/, .github/copilot-instructions.md, .windsurfrules
  • Documentation : README*, docs/, dossiers ADR, CONTRIBUTING*
  • Pièces de harnais existantes : feature_list.json, progress.md, init.sh, Makefile, harness/, scripts/harness/, .harness/
  • Configuration et skills des agents : .agents/skills/, .claude/ (settings.json, skills/, agents/, hooks/), .devin/, .cursor/, .github/, .worktreeinclude
  • .gitignore

Le contenu existant prime. Vous l'étendez ; vous ne remplacez jamais un fichier écrit par l'équipe sans demander.

3. Découvrir comment le projet s'exécute

Suivez references/discovery.md. L'objectif est une liste vérifiée de commandes pour chaque couche de vérification, chacune avec l'endroit où vous l'avez trouvée (la configuration CI est la preuve la plus solide, car c'est ce en quoi l'équipe a vraiment confiance). Identifiez également les couches ou modules du code et les directions de dépendance entre eux ; ils deviennent les règles d'architecture.

4. Ne demander que les lacunes

Regroupez les questions auxquelles vous n'avez pas pu répondre à partir du dépôt en un seul appel de question structuré si votre environnement en a un, sinon en un seul message. Lacunes typiques :

  • Limites d'architecture que vous avez déduites mais dont vous n'êtes pas sûr (« est-ce que ui/ a le droit d'importer db/ ? »)
  • La commande de bout en bout ou de smoke, si elle n'existe pas
  • La branche de base et la convention de nommage des branches, si non documentées
  • Quels agents de codage l'équipe utilise (Claude Code, Codex, Cursor, Copilot, Devin, Pi, autres). Cela détermine le fichier d'entrée et les adaptateurs d'agent à installer.
  • Si l'équipe utilise Claude Code : faut-il installer ses hooks (recommandé ; ils affichent l'état de la tâche au début de la session et empêchent les modifications manuelles de l'état de la tâche avant qu'elles ne se produisent)

Ne demandez pas les choses qui ont une valeur par défaut conventionnelle ; choisissez-la et mentionnez-la dans le rapport final.

5. Copier le squelette

bash <répertoire de ce skill>/scripts/install.sh <racine-dépôt> --agents <ids>

--agents prend les agents de l'équipe de l'étape 4 sous forme d'identifiants séparés par des virgules, les mêmes identifiants que ceux utilisés par la CLI npx skills (claude-code, codex, cursor, github-copilot, gemini-cli, opencode, pi, devin, windsurf, kiro-cli, ... ; --help les liste).

Le script copie assets/project/ dans le dépôt, y compris les skills de cycle de vie dans .agents/skills/, que la plupart des agents lisent directement. Pour les agents qui lisent un autre dossier (claude-code, devin, windsurf, kiro-cli), il ajoute des liens symboliques relatifs vers ces skills, et pour les agents ayant un adaptateur dans assets/adapters/<id>/, il copie les fichiers d'adaptateur. Passez --copy pour des copies au lieu de liens symboliques lorsque l'équipe a des checkouts Windows sans support des liens symboliques ; init.sh signalera alors les copies qui dérivent. Le script ne remplace jamais un chemin existant, marque les scripts comme exécutables et affiche CREATED / LINKED / SKIPPED par chemin. Utilisez --dry-run d'abord si le dépôt a déjà des pièces de harnais. Pour chaque chemin SKIPPED, lisez le fichier existant et fusionnez les idées manquantes à la main au lieu de forcer le modèle.

Si le script signale des chemins FAILED, le sandbox de votre agent protège probablement un dossier comme .agents/ ou .claude/ (Codex fait cela pour .agents/ par défaut). Réexécutez la même commande avec l'autorisation offerte par votre environnement, ou demandez à l'utilisateur de l'exécuter. Ne déplacez jamais les skills vers un autre dossier pour contourner le problème : les agents ne découvrent les skills que dans les dossiers qu'ils lisent, donc les skills déplacés cessent silencieusement de fonctionner.

6. Remplir les spécificités du projet

Tout ce que le squelette ne peut pas savoir vous appartient d'écrire, en vous basant sur ce que vous avez lu aux étapes 2-4 :

  1. harness/config.sh : une commande par ligne pour chaque couche (setup, statique, test, smoke, e2e), la branche de base et les modèles de débogage pour la pile. Laissez une couche vide seulement si elle n'existe vraiment pas ; verify.sh signalera les couches obligatoires vides comme UNVERIFIED au lieu de les valider. Ne remplissez jamais une couche avec une commande qu'une autre couche exécute déjà (par exemple les tests d'intégration comme « e2e ») : chaque couche doit ajouter des preuves que les autres n'apportent pas. Voir references/discovery.md.
  2. harness/architecture-rules.json : une règle par limite, en suivant references/architecture-rules.md. Chaque règle a besoin de why et fix rédigés pour un agent, car le message d'erreur est la boucle de rétroaction.
  3. Docs : créez docs/ARCHITECTURE.md, docs/PRODUCT.md, docs/RELIABILITY.md uniquement là où le dépôt n'a pas d'équivalent, en partant de assets/docs-skeletons/. Écrivez à partir du code que vous avez lu, gardez chaque document sous ~150 lignes, et marquez tout ce que vous n'avez pas pu confirmer par TODO(confirm): ... plutôt que de deviner. Si des équivalents existent ailleurs, faites un lien vers eux au lieu de les dupliquer.
  4. Enregistrements de décisions : le squelette ajoute docs/decisions/. Si le dépôt conserve déjà des ADR ailleurs (doc/adr/, docs/adr/), supprimez le nouveau dossier et pointez harness/README.md, les skills de transfert et de nettoyage, et les modèles vers l'existant.
  5. harness/quality-document.md : listez les modules réels avec une note initiale honnête, ou unknown là où vous n'avez aucune preuve. Ne notez jamais en vous basant sur une impression.

7. Câbler le fichier d'entrée

Insérez la section de assets/snippets/entry-section.md dans le fichier d'entrée, près du début ou de la fin (les modèles se souviennent mieux des bords des fichiers longs que du milieu). Gardez le fichier d'entrée comme un routeur : s'il dépasse ~200 lignes, déplacez les détails dans docs/ et faites un lien vers eux.

AGENTS.md est le fichier d'entrée canonique : la plupart des agents de codage le lisent directement. Les autres agents obtiennent un pointeur léger vers lui, jamais une seconde copie des règles, afin que les fichiers ne puissent pas dériver.

SituationFaites ceci
Ni AGENTS.md ni CLAUDE.md n'existentCréez AGENTS.md à partir de ce que vous avez appris, plus la section.
Seul AGENTS.md existeAjoutez la section à AGENTS.md.
Seul CLAUDE.md existe, l'équipe utilise uniquement Claude CodeAjoutez la section à CLAUDE.md.
Seul CLAUDE.md existe, l'équipe utilise d'autres agents aussiDemandez avant de le déplacer : proposez de déplacer son contenu dans AGENTS.md et de laisser @AGENTS.md dans CLAUDE.md. Si l'équipe refuse, ajoutez la section à CLAUDE.md et créez AGENTS.md avec la section et un lien vers CLAUDE.md.
Les deux existentAjoutez la section à AGENTS.md, et assurez-vous que CLAUDE.md l'importe avec @AGENTS.md.

Ajoutez ensuite le pointeur pour chaque agent de l'équipe qui ne lit pas AGENTS.md par défaut :

AgentPointeur
Claude CodeCLAUDE.md contenant @AGENTS.md. Par défaut, Claude Code ne lit AGENTS.md que lorsqu'aucun CLAUDE.md ou CLAUDE.local.md n'existe, donc un dépôt avec les deux ignore silencieusement AGENTS.md sans l'import.
Gemini CLIGEMINI.md contenant @AGENTS.md, ou "contextFileName": "AGENTS.md" dans .gemini/settings.json.
Tout agent avec son propre fichier de règles déjà dans le dépôt (.github/copilot-instructions.md, .cursor/rules/, .windsurfrules)Une ligne dans ce fichier disant de lire AGENTS.md, qui contient les règles.

Vérifiez le comportement actuel d'un agent dont vous n'êtes pas sûr dans sa propre documentation plutôt que de deviner ; les agents changent les fichiers qu'ils lisent.

8. Fusionner la configuration

  • .gitignore : ajoutez les lignes de assets/snippets/gitignore.txt qui manquent.
  • Claude Code uniquement, .claude/settings.json : fusionnez les hooks de assets/adapters/claude-code/settings-hooks.json. Lisez le fichier existant, ajoutez aux tableaux hooks.SessionStart / hooks.PreToolUse existants plutôt que de les remplacer, et gardez le JSON valide. Si l'équipe a refusé les hooks, ignorez cette étape et supprimez le dossier .claude/hooks/ que l'adaptateur a copié. Le harnais ne dépend pas des hooks : feature.py scelle l'état de la tâche et refuse de fonctionner après une modification manuelle, et le fichier d'entrée dit à chaque agent d'exécuter init.sh au début de la session.
  • Claude Code uniquement, .worktreeinclude : si le projet a besoin de fichiers gitignorés comme .env pour fonctionner, listez-les afin que chaque worktree que Claude Code crée en reçoive une copie. Pour un simple git worktree add, mentionnez ces fichiers dans harness/README.md pour que les gens les copient.

9. Prouver une fois

Exécutez bash scripts/harness/init.sh et python3 scripts/harness/check_architecture.py et rapportez le résultat réel. Si quelque chose échoue à cause du projet (pas du harnais), dites-le clairement et laissez-le comme première entrée du rapport ; n'assouplissez pas une règle ni ne supprimez une commande pour le rendre vert. Faites ensuite le test de session vierge de references/principles.md : répondez aux cinq questions en utilisant uniquement les fichiers, et corrigez celles auxquelles vous ne pouvez pas répondre.

10. Rapporter

Dites à l'utilisateur, brièvement :

  • Ce qui a été créé, ce qui a été fusionné et ce qui a été ignoré parce qu'il existait déjà
  • Les commandes par couche et d'où chacune vient
  • Chaque TODO(confirm) et chaque hypothèse que vous avez faite
  • Le résultat de l'initialisation/vérification, y compris les échecs
  • Si ce skill lui-même a été installé dans le dépôt (.agents/skills/harness-bootstrap/ ou le dossier de skills d'un autre agent, plus skills-lock.json), dites-le : l'équipe n'en a pas besoin après le bootstrap, et il peut être supprimé ou conservé pour une réexécution ultérieure. Ne le supprimez pas vous-même.
  • Prochaine étape : examiner et valider le bootstrap sur une branche, puis démarrer une tâche avec le skill harness-start (chez les agents avec des commandes slash, /harness-start <TASK-ID>)

Ne validez ni ne poussez sauf si l'utilisateur le demande.

Règles de conception pour l'adaptation du squelette

  • Préférez les outils existants du projet. Si le dépôt a un Makefile avec make check, mettez make check dans config.sh au lieu de re-lister ses parties.
  • Gardez les dépendances d'exécution à bash, git et python3 (bibliothèque standard uniquement). N'ajoutez pas de packages au projet pour le harnais.
  • Les messages d'erreur de tout script du harnais disent ce qui a échoué, pourquoi et comment le corriger.
  • Rien de destructeur dans les scripts. Le nettoyage ne fait que rapporter ; les humains ou les agents agissent sur le rapport.
  • Rendez le harnais plus petit quand vous le pouvez. Un composant qui ne modifie pas le comportement de l'agent sur ce dépôt est de la surcharge ; dites-le au lieu de l'installer par souci d'exhaustivité.

Skills associés