Revue de code IA avec Claude Code : REVIEW.md et Symfony

Quand l'agent écrit une grosse part du code, la production n'est plus ce qui limite l'équipe : c'est la relecture. Anthropic indique, dans son billet du 21 juillet 2026 sur son cycle de développement, qu'environ 80 % de son code mergé est écrit par Claude, et que la part de PR avec des commentaires de revue substantiels est passée de 16 % à 54 % après l'arrivée de relecteurs IA. La revue a été renforcée, pas supprimée.

Le piège est symétrique. La doc des bonnes pratiques le dit : un relecteur chargé de trouver des manques en signale presque toujours, même quand le travail est sain. Courir derrière chaque remarque produit de la sur-ingénierie, et une équipe qui reçoit douze remarques de style par PR apprend en deux semaines à ignorer le bot, le jour même où il signale une vraie faille. La revue de code IA avec Claude Code se déploie en trois niveaux (local, CI, service managé), plus un fichier REVIEW.md qui la calibre. Cet article explique comment les régler comme un linter : un filtre qu'on ajuste, pas un juge qu'on écoute.

Quelle différence entre /code-review, ultra, la CI et Code Review managé ?

Ce sont quatre dispositifs distincts, malgré des noms proches. La doc de la revue de code les décrit ainsi :

• /code-review en local : une skill intégrée qui tourne en sous-agent d'arrière-plan, sur ton usage normal, en quelques secondes à quelques minutes. Elle suit ton CLAUDE.md mais ne lit pas REVIEW.md. C'est la boucle courte avant le push.
• /code-review ultra : une revue multi-agents dans le cloud, lancée depuis le terminal sur une branche ou une PR, en 15 à 25 minutes. Trois runs gratuits sur Pro et Max, puis environ 5 à 25 $ selon la taille du changement. Indisponible sur Bedrock, Vertex et Foundry, et en Zero Data Retention.
• En CI avec anthropics/claude-code-action@v1 : tu écris le workflow, tu choisis le prompt et le modèle. Coût en minutes GitHub Actions et en tokens.
• Code Review managé (Team et Enterprise, en research preview) : une flotte d'agents en parallèle sur l'infrastructure d'Anthropic, plus une étape de vérification qui filtre les faux positifs. En moyenne 20 minutes et 15 à 25 $ par revue, facturés en crédits d'usage. Il lit REVIEW.md et CLAUDE.md, et son check run est toujours neutre : il ne bloque jamais un merge.

Règle de décision : le local pour itérer, ultra avant de merger un gros changement, le service managé pour une politique d'équipe, et la CI maison quand tu as besoin de ton propre prompt, d'un autre fournisseur ou de GitLab. Sur un dépôt Symfony standard, la combinaison la plus rentable est souvent /code-review en local, plus le service managé en déclenchement manuel sur les PR à risque. Si tu veux un agent entièrement sur mesure, la construction via l'API est décrite dans notre article sur un agent de revue PHP en tool use.

Comment utiliser /code-review en local sans te noyer ?

La signature documentée est /code-review [low|medium|high|xhigh|max|ultra] [--fix] [--comment] [--max-findings n] [pr|branche|chemin]. Sans cible, elle relit les commits de ta branche en avance sur l'amont, plus les modifications non commitées. /review en est un alias depuis la v2.1.223.

# Revue rapide : uniquement les remarques à forte confiance
/code-review low

# Couverture large avant un gros refactoring
/code-review high

# PR d'un collègue, avec un plafond de remarques (v2.1.288+)
/code-review high 1234 --max-findings 8

# Publier les remarques en commentaires sur la PR
/code-review high 1234 --comment

# Appliquer les corrections dans l'arbre de travail
/code-review --fix

Le niveau est ton premier levier contre le bruit : à low, la revue ne rapporte que ce dont elle est la plus sûre ; plus haut, elle élargit la couverture et le bruit avec. Le dernier niveau saisi est mémorisé d'une session à l'autre, et --max-findings reste actif tant que tu ne repasses pas --max-findings default. Trois pièges de production :

