Cours Vibe coding avec Claude Code · Module 15: Claude Code avancé

Agent de quart : scripts pour la revue, la documentation, les tests et les commits

10 min de lecture
Dans cette leçon9

Jette un œil dans la cale de Treasure Map. Dans lib/, il y a quatorze fichiers de code, et neuf d'entre eux n'ont pas de tests. Le README.md raconte encore create-next-app, alors que le projet a une base de données, des routes d'API et une recherche par image. Et les messages de commit de la semaine dernière sont sans doute "fix", "fix2" et "corrections". Aucune de ces tâches n'est difficile, chacune est ennuyeuse, et tu les repousses toutes. Ces corvées du quart de nuit, tu les confies à des scripts, et toi, tu gardes ce qu'un script ne fera pas : la décision.

Ce que tu sais déjà

Dans la leçon 14_1, tu as appris le pipe, la redirection >, les drapeaux --tools et --model, et le fait que -p sans permission n'écrira rien. De la leçon 10_4, tu sais qu'un test que tu n'as jamais vu au rouge a pu ne rien garder, et de la leçon 1_5 que la première ligne d'un message de commit dit "quoi" en 50 caractères. Dans la leçon 12_7, Claude est entré dans GitHub Actions. Maintenant, tu assembles ces briques en trois scripts, et tu les fais écrire par Claude Code.

Demande pour Claude Code : la documentation

Commence par la documentation, car c'est elle dont l'erreur coûte le moins. Dans une session Claude Code, écris :

Demande pour Claude Code :

Écris un script scripts/generate-docs.sh : trois appels à claude -p avec --model sonnet
et --max-turns 10. Résultats : docs/API.md à partir des routes de app/api, docs/COMPONENTS.md
à partir de components/ et le README.md de tout le projet, chacun enregistré par une redirection >.
Si un appel échoue, l'ancien fichier doit rester. Ne lance pas le script, montre-le-moi.

La dernière phrase compte : le script, tu le lis d'abord, et seulement ensuite tu le lances.

Ce que Claude a écrit : generate-docs.sh

Ouvre scripts/generate-docs.sh dans Cursor. En haut se trouve une variable avec la règle commune à tous les appels :

ONLY="Renvoie uniquement le contenu du fichier Markdown, sans clôtures autour de l'ensemble et sans phrases de ta part."
mkdir -p docs

Tout ce que Claude écrit atterrit dans le fichier : aussi la phrase "Voici la documentation :" et les trois signes de clôture autour de l'ensemble. Cette règle dit que le résultat doit être un fichier prêt, pas un message à propos d'un fichier. mkdir -p crée le dossier docs, et s'il existe déjà, ne fait rien. Le premier appel :

claude -p "Décris les routes de app/api : méthode, adresse, données d'entrée, réponses et codes d'erreur. $ONLY" \
  --model sonnet --max-turns 10 > docs/API.md.tmp && mv docs/API.md.tmp docs/API.md

La réponse va d'abord dans un fichier .tmp, car > vide le fichier avant que Claude commence. && ne lance mv que si claude s'est terminé en succès, donc une exécution interrompue par la limite de tours n'écrasera pas un bon docs/API.md avec un message d'erreur. Les deux appels suivants ont la même forme :

claude -p "Décris les composants de components/ : rôle, props et exemple d'utilisation. $ONLY" \
  --model sonnet --max-turns 10 > docs/COMPONENTS.md.tmp && mv docs/COMPONENTS.md.tmp docs/COMPONENTS.md

claude -p "Écris le README du projet : description, lancement, tests, base de données, structure des dossiers. $ONLY" \
  --model sonnet --max-turns 10 > README.md.tmp && mv README.md.tmp README.md

Pour le README, cet ordre a un deuxième avantage : Claude peut lire l'ancien fichier, car > ne vide que README.md.tmp. Aucun appel ne modifie le code : en mode -p sans permission, Claude ne fait que lire, et ce sont les fichiers de ton terminal qui sont écrits.

Il existe une seconde voie : demander "enregistre le résultat dans docs/API.md" et ajouter --permission-mode acceptEdits. Claude crée et modifie alors lui-même les fichiers du projet, mais tous, pas seulement ces trois. Lance un tel script seulement sur un arbre propre, quand git status n'affiche rien : le diff de Source Control est alors exactement le travail du script, et git restore annule chaque changement. Je conseille la redirection, car c'est le script qui décide où va le résultat.

