Harness
Un cadre de travail prêt à l'emploi pour Claude Code, quelle que soit la stack.
Tu décris ce que tu veux, tu valides le cadrage une fois, et Claude livre seul : spec, code testé, revue, PR. Le harness installe dans ton projet les skills, agents, rules, hooks et contrôles CI qui rendent ce cycle fiable, autour d'OpenSpec.
| |
|---|
| 🎯 Un seul arrêt | Tu valides la spec à la porte de cadrage. Ensuite, le run va jusqu'au rapport sans te solliciter, et jusqu'à la PR relue si la confiance suffit. |
| ⚡ En parallèle | Chaque run tourne dans son propre worktree : tu cadres le change suivant pendant ce temps. |
| ✅ Jamais vert sans test | hx check lance les mêmes contrôles en local et en CI, et relie chaque scénario de spec à un test. |
| 🧩 Toute stack | /hx-setup adapte les commandes (lint, tests, typecheck…) à ton projet. |
Pensé pour Claude Code Desktop ; le terminal reste pris en charge. Statut : éprouvé sur un vrai projet. Présentation en schémas →
Démarrer
1. Installer — dans Claude Code Desktop, ouvre une session sur le dossier du projet et dis :
« Installe le harness github.com/PatayEnCroute/Harness en suivant son INSTALL.md »
2. Personnaliser — ouvre une nouvelle session sur le même dossier et tape /hx-setup. Il adapte le harness à ta stack et finit par hx doctor.
C'est tout.
Prérequis : git et Node ≥ 20.19. Dans le dossier du projet (vide, ou dépôt git sans changement en cours) :
npx github:PatayEnCroute/Harness
| Le lanceur… | Pourquoi |
|---|
fait git init dans un dossier vide ; refuse un arbre git sale | /hx-setup retrouve dans git les fichiers que l'installation remplace |
| installe uv s'il manque, après accord | uv lance Copier, le moteur du template |
lance uvx [email protected] copy --trust | pose 4 questions : nom du projet, workflow CI (ci), branche par défaut (default_branch), relecteurs obligatoires (codeowners) |
ouvre Desktop sur le dossier (claude --desktop), sinon dit comment faire | tu y tapes /hx-setup |
Options : --vcs-ref vX.Y.Z (version précise) · --defaults (sans questions) · --terminal (Claude Code dans le terminal au lieu de Desktop) · --no-claude · --help.
Sans le lanceur : uvx [email protected] copy --trust gh:PatayEnCroute/Harness ., puis /hx-setup.
L'installation remplace CLAUDE.md, .claude/settings.json et openspec/config.yaml s'ils existent. Accepte : /hx-setup récupère ensuite leur contenu utile depuis git.
Il autorise les tâches post-installation : openspec init à l'installation, puis openspec update et hx migrate à chaque mise à jour. La CLI OpenSpec (commandes /opsx:*) s'installe au premier démarrage de session si elle manque. Copier 9.19.1 est la version testée en CI et le minimum exigé.
Agent IA : pour installer le harness à la demande d'un utilisateur, suis INSTALL.md.
Travailler avec le harness
Chaque demande passe par hx-triage, qui choisit la piste selon sa taille.
flowchart LR
D([Demande]) --> T{hx-triage}
T -->|S| S1[hx-tdd / hx-debug] --> S2[hx-verify] --> S3([commit])
T -->|M / L| C
subgraph C [1 · CADRAGE — avec toi]
C1["[hx-clarify]"] --> C2["/opsx:propose"] --> C3{{Porte de cadrage}}
end
subgraph R [2 · RUN — seul, dans son worktree]
R1[hx-implement] --> R2[hx-verify] --> R3[hx-review] --> R4([rapport])
end
subgraph L [3 · LIVRAISON — toi, ou seul si la confiance suffit]
L0{hx confidence} -->|non| L1["/hx-ship"]
L0 -->|oui| LA["/hx-ship auto<br/>PR brouillon · CI"] --> LR["hx-review --pr<br/>revue en commentaire"]
L1 --> L2[hx-learn]
LR --> L2
end
C --> R --> L
Les trois temps d'un change M ou L
| Temps | Qui | Ce qui se passe |
|---|
| 1 · Cadrage | toi + Claude | hx-clarify si la demande est floue, puis proposition OpenSpec. En M avec design.md et en L, un hx-architect neuf conteste le cadrage (garder, simplifier, retirer, changer). En L : hx-architect et hx-adr. La porte : tu vérifies que la spec dit ce que tu as demandé, sans plus. |
| 2 · Run | Claude seul | hx worktree <change> crée sa branche et son worktree. Lance-le en mode Auto : Desktop → nouvelle session sur le worktree, Cmd/Ctrl+Shift+M, puis /hx-implement <change>. Il ne s'arrête que sur un vrai blocage (3 échecs sur une tâche, spec fausse, piste qui monte, outillage cassé). Le rapport finit dans run-report.md. |
| 3 · Livraison | toi | Réponds à la question du rapport sur les mineurs, puis /hx-ship : il reprend la base, vérifie, et fait de l'archive OpenSpec le dernier commit de la PR. |
| 3 bis · Livraison automatique | Claude seul | Si tu l'as activée et que hx confidence l'autorise : /hx-ship sans mineur appliqué, PR en brouillon, CI, puis une revue neuve publiée en commentaire. Aucun bloquant : la PR passe « prête ». Tu relis et tu merges. |
💡 Pendant un run, cadre le change suivant dans le dossier principal. hx status montre où en est chaque run.
Livraison automatique
Désactivée par défaut. Pour l'activer : "ship": { "auto": true, "min_confidence": 80 } dans .harness/config.json. En fin de run, hx confidence <change> calcule l'indice sur les fichiers du change et sur git, jamais sur l'avis de l'agent qui a codé. Le hook PreToolUse refuse /hx-ship à Claude tant que l'indice ne l'autorise pas.
| ✗ Exclut toujours | − Retire des points (sur 100) |
|---|
| piste L (ou autre que M) | 10 par hypothèse à confirmer |
| rapport de fin de run autre que « Prêt à livrer », tâches non cochées | 5 par mineur proposé |
| important reporté hors du change | 5 par constat corrigé après la revue (non relu) |
.harness/, .claude/, .github/, CLAUDE.md, specs principales modifiés | 15 si des dépendances changent |
mesure absente de .openspec.yaml, arbre sale, revue sans sous-agents | |
Le commentaire de revue donne : verdict, indice et contrôles, constats triés par gravité avec leur correction, hypothèses et mineurs à confirmer, constats écartés. Le harness ne merge jamais.
Hors workflow, à la demande
| Skill | Usage |
|---|
/hx-security-audit | CVE des dépendances, injections SQL. Lecture seule. |
/hx-explain | Pour un non-développeur : expliquer une décision, faire le bilan de son usage, expliquer une notion. |
/hx-dream | Consolider la mémoire du projet : oublier le périmé, fusionner, hiérarchiser. Plan validé avant écriture. |
Ce qui est installé
| Composant | Contenu |
|---|
| 15 skills | Workflow : hx-setup, hx-triage, hx-clarify, hx-tdd, hx-implement, hx-verify, hx-review, hx-ship, hx-adr, hx-debug, hx-learn, hx-discover · À la demande : hx-security-audit, hx-explain, hx-dream |
| 7 agents | hx-explorer, hx-implementer, hx-spec-reviewer, hx-code-reviewer, hx-security-reviewer, hx-architect, hx-verifier |
| 4 rules | openspec · testing · architecture (feature-first, proportionnée) · comments (aucun par défaut, liste fermée d'exceptions) |
| 4 hooks | Contexte au démarrage · rappel quand Claude édite un fichier sensible (spec, contrat, hooks, permissions) · lint du fichier édité · contrôles rapides et chemins protégés avant de rendre la main |
CLI hx | hx check (openspec, archives, pistes, trace @scenario, lint, typecheck, arch, test) · hx status (état des runs) · hx stats (mesures d'élagage) · hx confidence (livraison automatique) · hx doctor · hx worktree |
Autorisés sans confirmation : node .harness/hx.mjs, openspec, git local (lecture, add, commit, pull, branch -d, worktree list), gh pr create/checks/view/comment/ready, lectures shell (ls, cat, head, tail, wc).
Aucune règle ask : une confirmation que personne ne relit ne protège rien, et elle interromprait le mode Auto. Le reste (git push, git rm, git worktree remove, git bisect, gh issue create…) revient au mode de permission ; en Auto, son classifieur décide. Les permissions du dossier principal (.claude/settings.local.json) sont reprises dans chaque worktree.
Interdit : éditer hx.mjs, hooks.mjs et versions.json (gérés par Copier). Un test vérifie que chaque commande citée par un skill est autorisée ou laissée exprès au mode.
Générique ou spécifique ?
🔄 Générique — mis à jour par copier update | 📌 Spécifique — rempli par /hx-setup, jamais écrasé |
|---|
CLAUDE.md, .claude/, .harness/hx.mjs, .harness/hooks.mjs, openspec/config.yaml, .github/workflows/hx-check.yml | .harness/config.json, .harness/project.md, .harness/ci/setup/action.yml, .github/dependabot.yml, .github/CODEOWNERS, .claude/rules/stack-*.md |
Un fichier générique s'améliore dans Harness, pas dans le projet.
Maintenir
| Action | Comment |
|---|
| Mettre à jour | Sur un arbre git propre : uvx [email protected] update --trust, puis node .harness/hx.mjs doctor. Copier prend le dernier tag ; hx doctor signale un projet en retard. |
| Résoudre un conflit | hx doctor liste les marqueurs <<<<<<< et fichiers .rej. Garde la version du template sauf personnalisation voulue, nettoie, relance hx doctor, commite. |
| Protéger le harness | Avec codeowners, .github/CODEOWNERS couvre .harness/, .claude/settings.json, .github/ et openspec/specs/. À combiner avec « Require review from Code Owners ». |
- Supprime
.harness/, .copier-answers.yml, .claude/skills/hx-*, .claude/agents/hx-*, les rules openspec, testing, architecture et comments, .github/workflows/hx-check.yml (et CODEOWNERS, dependabot.yml s'ils viennent du template).
- Dans
.claude/settings.json, retire les hooks vers .harness/hooks.mjs, les permissions hx.mjs, openspec et git du template, et OPENSPEC_TELEMETRY.
- Dans
CLAUDE.md, retire les sections du harness.
openspec/ reste utilisable sans le harness : garde-le si les specs servent encore.
Contribuer au template
npm test # unitaires, hermétiques (CI : Linux, macOS, Windows)
npm run test:contract # contrat OpenSpec sur la version épinglée (réseau)
npm run e2e # 5 stacks, cycle OpenSpec complet, copier update, lanceur npx
npm run evals # agents headless notés de façon déterministe (local, sans clé d'API)
Publier une version : sur main, la section « Non publié » de CHANGELOG.md devient la version, puis git tag vX.Y.Z && git push origin vX.Y.Z. Les projets suivent les tags.
Les actions GitHub sont épinglées par SHA et tenues à jour par Dependabot ; les SHA de hx-check.yml.jinja suivent ceux de ci.yml (vérifié par un test).
Pour aller plus loin