• --fix et /rewind : la revue tournant en arrière-plan, ses éditions sortent des checkpoints de la session, et /rewind ne les annule pas. Commite avant, et reviens en arrière avec git.
• Pas de REVIEW.md en local : les règles valables partout vont dans CLAUDE.md, le calibrage propre au service managé dans REVIEW.md.
• En script ou en CI, claude -p '/code-review ultra' sort avant les résultats. La bonne commande est claude ultrareview, qui attend la fin et écrit les remarques sur la sortie standard (--json pour le format brut).

Depuis la v2.1.246, Claude peut aussi lancer /code-review de sa propre initiative. Pour le réserver à un usage manuel, mets "skillOverrides": { "code-review": "user-invocable-only" } dans les settings. À côté, /security-review est une commande distincte qui analyse la différence avec la branche par défaut pour les risques d'injection, d'authentification et d'exposition de données.

Comment faire tourner la revue IA dans ta CI ?

Quand le service managé n'est pas disponible (plan, Zero Data Retention, GitLab, contrainte de souveraineté), la revue tourne dans ton propre pipeline. La doc des GitHub Actions donne un workflow qui installe le plugin de revue et le lance sur chaque PR. Version adaptée pour limiter la dépense :

name: Code Review
on:
  pull_request:
    types: [opened, ready_for_review]   # pas "synchronize" : évite de payer chaque push
concurrency:
  group: claude-review-${{ github.event.pull_request.number }}
  cancel-in-progress: true
jobs:
  review:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    permissions:
      contents: read
      pull-requests: read
      issues: read
      id-token: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          plugin_marketplaces: "https://github.com/anthropics/claude-code.git"
          plugins: "code-review@claude-code-plugins"
          prompt: "/code-review:code-review --comment ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"
          claude_args: '--allowedTools "mcp__github_inline_comment__create_inline_comment" --max-turns 30'

Sans --comment, rien n'est publié sur la PR. Sur un dépôt public, GitHub n'expose pas les secrets aux PR de forks : la revue ne tourne que pour les branches du dépôt, et contourner avec pull_request_target sans lire la doc de sécurité de l'action est une mauvaise idée. --max-turns, timeout-minutes et concurrency sont tes trois garde-fous de coût. Je n'ai pas pu confirmer que ce plugin lit REVIEW.md : dans ce mode, pilote le calibrage par CLAUDE.md ou par le prompt. Pour durcir ce pipeline, voir sécuriser un pipeline GitHub Actions avec des agents de code.

Comment fonctionne Code Review managé ?

À l'ouverture de la PR, à chaque push ou sur demande, plusieurs agents analysent le diff et le code environnant en parallèle, chacun sur une classe de problèmes. Une étape de vérification confronte ensuite chaque remarque au comportement réel du code pour écarter les faux positifs. Les résultats sont dédoublonnés, publiés en commentaires dans le diff et classés en trois sévérités : Important (bug à corriger avant merge), Nit (mineur) et Pre-existing (défaut déjà présent avant la PR). En déclenchement manuel, un commentaire @claude review lance une revue, et @claude review always abonne la PR aux pushes suivants.

Le check run étant toujours neutre, aucune protection de branche ne peut s'appuyer dessus tel quel. C'est un bon choix de conception : un relecteur probabiliste ne doit pas bloquer seul un merge, et un filtre qui bloque sur un faux positif se fait contourner en une semaine. Si tu veux malgré tout bloquer sur les remarques Important, la doc documente une ligne lisible par machine dans la sortie du check run :

gh api repos/OWNER/REPO/check-runs/CHECK_RUN_ID \
  --jq '.output.text | split("bughunter-severity: ")[1] | split(" -->")[0] | fromjson'
# => {"normal": 2, "nit": 1, "pre_existing": 0}   (normal = Important)