Demande pour Claude Code : les tests

Maintenant, les neuf fichiers sans tests. Le projet utilise Vitest, donc c'est lui que tu demandes :

Écris scripts/generate-tests.sh : pour chaque fichier .ts de lib/ sans fichier .test.ts,
appelle claude -p en demandant des tests Vitest et enregistre le résultat à côté. Saute
les fichiers qui ont déjà des tests et ceux qui n'exportent aucune fonction. Une exécution
échouée ne doit pas laisser de fichier de tests. Ne lance pas le script, montre-le-moi.

Ce que Claude a écrit : generate-tests.sh

Le script est une boucle, c'est-à-dire le même ordre répété pour chaque fichier. Le premier fragment choisit les fichiers et saute ceux qui ont des tests :

for FILE in $(find lib -name "*.ts" ! -name "*.test.ts"); do
  TEST_FILE="${FILE%.ts}.test.ts"
  if [ -f "$TEST_FILE" ]; then
    continue
  fi

find lib -name "*.ts" attrape les fichiers TypeScript, et ! -name "*.test.ts" écarte les tests eux-mêmes. for ... do met à chaque tour un chemin dans la variable FILE. ${FILE%.ts} coupe la fin .ts, donc lib/plural.ts donne lib/plural.test.ts. [ -f "$TEST_FILE" ] demande si ce fichier existe, et continue passe au tour suivant. Tes tests restent intacts, et tu peux lancer le script à volonté. Le second filtre élimine les fichiers où il n'y a rien à tester :

  if ! grep -q "export .*function" "$FILE"; then
    echo "Je saute $FILE : n'exporte aucune fonction"
    continue
  fi

grep -q cherche du texte en silence et répond seulement par un succès ou un échec, et ! inverse la réponse. Chez nous, lib/types.ts avec ses seuls types et lib/prisma.ts avec le client de la base sont tombés : un test pour eux serait une coquille vide. Vient ensuite l'appel proprement dit :

  echo "J'écris les tests : $TEST_FILE"
  claude -p "Écris des tests Vitest pour @$FILE : chaque fonction exportée et les cas limites.
Renvoie uniquement du code TypeScript, sans clôtures Markdown et sans explications." \
    --model sonnet --max-turns 5 > "$TEST_FILE.tmp" || continue
  mv "$TEST_FILE.tmp" "$TEST_FILE"

Le terminal remplace $FILE par le chemin avant que Claude voie la phrase, donc @ désigne un fichier différent à chaque tour. || continue passe au fichier suivant quand claude échoue : il ne reste alors que le .tmp, et le lancement suivant réessaiera. Si le résultat allait directement dans .test.ts, un fichier raté bloquerait le test pour toujours, car [ -f ] le jugerait prêt. Le dernier fragment attrape l'erreur la plus fréquente de l'agent :

  if grep -q '^```' "$TEST_FILE"; then
    echo "Clôtures Markdown dans $TEST_FILE : retire-les avant de lancer les tests"
  fi
done

Quand Claude enveloppe le code dans des clôtures Markdown, le fichier cesse d'être du TypeScript. Sur une coquille vide avec clôtures, Vitest a signalé chez nous TypeError: "" is not a function et n'a lancé aucun test. Le même script fonctionne avec Jest : dans la demande, remplace le mot Vitest par Jest, et dans un projet avec le code dans src/, change aussi le chemin dans find.

La revue du capitaine

Lance bash scripts/generate-tests.sh et, avant d'ajouter quoi que ce soit au commit, vérifie :

  1. Chaque fichier de tests séparément : npm run test -- --run lib/plural.test.ts. Chez nous, Claude a écrit pour lib/plural.ts 34 cas et tous sont passés.
  2. Le test au rouge : casse la fonction un instant, comme dans la leçon 10_4. Dans lib/plural.ts, nous avons remplacé forms.few par forms.many et 11 des 34 tests sont passés au rouge. Puis git restore lib/plural.ts. Un test qui passe malgré la fonction cassée est une coquille vide.
  3. L'essai à la place du code : le garde des clôtures n'attrapera pas une réponse écrite en prose, comme dans la leçon 14_1 quand l'écriture a été bloquée. Seul le lancement du test l'attrape, donc le point 1 est obligatoire.

Demande pour Claude Code : le commit

Le troisième script se termine par ta signature :

