Subagent code-review pour Claude Code : template & bonnes pratiques

Phrase d’accroche — un subagent bien configuré te fait gagner des heures sur les revues de code récurrentes.

Si tu utilises Claude Code pour automatiser une partie des revues, un subagent code-review bien écrit transforme des commentaires bruyants en actions exploitables : checklist, correctifs automatiques et suggestions ciblées. Ce guide te donne un template prêt à copier-coller, 7 règles pratiques et des tests rapides pour éviter les faux positifs et les régressions.

---

Pourquoi un subagent code-review ?

Les revues de code automatisées ne sont pas nouvelles, mais avec Claude Code elles deviennent interactives : l’agent lit des fichiers, exécute des tests, propose des commits. Sans règles claires, tu obtiens soit du bruit (commentaires génériques), soit des actions dangereuses (modifications hors-scope). Un subagent:code-review — déclaré dans ton CLAUDE.md ou comme skill — sert de contrat : il limite l’étendue, expose les commandes exactes et rend les retours reproductibles.

Sources utiles : notre template CLAUDE.md minimal pour monorepo pnpm (voir /blog/fr/2026-05-23-claude-md-minimal-monorepo-pnpm/) et l’article sur les hooks Claude Code (/blog/fr/2026-05-24-claude-code-hooks-eviter-drift-lint-tests/).

Thèse — ce que ce guide résout

Si tu as déjà vu un agent ouvrir 20 fichiers, lancer une batterie de tests inutile, ou modifier des migrations Prisma par erreur, ce guide est pour toi. Objectif : un subagent code-review qui :

• exécute un set limité de checks (lint, tests ciblés),
• produit un rapport structuré (commentaires + patch suggestion),
• propose un commit prêt à vérifier humainement,
• n’effectue jamais de merges ou modifications critiques sans revue humaine.

Template minimal — copy/paste

Colle ceci dans ton CLAUDE.md (package-specific) ou dans une skill réutilisable :

## Subagent: code-review

name: "subagent:code-review"
role: "examine les changements proposés, exécute des checks, propose un patch et un message de commit. NE PAS pousser sur main."

commands:
- name: install
  run: "pnpm install --frozen-lockfile"
- name: lint
  run: "pnpm --filter=@myorg/frontend lint -- --max-warnings=0"
- name: test-targeted
  run: "pnpm --filter=@myorg/frontend test -- -t 'should handle X' --runInBand"
- name: smoke
  run: "pnpm --filter=@myorg/frontend smoke"

paths_to_check:
- "packages/frontend/src"
- "packages/api/src"

no_touch:
- "prisma/migrations/"
- "infra/terraform/"

output_format: "report+patch"

limits:
  max_files: 12
  max_diff_lines: 600
  max_runtime_seconds: 300

on_findings:
  - create_patch_file: true
  - propose_commit_message: true
  - notify_human: true

Ce template est volontairement court. Rappelle-toi : chaque ligne coûte des tokens et peut ralentir l’agent. Pour plus de contexte sur la minimalité des fichiers de contexte, relis notre comparaison CLAUDE.md vs AGENTS.md (/en/blog/2026-04-14-claude-md-vs-agents-md-ai-repo-context/).

7 bonnes pratiques

1. Limite l’étendue — paths_to_check

Liste explicitement les dossiers pertinents. Trop large = bruit. Dans un monorepo pnpm, préfère packages/<name>/src plutôt que la racine.

2. Définit des commandes exactes

Les agents obéissent littéralement aux commandes. Indique des flags (ex: --runInBand, --max-warnings=0) pour rendre les checks déterministes.

3. Interdiction explicite des zones dangereuses

Utilise no_touch pour protéger prisma/migrations/, infra/terraform/, ou tout artefact non réversible. Les erreurs humaines arrivent — anticipe-les.

4. Short-circuit pour les gros diffs

Si le PR dépasse max_files ou max_diff_lines, le subagent doit demander une revue humaine plutôt que tenter une correction automatique.

5. Génère un patch, ne pousse jamais

Le subagent doit produire un patch (diff) et un message de commit suggéré. Ne pas pousser sur main. L’humain vérifie, adapte et merge.

6. Log & provenance

Chaque action doit écrire un report.json avec : fichiers lus, commandes exécutées, versions (node/pnpm), et hash du commit ciblé. Cela facilite l’audit et le rollback.

7. Tests ciblés avant modifications

Exécute seulement les tests liés aux fichiers modifiés. Plusieurs articles dans notre repo montrent que lancer l’intégralité de la suite augmente le temps et les faux positifs (voir /blog/fr/2026-05-24-claude-code-hooks-eviter-drift-lint-tests/).

Checklist rapide — avant d’activer le subagent

• CLAUDE.md ou AGENTS.md existant importé (@AGENTS.md) pour éviter duplication
• paths_to_check limités à 2–4 dossiers
• max_files <= 12
• commands reproductibles localement (tester en CI)
• no_touch listée et vérifiée
• report.json loggable dans un dossier ./.agent-reports/

Tests rapides pour valider le comportement (5 min)

1. Petit PR faux-positif

• Crée un PR trivial (ex: correction d’une typo dans README). Vérifie que le subagent l’ignore si hors paths_to_check.

2. PR avec modifs frontend

• Change un composant dans packages/frontend/src. Vérifie que le subagent lance lint + tests ciblés et propose un patch si besoin.

3. Gros PR bloqué

• Simule un PR avec 50 fichiers modifiés. Le subagent doit refuser d’autocorriger et générer un message “Human review required: large diff”.

4. Test de sécurité

• Modifie un fichier sous prisma/migrations/. Le subagent doit loguer l’incident et ne pas appliquer de patch.

5. Repro local

• Exécute les mêmes commandes que le subagent dans un conteneur local (CI) et compare les sorties pour garantir déterminisme.

Exemples de messages de sortie (format attendu)

• Report (report.json) :

  • files_checked: [ … ]
  • commands: [ {name: “lint”, exit: 0} ]
  • findings: [ {path: “x”, type: “style”, suggestion: “replace …”} ]
  • patch_file: “/tmp/agent_patch.diff”
  • suggested_commit_message: “fix(frontend): corrige l’overflow dans Button — suggestions auto du subagent”

• Human note (plain text) :

  • “Le subagent a identifié 3 suggestions de style et propose un patch. Revue humaine requise pour DB/migrations. Report : ./.agent-reports/2026-06-09-.json”

Pièges communs & comment les éviter

• Trop de verbosité : un CLAUDE.md long = plus d’erreurs. Couper les sections inutiles.
• Générer des commits sans vérification humaine : règle absolue, ne jamais pousser automatiquement.
• Tests non déterministes : locke les versions et utilise --runInBand ou --ci quand possible.
• Ignorer la provenance : toujours inclure des logs et des hashes de commit dans le report.

Et maintenant ? (pour aller plus loin)

• Intègre une étape CI qui reproduit exactement le workflow du subagent pour valider les résultats avant de merge.
• Ajoute des métriques : temps d’exécution moyen, taux de suggestions acceptées, et nombre de faux positifs par mois.
• Si tu utilises claude-mem, synchronise report.json avec la mémoire pour améliorer les prochaines revues.

---

Ce guide s’appuie sur nos templates CLAUDE.md et les runs précédents (voir /blog/fr/2026-05-23-claude-md-minimal-monorepo-pnpm/ et /blog/fr/2026-05-24-claude-code-hooks-eviter-drift-lint-tests/). Si tu veux, je peux ouvrir une PR automatiquement avec ce fichier et le placeholder image (je m’en occupe maintenant).