Un workflow déclenché sur la fin du check run peut lire ce décompte et échouer s'il trouve une remarque Important : c'est un montage à toi, à tester avant d'en faire un check requis. Le vrai blocage reste tes contrôles déterministes, tests, PHPStan et hooks, détaillés dans l'article sur la vérification d'abord.

Que mettre dans un REVIEW.md pour un dépôt Symfony ?

REVIEW.md est un fichier Markdown libre, à la racine du dépôt, que le service managé transmet aux agents qui cherchent et vérifient les remarques. La doc liste ce qu'on y règle : la définition d'Important, le plafond de nits, les exclusions (chemins, branches, ce que la CI applique déjà), les contrôles propres au dépôt, un seuil de preuve, la convergence après la première revue et la forme du résumé. Elle insiste sur un point : un REVIEW.md long dilue les règles importantes. Voici un exemple pour Symfony, Doctrine et Messenger, à adapter à ton domaine :

# Review instructions (Symfony / Doctrine / Messenger)

## What Important means here
Reserve Important for findings that would break production, leak data
or block a rollback:
- Missing authorization: a controller action, API operation or Messenger
  handler that reads or mutates data without a Voter or #[IsGranted].
- Tenant leaks: a Doctrine query not scoped to the current user or tenant.
- Mass assignment: an entity bound from the request without an explicit
  allow-list of fields.
- Non-idempotent Messenger handlers (email, payment, external API) on a
  transport with retries.
- Doctrine N+1: a loop triggering a lazy-loaded association on a list
  endpoint, a console command or a batch handler.
- Migrations not backward compatible with the previous release.
- Secrets or personal data in logs or exception messages.
Style, naming and refactoring suggestions are Nit at most.

## Cap the nits
Report at most 5 Nits per review; summarize the rest as "plus N similar
items". After the first review of a PR, report Important findings only.