Écris scripts/smart-commit.sh : à partir du diff de la zone de préparation, claude -p propose
un message de commit au format Conventional Commits, le script l'affiche et ne fait le commit
que lorsque j'ai tapé y. Une zone de préparation vide arrête le script sans appeler Claude.
Ne lance pas le script.

Conventional Commits est une convention sur la forme du message : type(portée): description, où le type est par exemple feat pour une nouvelle fonction, fix pour une correction, ou test et docs.

Ce que Claude a écrit : smart-commit.sh

D'abord, le garde de la zone de préparation vide :

DIFF=$(git diff --cached)
if [ -z "$DIFF" ]; then
  echo "La zone de préparation est vide. D'abord : git add <fichiers>"
  exit 1
fi

$(...) exécute une commande et met sa sortie dans une variable. [ -z "$DIFF" ] demande si la variable est vide, et exit 1 termine le script avec un code d'erreur avant que tu paies un message pour rien. Vient ensuite la proposition :

MESSAGE=$(echo "$DIFF" | claude -p "Écris un message de commit au format Conventional Commits : type(portée): description, en français, première ligne de 50 caractères maximum. Renvoie uniquement le message." \
  --model sonnet --tools "" --max-turns 2)

Le diff passe par le pipe et la réponse atterrit dans MESSAGE. --tools "" suffit, car pour le message Claude n'a besoin que du diff. À la fin, l'accord :

echo "Proposition : $MESSAGE"
read -r -p "Commit avec ce message ? (y/n) " ANSWER

if [ "$ANSWER" = "y" ]; then
  git commit -m "$MESSAGE"
else
  echo "Annulé, rien n'a été enregistré."
fi

read arrête le script et attend ta réponse au clavier, et git commit -m ne démarre qu'après y. Toute autre réponse n'enregistre rien. Ce n'est pas un ornement : le message peut omettre quelque chose que toi seul vois, par exemple que le changement de la limite de tags était voulu. Le commit, c'est toujours un humain qui le signe.

Étape suivante : le quart en CI

Le workflow avec @claude, tu le connais depuis la leçon 12_7. Ce qui est nouveau, c'est la revue qui laisse des remarques sur des lignes précises de la pull request. La documentation la présente comme une étape de l'action avec le plugin officiel code-review :

          plugins: "code-review@claude-plugins-official"
          prompt: "/code-review:code-review --comment ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"
          claude_args: '--allowedTools "mcp__github_inline_comment__create_inline_comment"'

Plus haut dans cette étape se trouve plugin_marketplaces avec l'adresse du marketplace officiel. --comment demande de publier la revue dans la pull request : un commentaire à chaque ligne qui pose problème, ou un commentaire de synthèse. claude_args doit nommer l'outil de commentaires, car l'action ne le lance que si --allowedTools le nomme. Dans un dépôt public, GitHub ne donne pas de secrets aux exécutions venues de forks, donc la revue ne démarrera que pour les branches de ton dépôt.

Quand tu laisses Claude seul, les best practices conseillent un jeu de trois drapeaux : --allowedTools approuve exactement ce dont la tâche a besoin, --permission-mode dontAsk refuse le reste, et --max-turns arrête l'exécution. Elles y ajoutent cinq questions : la tâche sait-elle à quoi ressemble la fin, peut-elle se vérifier, qu'a-t-elle le droit de toucher, qu'est-ce qui l'arrêtera, et qui approuve le résultat. Pour nos scripts, la réponse à la dernière est toujours la même : toi.

Dans l'éditeur à côté, tu feras passer des fichiers de lib/ dans la boucle generate-tests.sh et tu verras lesquels elle saute, où elle laisse un .tmp et quel test trahit la coquille vide.

N'oublie pas : l'automate propose, le marin décide, et chaque script s'arrête à ta signature.

Code de cette leçon : App.tsx
// Simulateur de la boucle generate-tests.sh : ce que le script saute, ce qu’il écrit et quel test veille
import { useState } from 'react';

export type Reply = 'code' | 'weak' | 'fenced' | 'essay' | 'error';
export type Status = 'has-test' | 'no-function' | 'written' | 'failed';

export interface LibFile {
  path: string;
  hasTest: boolean;
  exportsFunction: boolean;
}

export interface FileResult {
  path: string;
  status: Status;
  verdict: string;
  guarded: boolean;
}

