Cours Vibe coding avec Claude Code · Module 15: Claude Code avancé
L'épreuve sans surveillance : /goal, hook Stop et /verify
Dans cette leçon8
Le matin, dans rapport-de-nuit.json, le champ result dit : "Terminé. Toutes les routes utilisent lib/apiErrors.ts, les tests passent." À côté t'attend la branche worktree-api-erreurs avec une quinzaine de fichiers modifiés, et tu n'as pas vu un seul tour de ce travail. Depuis la leçon 10_4, tu sais ce que vaut un rapport sans preuve. Dans une session où tu es présent, tu attrapes l'erreur en une minute. Après la nuit, tu n'as que ce que l'exécution a écrit elle-même. C'est pourquoi tu intègres l'épreuve à l'exécution avant qu'elle appareille, et le matin tu compares le rapport à la carte des changements.
Ce que tu sais déjà
Dans la leçon 10_4, tu as découvert les degrés de rigueur : le critère dans la demande, /goal avec un modèle à part qui ne lit que la conversation, le hook Stop avec le code 2 et /verify, et dans la leçon 2_9 /code-review dans un subagent neuf. De la leçon 14_1, tu connais les champs du rapport de claude -p, de la leçon 14_2 les cinq questions avant de laisser un agent seul, de la leçon 14_6 les sessions dans le cloud et Remote Control, et de la leçon 14_7 le quart de nuit : commit, worktree, sandbox et --max-turns. Je ne répète pas ici ce que sont ces outils. Je montre comment les régler pour un long voyage que tu ne regardes pas.
Un objectif dans une exécution sans toi
/goal fonctionne aussi en mode -p : écrit au début de la demande, il mène la boucle jusqu'au bout en un seul appel. Il fonctionne aussi dans l'application de bureau et par Remote Control. Fixer un objectif lance tout de suite le travail, et la condition est en même temps la demande, donc elle doit dire quoi faire et à quoi on reconnaît la fin. La documentation avertit qu'avec la sortie texte ordinaire un long objectif a l'air suspendu, c'est pourquoi le départ de nuit de la leçon 14_7 passe au format flux. Tu le lanceras seulement après le hook de la section suivante.
Demande pour Claude Code (départ du quart) :
claude -p "/goal Toutes les routes de app/api renvoient leurs erreurs par lib/apiErrors.ts et ont des tests : grep -rn 'error:' app/api --include=route.ts n'affiche rien, et dans le résultat de find app/api -name 'route*.ts' chaque route.ts a un route.test.ts à côté ; npm run test -- --run se termine sans échec et npx tsc --noEmit sans erreur ; git diff --name-only --diff-filter=MD main -- '*.test.ts' n'affiche rien ; ou arrête-toi après 25 tours" \
--worktree api-erreurs --permission-mode auto --settings scripts/quart-de-nuit.json \
--max-turns 60 --output-format stream-json --verbose > flux-de-nuit.jsonlL'évaluateur n'exécute rien, donc chaque membre de la condition nomme une commande dont Claude doit montrer le résultat dans la conversation. Un grep vide prouve qu'il ne reste aucune erreur écrite à la main dans les routes, la liste de find montre une paire de fichiers à côté de chaque route, les tests et tsc donnent réussi ou non, et le dernier git diff garde l'interdiction de modifier les tests. La condition peut faire jusqu'à 4000 caractères, tu y mets donc tout ce que tu veux voir le matin.
Ce dernier membre a cette forme à cause de notre essai. Nous avions posé un objectif avec la condition git diff --stat -- '*.test.ts' n'affiche rien. Claude a annoncé la condition remplie, et a ajouté de lui-même que lib/plural.test.ts n'était pas suivi. git diff ne voit pas les fichiers non suivis, donc un test modifié hors d'un commit serait passé inaperçu. --diff-filter=MD main compare avec la branche main et n'affiche que les fichiers modifiés (M) et supprimés (D), même ceux que Claude a déjà commités. Les nouveaux tests passent et les anciens sont protégés, à condition qu'ils aient été dans un commit avant le départ.
Tu as une double limite. La clause "ou arrête-toi après 25 tours" est jugée par l'évaluateur d'après la conversation, donc elle est molle. --max-turns 60 est le frein dur du programme, compté en pas de l'agent : chez nous, un seul passage de l'objectif avec quatre appels d'outils a donné num_turns égal à 5, donc tu fixes la limite avec de la marge. La boucle s'arrête d'elle-même dans trois cas : quand l'évaluateur juge la condition remplie, quand il la juge impossible (il note alors la raison) et quand Claude répond plusieurs tours de suite sans utiliser d'outil. Une erreur que toi seul peux corriger, par exemple une connexion échouée ou des crédits épuisés sur le compte API, efface l'objectif et laisse un avertissement qui commence par Goal cleared after an unrecoverable error.
Le hook Stop pour un long quart
De la leçon 10_4, tu sais qu'après huit blocages de suite Claude Code termine quand même le tour. Un détail qui compte la nuit : le compteur repart de zéro chaque fois que Claude appelle un outil. La limite de blocages n'interrompra donc pas une boucle où l'agent essaie toujours quelque chose : elle protège seulement contre l'entêtement à vide. Le frein d'un long voyage reste --max-turns. Une fois la limite dépassée, Claude Code termine le tour avec un avertissement, et le hook peut reconnaître qu'il a déjà renvoyé Claude au travail grâce au champ stop_hook_active dans les données d'entrée.
L'interdiction de modifier les tests est une règle sans exception, elle reçoit donc un hook, mais seulement pour la nuit : de jour, tu modifies les tests exprès et tu ne veux pas que le hook te renvoie.
Demande pour Claude Code :
Écris .claude/hooks/tests-intacts.sh : un hook Stop qui se termine par le code 2
et un message sur stderr quand git diff par rapport à main montre un fichier *.test.ts
ou *.test.tsx modifié ou supprimé. Laisse passer les nouveaux fichiers de tests. Ajoute-le
à scripts/quart-de-nuit.json à côté du sandbox, pas à .claude/settings.json.
C'est fini quand le script, avec un JSON contenant le champ cwd, donne 2 pour un test modifié et 0 pour un nouveau.La demande donne l'événement, le code de sortie, l'endroit de l'entrée et l'épreuve, et l'interdiction d'écrire dans .claude/settings.json protège tes sessions de jour.
Ce que Claude a écrit : le hook
Ouvre .claude/hooks/tests-intacts.sh dans Cursor :
#!/bin/bash
# tests-intacts.sh : hook Stop qui renvoie Claude au travail quand il a modifié ou supprimé un test qui existait sur main
cd "$(jq -r '.cwd')"
MODIFIES=$(git diff --name-only --diff-filter=MD main -- ':(top)*.test.ts' ':(top)*.test.tsx')
if [ -n "$MODIFIES" ]; then
echo "Tests de main modifiés ou supprimés : $MODIFIES. Rétablis-les et corrige le code, pas le test." >&2
exit 2
fi
exit 0La première ligne passe dans le dossier de la session, donné par le champ cwd que le hook reçoit en entrée, car dans un worktree, le pont de Claude, c'est le dossier du worktree. Ensuite vient la même commande que dans la condition de l'objectif, mais cette fois c'est un programme qui la vérifie, pas un modèle. :(top) demande de compter les chemins depuis la racine du dépôt. Sans cela, le hook lancé depuis un sous-dossier ne voyait chez nous pas le test modifié dans lib/ et laissait tout passer. Le message va sur stderr, donc Claude le reçoit comme la raison pour laquelle il ne peut pas terminer.
Dans scripts/quart-de-nuit.json, à côté de la clé sandbox de la leçon 14_7, après la virgule, une entrée est venue, de la forme connue depuis la leçon 14_5 :
"hooks": {
"Stop": [
{
"hooks": [
{ "type": "command", "command": "bash", "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/tests-intacts.sh"] }
]
}
]
}Le script, comme les règles de la leçon 14_7, doit être dans le commit avant que tu appareilles. Vérifie-le comme dans la leçon 14_5, en donnant le JSON à la main : ajoute une ligne à lib/pins.test.ts et lance jq -n --arg cwd "$PWD" '{cwd: $cwd}' | bash .claude/hooks/tests-intacts.sh; echo $?. Chez nous, un test modifié a donné le message et 2, un nouveau fichier de tests 0, et un changement commité sur la branche encore 2. Ensuite, rétablis le test.
Le briefing du matin : le rapport contre le diff
Commence par le résultat de l'exécution. Le flux a beaucoup de lignes, et le résumé est dans l'événement de type result :
jq -c 'select(.type == "result") | {subtype, is_error, num_turns, refus: [.permission_denials[].tool_input]}' flux-de-nuit.jsonlsubtype et is_error disent si l'exécution s'est terminée normalement ou sur la limite, et refus montre ce que l'agent n'avait pas le droit de faire. Ce résultat ne prouve encore rien, car ce sont toujours les mots de l'exécution elle-même. La preuve, ce sont les résultats des commandes de la condition : ouvre flux-de-nuit.jsonl dans Cursor et cherche Test Files. La dernière occurrence doit montrer des tests au vert.
Puis la carte des changements. Dans le terminal de Cursor, git diff --stat main...worktree-api-erreurs affiche chaque fichier modifié sur la branche, et dans Source Control tu les ouvres un par un. Tu lis dans les deux sens : chaque phrase du rapport a son fichier dans le diff, et chaque fichier du diff a sa raison dans le rapport. Un fichier hors de app/api et de lib/, par exemple package.json ou quelque chose dans .claude/, est une question à poser avant de fusionner quoi que ce soit.
Enfin, des yeux neufs. Ouvre une session dans le dossier du worktree (cd .claude/worktrees/api-erreurs, puis claude) et tape /code-review : sans cible, il relit les commits de la branche avec les changements non commités, dans un subagent qui n'a pas vu la conversation de la nuit. Les corrections, tu les demandes dans la même session. Ce n'est qu'après avoir fusionné la branche dans main, dans le dossier principal où tu as .env et la base lancée avec npx prisma dev, que tu lances /verify : Claude construit l'application, la démarre et regarde le résultat. Tu supprimes ensuite le worktree avec la commande git worktree remove.
Les cinq questions comme liste de briefing
Les questions de la leçon 14_2, tu les poses deux fois : le soir avant le départ et le matin au briefing.
| Question | Dans cette exécution | Le matin, tu vérifies |
|---|---|---|
| Sait-il à quoi ressemble la fin ? | la condition de /goal | si le flux contient le résultat de chaque commande de la condition |
| Peut-il se vérifier ? | les tests, tsc, le hook Stop | le dernier Test Files dans le flux |
| À quoi a-t-il le droit de toucher ? | le worktree, le sandbox, les règles deny | refus et les fichiers hors de la tâche dans le diff |
| Qu'est-ce qui l'arrêtera ? | --max-turns 60 et la clause des 25 tours | subtype et num_turns |
| Qui valide le résultat ? | toi, après /code-review | tu fusionnes toi-même, jamais l'exécution |
La revue du capitaine
- La condition se voit dans la conversation. Chaque membre de l'objectif nomme une commande. Un membre du genre "le code est lisible", l'évaluateur le jugera à l'œil.
- Tests intacts.
git diff --name-only --diff-filter=MD main...worktree-api-erreurs -- '*.test.ts'n'affiche rien. - Une preuve, pas une phrase. Dans
resultou dans le flux se trouvent la commande et son résultat, pas seulement "tous les tests passent". - Les refus lus. Chaque entrée de
refusest soit une limite que tu as posée, soit la raison pour laquelle une partie du travail n'existe pas.
L'erreur typique de l'agent : quand un test ne veut pas passer, Claude l'affaiblit ou le supprime, et dans son rapport il parle de "nettoyage des tests". Tu le reconnais à la lettre M ou D devant un fichier .test.ts dans le diff de la branche. Le hook attrapera la modification et la suppression, mais un nouveau test faible, par exemple avec un simple toBeTruthy, il le laissera passer. Celui-là, seuls toi et /code-review le verrez.
Étape suivante
Le briefing a les mêmes étapes chaque matin, enferme-le donc dans un script, comme la relecture de la leçon 14_1 :
Enregistre le briefing du matin dans scripts/briefing.sh : le résultat de l'exécution depuis flux-de-nuit.jsonl
avec jq, git diff --stat main...worktree-api-erreurs et la liste des tests modifiés ou
supprimés. Le script ne fait que lire : il ne fusionne rien et ne supprime rien.Ensuite un commit, par exemple "Quart de nuit : hook qui garde les tests et briefing", et une traversée d'essai avec --max-turns 5 avant de lancer la complète. Dans l'éditeur à côté, tu écriras la condition de l'objectif, et le vérificateur signalera les membres que l'évaluateur ne verra pas dans la conversation.
N'oublie pas : un bon capitaine ne croit pas les rapports mais les écritures du journal de bord, et le journal du quart de nuit, c'est le résultat d'une commande et le diff de la branche.
Code de cette leçon : App.tsx
// Vérificateur de condition /goal : quels membres l’évaluateur verra dans la conversation, et lesquels non
import { useState } from 'react';
export type Level = 'ok' | 'warn' | 'error';
export interface Finding {
level: Level;
text: string;
}
export const MAX_LENGTH = 4000;
export const COMMANDS = ['npm ', 'npx ', 'git ', 'grep ', 'find ', 'ls ', 'jq ', 'wc ', 'node '];
export const CHECKS = ['npm test', 'npm run test', 'tsc', 'vitest', 'npm run build', 'npm run lint'];
export const VAGUE = ['lisible', 'joli', 'cohérent', 'pertinent', 'propre', 'bien', 'correct', 'cassé', 'fonctionne'];
export const SAMPLES: Record<string, string> = {
'Rapport sur parole': "/goal le code des routes est lisible et cohérent ; tous les tests passent ; rien n'est cassé",
'Condition de la leçon 10_4': "/goal npm run test -- --run se termine sans échec, npm run lint et npx tsc --noEmit passent, et git diff --stat n'affiche aucun changement dans les fichiers .test.ts ni .test.tsx ; ou arrête-toi après 15 tours",
'Quart de nuit': "/goal Toutes les routes de app/api renvoient leurs erreurs par lib/apiErrors.ts et ont des tests : grep -rn 'error:' app/api --include=route.ts n'affiche rien, et dans le résultat de find app/api -name 'route*.ts' chaque route.ts a un route.test.ts à côté ; npm run test -- --run se termine sans échec et npx tsc --noEmit sans erreur ; git diff --name-only --diff-filter=MD main -- '*.test.ts' n'affiche rien ; ou arrête-toi après 25 tours",
};
export function stripGoal(text: string): string {
const t = text.trim();
return t.startsWith('/goal') ? t.slice('/goal'.length).trim() : t;
}
export function isTurnClause(clause: string): boolean {
return /après \d+ tours/.test(clause);
}
export function hasCommand(clause: string): boolean {
const c = clause + ' ';
return COMMANDS.some((k) => c.includes(k));
}
export function clauses(condition: string): string[] {
return condition.split(';').map((c) => c.trim()).filter((c) => c.length > 0);
}
export function check(text: string): Finding[] {
const condition = stripGoal(text);
if (condition === '') return [{ level: 'error', text: 'Condition vide : /goal sans condition n’affiche que l’état de l’objectif.' }];
const out: Finding[] = [];
if (condition.length > MAX_LENGTH) {
out.push({ level: 'error', text: 'La condition fait ' + condition.length + ' caractères, et /goal en accepte au plus ' + MAX_LENGTH + '.' });
}
for (const c of clauses(condition)) {
if (isTurnClause(c)) continue;
const short = c.length > 60 ? c.slice(0, 60) + '...' : c;
if (hasCommand(c)) {
out.push({ level: 'ok', text: '"' + short + '" : nomme une commande dont Claude montrera le résultat dans la conversation.' });
} else if (VAGUE.some((v) => c.toLowerCase().includes(v))) {
out.push({ level: 'error', text: '"' + short + '" : jugement à l’œil. L’évaluateur n’exécute pas de commandes et ne lit pas de fichiers, il n’a donc rien à vérifier.' });
} else {
out.push({ level: 'warn', text: '"' + short + '" : sans commande. Ajoute avec quoi Claude doit le prouver.' });
}
}
const lower = condition.toLowerCase();
if (!CHECKS.some((k) => lower.includes(k))) {
out.push({ level: 'warn', text: 'Aucune épreuve qui dit réussi ou non : tests, tsc, lint ou build.' });
}
if (!lower.includes('.test.')) {
out.push({ level: 'warn', text: 'Rien ne garde les tests. Ajoute git diff --name-only --diff-filter=MD main -- *.test.ts ou un hook Stop.' });
} else if (lower.includes('git diff') && !lower.includes('--diff-filter=md main')) {
out.push({ level: 'warn', text: 'Ce git diff ne voit ni les fichiers non suivis ni les changements déjà commités par Claude. Compare avec main : git diff --name-only --diff-filter=MD main.' });
}
if (!clauses(condition).some(isTurnClause)) {
out.push({ level: 'warn', text: 'Pas de clause du genre "ou arrête-toi après 25 tours". La limite dure ne vient de toute façon que de --max-turns.' });
}
return out.filter((f, i) => out.findIndex((g) => g.text === f.text) === i);
}
const LEVEL_CLASS: Record<Level, string> = {
ok: 'text-emerald-400',
warn: 'text-amber-400',
error: 'text-rose-400',
};
export default function App() {
const [text, setText] = useState(SAMPLES['Rapport sur parole']);
const findings = check(text);
const problems = findings.filter((f) => f.level !== 'ok').length;
return (
<div className="min-h-screen space-y-4 bg-slate-950 p-4 text-slate-100">
<h1 className="text-xl font-bold">L’évaluateur verra-t-il cela ?</h1>
<div className="flex flex-wrap gap-2 text-sm">
{Object.keys(SAMPLES).map((name) => (
<button key={name} type="button" className="rounded bg-slate-800 px-2 py-1 hover:bg-slate-700" onClick={() => setText(SAMPLES[name])}>
{name}
</button>
))}
</div>
<label className="block text-sm">
Condition de l’objectif
<textarea className="mt-1 h-32 w-full rounded bg-slate-900 p-2 font-mono text-xs" value={text} onChange={(e) => setText(e.target.value)} />
</label>
<p className="text-xs text-slate-400">{stripGoal(text).length} / {MAX_LENGTH} caractères</p>
<p role="status" className="text-sm font-semibold">
{problems === 0 ? 'Chaque membre peut être confirmé par le résultat d’une commande.' : 'À corriger : ' + problems}
</p>
<ul className="space-y-1 text-sm">
{findings.map((f) => (
<li key={f.text} className={LEVEL_CLASS[f.level]}>{f.level}: {f.text}</li>
))}
</ul>
</div>
);
}Tu as repéré une erreur dans cette leçon ?
Teste tes connaissances
Réponds aux questions de cette leçon. Choisis une réponse pour voir tout de suite si elle est correcte.
1. Quelle condition de /goal l'évaluateur peut-il confirmer sans deviner dans une exécution de nuit ?
2. Pourquoi la condition "git diff --stat -- '*.test.ts' n'affiche rien" peut-elle laisser passer un test modifié ?
Voici 2 des 4 questions de cette leçon. Réponds aux autres dans le jeu.
Tâches pratiques dans le jeu
- Tri vertical
Mets dans l'ordre les étapes du briefing du matin après une exécution de nuit dans un worktree :
- Tri horizontal
Compose la commande qui donne au hook un JSON avec le dossier de la session et affiche son code de sortie :
Exercices après cette leçon
- QuestionQuiz : Une condition visible pour l'évaluateur
- QuestionQuiz : Ce que git diff ne voit pas
- Remets dans l'ordreTri : Le briefing du matin après l'exécution de nuit
- Remets dans l'ordreTri : L'essai à la main du hook Stop
- QuestionQuiz : Ce qui arrêtera le hook Stop
- QuestionQuiz : Les cinq questions au briefing du matin