## Do not report
- Anything CI already enforces: PHP-CS-Fixer, PHPStan, Rector.
- vendor/, var/, public/build/, composer.lock, symfony.lock.
- Style in migrations/ (but DO check schema backward compatibility).
- Branches matching dependabot/* and renovate/*.

## Always check
- New routes or API operations have an access rule AND a functional test
  covering the denied case.
- New input DTOs carry #[Assert\...] constraints and are mapped with
  #[MapRequestPayload] or #[MapQueryString].
- Repository methods returning collections fetch-join the associations
  the caller iterates over.

## Evidence bar
Behavior claims need a file:line citation, not an inference from naming.

## Summary shape
Open with a one-line tally such as "2 Important, 3 Nit".

Chaque bloc répond à un problème de bruit. Les exclusions évitent de payer des agents pour relire du code généré ou déjà couvert par PHPStan. Le plafond de nits et la règle de convergence coupent les septièmes allers-retours sur le style. Le seuil de preuve écarte les remarques déduites d'un nom de méthode. Et les quelques contrôles « Always check » sont les rares règles propres à ton dépôt qui méritent un commentaire sur chaque PR. CLAUDE.md reste lu comme contexte : n'y duplique pas ces règles.

Comment déployer en shadow mode sans bloquer l’équipe ?

Le shadow mode est une période où la revue IA commente sans que personne soit tenu d'agir, le temps de mesurer sa pertinence. Anthropic l'applique à ses propres relecteurs, et garde un échantillon pondéré par le risque relu par des humains. La même discipline, en quatre temps :

• Semaines 1 et 2, observation : un dépôt pilote en déclenchement manuel, @claude review sur des PR choisies. L'équipe vote chaque remarque, pouce en haut ou en bas, sans obligation de la traiter.
• Semaines 3 et 4, calibrage : chaque faux positif récurrent devient une ligne dans « Do not report » ou dans le seuil de preuve ; chaque bug manqué, découvert en revue humaine ou en production, devient une ligne dans « Always check ».
• Ensuite, automatique : revue unique à la création de la PR. Garde la revue à chaque push pour les dépôts critiques seulement, puisqu'elle multiplie le coût par le nombre de pushes.
• En continu, échantillon humain : même quand l'IA a relu, une partie des PR passe par un humain, pondérée par le risque. Relecture systématique sur security.yaml, les voters, les migrations et le paiement ; échantillon sur le reste.

Pour mesurer le taux de remarques acceptées, le tableau de bord Code Review d'Anthropic expose le nombre de PR relues, le coût et les commentaires résolus parce que le développeur a corrigé le problème. Côté équipe, compte les fils de discussion résolus par un commit : le bouton « Resolve » sert aussi à écarter une remarque, et ne prouve pas qu'elle était juste.

Combien coûte la revue IA, et quoi piloter ?

Le service managé coûte en moyenne 15 à 25 $ par revue, variable avec la taille de la PR et le nombre de remarques à vérifier. Exemple de calcul à refaire avec tes chiffres : 50 PR par semaine relues une fois, c'est 750 à 1 250 $ par semaine ; en revue à chaque push, multiplie par le nombre moyen de pushes. Un plafond mensuel se règle dans l'administration ; une fois atteint, la revue est sautée et un commentaire l'indique sur la PR. À ce prix, la revue managée n'est pas un réflexe pour une correction de typo : elle se justifie là où une erreur coûte cher. Cinq indicateurs suffisent pour piloter :

• Taux de remarques Important corrigées par commit, rapporté aux remarques publiées. Un taux bas signale du bruit : suis la tendance, pas un seuil magique.
• Remarques et nits par PR : s'ils dérivent à la hausse, ton REVIEW.md manque d'exclusions.
• Échappés : bugs trouvés en production ou par un humain sur des PR déjà relues par l'IA. C'est la seule mesure de ce que la revue rate.
• Temps de cycle et nombre d'allers-retours : la revue IA doit en retirer, pas en ajouter.
• Coût par remarque acceptée : dépense du mois divisée par les remarques Important corrigées.

Pour repère, Anthropic cite son client Intercom : 19 % de PR auto-approuvées et 35 % d'indisponibilités en moins dues à des changements cassants. Ce sont les chiffres d'une seule entreprise, dans son contexte : un ordre de grandeur, pas une promesse. Le code généré a par ailleurs ses propres faiblesses récurrentes, documentées dans notre article sur la dette du code produit par les agents.

La revue IA remplace-t-elle la revue humaine ?

Non. Par défaut, le service managé se concentre sur la correction : les bugs qui casseraient la production, pas le formatage. Il ne sait pas si la PR devait exister, si ce nouveau handler Messenger aurait dû être un simple appel synchrone, ou si la dette introduite est un choix assumé pour tenir une échéance. Il ne connaît ni ta stratégie produit, ni l'incident qui explique une règle étrange. Une remarque peut être juste techniquement et fausse métier. L'architecture, le métier et les zones à risque restent la valeur de la revue humaine, qui peut justement s'y concentrer puisque la chasse aux bugs de logique est en partie déléguée.

• Commencer en local : /code-review low avant chaque push, avec --max-findings.
• Écrire CLAUDE.md d'abord, puis un REVIEW.md court.
• Activer le service managé sur un seul dépôt, en manuel, avec un plafond de dépense.
• Mesurer deux sprints, puis ajuster les exclusions.
• Garder un échantillon humain pondéré par le risque, et une relecture systématique sur la sécurité, les migrations et le paiement.

La revue IA est un filtre qu'on calibre comme un linter : on part trop bavard, on mesure ce qui fait perdre du temps, on retire ou on reclasse, et on recommence chaque mois. Le calibrage ne vaut que s'il est partagé : un REVIEW.md versionné, relu par l'équipe sur son code réel. Dernier article de la série : concevoir ton harness agentique, et le simplifier à chaque nouveau modèle.

Écrit par

Flavien Métivier

Expert PHP/Symfony indépendant depuis 2014, ancien CTO de Kartable et d'Extrabat. Plus de 80 projets menés, de l'audit à la migration.

Mon parcours