export const FILES: LibFile[] = [
  { path: 'lib/boards.ts', hasTest: true, exportsFunction: true },
  { path: 'lib/columns.ts', hasTest: false, exportsFunction: true },
  { path: 'lib/imageCheck.ts', hasTest: false, exportsFunction: true },
  { path: 'lib/plural.ts', hasTest: false, exportsFunction: true },
  { path: 'lib/price.ts', hasTest: true, exportsFunction: true },
  { path: 'lib/prisma.ts', hasTest: false, exportsFunction: false },
  { path: 'lib/session.ts', hasTest: false, exportsFunction: true },
  { path: 'lib/types.ts', hasTest: false, exportsFunction: false },
];

const REPLY_LABEL: Record<Reply, string> = {
  code: 'du code seul, avec de vraies assertions',
  weak: 'du code seul, mais expect(1).toBe(1)',
  fenced: 'code entouré de clôtures Markdown',
  essay: 'une description en prose au lieu de code',
  error: 'erreur : limite de tours',
};

export function testPath(path: string): string {
  return path.replace(/\.ts$/, '.test.ts');
}

const VERDICT: Record<Reply, string> = {
  code: 'Vert, et rouge quand la fonction est cassée : le test veille.',
  weak: 'Vert même quand la fonction est cassée : une coquille vide, rejette-la.',
  fenced: 'Vitest : TypeError: "" is not a function, aucun test n’a démarré.',
  essay: 'Le garde se tait, car il n’y a pas de clôtures. L’erreur de syntaxe n’apparaîtra qu’au lancement du test.',
  error: 'Il ne reste que le fichier .tmp avec le message d’erreur. Le prochain lancement réessaiera.',
};

export function runLoop(files: LibFile[], replies: Record<string, Reply>, existing: string[]) {
  const log: string[] = [];
  const results: FileResult[] = [];
  const created: string[] = [];
  for (const file of files) {
    const test = testPath(file.path);
    if (file.hasTest || existing.includes(test)) {
      results.push({ path: file.path, status: 'has-test', verdict: 'A un test : continue.', guarded: false });
      continue;
    }
    if (!file.exportsFunction) {
      log.push('Je saute ' + file.path + ' : n’exporte aucune fonction');
      results.push({ path: file.path, status: 'no-function', verdict: 'Aucune fonction à tester.', guarded: false });
      continue;
    }
    log.push('J’écris les tests : ' + test);
    const reply = replies[file.path] ?? 'code';
    if (reply === 'error') {
      results.push({ path: file.path, status: 'failed', verdict: VERDICT.error, guarded: false });
      continue;
    }
    created.push(test);
    const guarded = reply === 'fenced';
    if (guarded) log.push('Clôtures Markdown dans ' + test + ' : retire-les avant de lancer les tests');
    results.push({ path: file.path, status: 'written', verdict: VERDICT[reply], guarded });
  }
  return { log, results, created };
}

const START: Record<string, Reply> = {
  'lib/columns.ts': 'code',
  'lib/imageCheck.ts': 'fenced',
  'lib/plural.ts': 'code',
  'lib/session.ts': 'weak',
};

const STATUS_CLASS: Record<Status, string> = {
  'has-test': 'text-slate-400',
  'no-function': 'text-slate-400',
  written: 'text-emerald-400',
  failed: 'text-amber-400',
};

export default function App() {
  const [replies, setReplies] = useState<Record<string, Reply>>(START);
  const [runs, setRuns] = useState(0);
  const first = runLoop(FILES, replies, []);
  const second = runLoop(FILES, replies, first.created);
  const shown = runs === 0 ? null : runs === 1 ? first : second;

  return (
    <div className="min-h-screen space-y-4 bg-slate-950 p-4 text-slate-100">
      <h1 className="text-xl font-bold">La boucle generate-tests.sh sur lib/ de Treasure Map</h1>
      <p className="text-sm text-slate-300">Choisis ce que Claude répondra pour les fichiers sans tests, puis lance le script.</p>
      <ul className="space-y-1 text-sm">
        {FILES.map((file) => (
          <li key={file.path} className="flex flex-wrap items-center gap-2">
            <code className="w-40 font-mono">{file.path}</code>
            {file.hasTest ? (
              <span className="text-slate-400">a déjà {testPath(file.path)}</span>
            ) : !file.exportsFunction ? (
              <span className="text-slate-400">n’exporte aucune fonction</span>
            ) : (
              <select
                className="rounded border border-slate-600 bg-slate-900 p-1"
                value={replies[file.path] ?? 'code'}
                onChange={(e) => {
                  setReplies({ ...replies, [file.path]: e.target.value as Reply });
                  setRuns(0);
                }}
              >
                {(Object.keys(REPLY_LABEL) as Reply[]).map((r) => (
                  <option key={r} value={r}>{REPLY_LABEL[r]}</option>
                ))}
              </select>
            )}
          </li>
        ))}
      </ul>
      <div className="flex gap-2">
        <button type="button" className="rounded bg-emerald-700 px-3 py-1" onClick={() => setRuns(1)}>bash scripts/generate-tests.sh</button>
        <button type="button" className="rounded bg-slate-700 px-3 py-1" disabled={runs === 0} onClick={() => setRuns(2)}>Lancer une seconde fois</button>
      </div>
      {shown && (
        <>
          <pre className="rounded bg-slate-900 p-2 font-mono text-xs">{shown.log.length ? shown.log.join('\n') : '(le script n’a rien affiché : tout a des tests)'}</pre>
          <ol className="space-y-1 text-sm">
            {shown.results.map((r) => (
              <li key={r.path} className="rounded border border-slate-800 p-2">
                <strong className={STATUS_CLASS[r.status]}>{r.path}</strong> {r.verdict}
              </li>
            ))}
          </ol>
          <p role="status" className="font-semibold">
            {runs === 1
              ? 'Lance chaque nouveau test et casse un instant sa fonction : c’est seulement alors que tu sais lequel veille.'
              : 'Le second lancement saute les fichiers qui ont déjà des tests et ne refait que ceux qui ont échoué.'}
          </p>
        </>
      )}
    </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. 1. Pourquoi les demandes de generate-docs.sh se terminent-elles par la règle "Renvoie uniquement le contenu du fichier Markdown, sans clôtures autour de l'ensemble et sans phrases de ta part" ?

  2. 2. Qu'est-ce qui fait que la revue officielle dans GitHub Actions laisse des remarques sur des lignes précises de la pull request ?

Voici 2 des 5 questions de cette leçon. Réponds aux autres dans le jeu.

Tâches pratiques dans le jeu

  • Tri horizontal

    Range la ligne de smart-commit.sh qui enregistre la proposition de message de commit dans la variable MESSAGE :

  • Éditeur de code

    Dans commands.sh, écris le script generate-docs.sh qui utilise claude -p pour créer trois fichiers : docs/API.md, docs/COMPONENTS.md et README.md. Enregistre chaque réponse dans son fichier avec la redirection >.

  • Tri horizontal

    Range l'appel de generate-docs.sh qui remplace docs/API.md seulement après une exécution réussie :

  • Tri vertical

    Range de haut en bas les lignes de la boucle de generate-tests.sh :

  • Éditeur de code

    Dans commands.sh, écris le script generate-tests.sh : trouve les fichiers .ts de src (find), ignore ceux qui ont déjà un fichier .test.ts ([ -f ... ]) et appelle claude -p pour les autres en demandant des tests Jest.

  • Tri vertical

    Range les étapes du fonctionnement du script smart-commit.sh :

  • Tri horizontal

    Range la ligne de generate-tests.sh qui choisit les fichiers sans fonctions exportées, afin de les sauter :

  • Tri vertical

    Range le travail avec generate-tests.sh, du lancement au commit :

  1. QuestionQuiz : Le fichier seul, sans message
  2. QuestionQuiz : Commentaires sur les lignes en CI
  3. Remets dans l'ordreTri : Le message de commit dans une variable
  4. Exercice de codePratique : générateur de documentation
  5. QuestionQuiz : Le garde des clôtures Markdown
  6. Remets dans l'ordreTri : Écrire par un fichier temporaire
  7. QuestionQuiz : Le nom du fichier de tests
  8. Remets dans l'ordreTri : Les lignes du script generate-tests.sh
  9. Exercice de codePratique : des tests pour les fichiers sans tests
  10. Remets dans l'ordreTri : Le script smart-commit
  11. QuestionQuiz : Les drapeaux du travail sans surveillance
  12. Remets dans l'ordreTri : Le filtre des fichiers sans fonction
  13. Remets dans l'ordreTri : Du script aux tests vérifiés

Articles utiles