Revue de code avec Claude Code pour les équipes

Claude Code est utile en revue de code lorsqu’il devient un flux répétable, pas lorsqu’il sert d’avis improvisé. Son rôle est de trier le PR, signaler les zones à risque, poser de meilleures questions et laisser les humains décider de l’architecture, de l’intention produit et de la responsabilité d’ownership.

Pour une équipe, le socle pratique combine un template de PR, des règles dans CLAUDE.md, un gate de taille de diff, GitHub Actions, CODEOWNERS et un prompt qui exige des preuves. Gardez les références officielles ouvertes : Claude Code common workflows, documentation GitHub sur les pull requests, CODEOWNERS, GitHub Actions workflow syntax et OWASP Code Review Guide.

Système de revue

Une revue basée sur le risque ne lit pas chaque ligne avec la même intensité. Authentification, autorisation, paiement, migration de données, performance et tests manquants demandent plus d’attention. Diff scope signifie le périmètre réellement modifié par ce PR. Un CI gate est une vérification automatique qui bloque ou avertit. Un hallucinated finding est une remarque IA plausible, mais sans preuve dans le diff.

flowchart LR
  A["PR template"] --> B["Diff size gate"]
  B --> C["Claude Code review"]
  C --> D["Code owner review"]
  D --> E["CI tests and merge"]
  C --> F["Questions before fixes"]

La règle centrale : Claude Code ne doit pas réécrire le code silencieusement pendant la revue. Si l’intention métier, le contrat de données ou la politique de permission n’est pas claire, il doit poser une question.

Cas d’usage concrets

Premier cas : authentification et autorisation. Pour login, sessions, rôles, écrans admin et API keys, demandez à Claude Code de chercher les oublis d’autorisation, l’escalade de privilèges, les secrets exposés et les audit logs manquants. La règle métier reste une décision humaine. Pour aller plus loin, lisez l’audit de sécurité avec Claude Code.

Deuxième cas : performance. Recherche, listes, caches, images et jobs batch peuvent cacher des requêtes N+1, des rendus répétés, de mauvaises clés de cache et de gros payloads. Un bon commentaire indique à quelle taille d’entrée le problème apparaît et comment le mesurer.

Troisième cas : tests et migrations. Schema, migrations, seeds, validation et backfills exigent une réflexion sur rollback, données existantes, champs nullable, contraintes uniques et reprise après échec. Claude Code peut préparer la liste avant la revue du responsable données.

Quatrième cas : PR trop gros. Au-delà de 800 à 1000 lignes modifiées, la qualité de revue baisse. Le CI peut avertir ou bloquer, et Claude Code peut proposer un découpage par comportement, migration, UI et tests.

Template de PR

Créez .github/pull_request_template.md.

## Change summary
- What changed:
- Why it changed:
- User-visible impact:

## Risk review
- [ ] Security impact checked
- [ ] Performance impact checked
- [ ] Test coverage added or explained
- [ ] Data migration or rollback plan checked
- [ ] No secrets, tokens, or personal data included

## Claude Code review request
Please review this PR by diff scope only.

Focus on:
- Security: auth, authorization, injection, secret leakage
- Performance: N+1 queries, cache keys, unnecessary work
- Tests: missing unit, integration, and migration tests
- Data: schema changes, rollback, backfill safety

For each finding, include:
- file and line
- why it matters
- evidence from the diff
- suggested fix or question for the author

La mention diff scope only garde Claude Code dans les preuves du PR, au lieu de produire des conseils génériques sur tout le dépôt.

Règles CLAUDE.md

Ajoutez la politique de revue dans CLAUDE.md. C’est la mémoire locale que Claude Code utilise pour les standards du projet. Pour la structure complète, consultez les bonnes pratiques CLAUDE.md.

## Code review rules

Review only the current diff unless the user asks for wider context.

Severity:
- Must fix: security bug, data loss, broken build, failed test, migration risk
- Should fix: likely production bug, missing important test, measurable performance issue
- Nice to have: naming, small cleanup, optional refactor

Evidence rule:
- Every finding must cite a file and line.
- If the evidence is uncertain, ask a question instead of asserting a bug.
- Do not invent dependencies, routes, database columns, or team policies.

Security checks:
- Authentication and authorization
- SQL or command injection
- XSS and unsafe HTML
- Secret leakage
- Missing audit log for privileged actions

Data checks:
- Migration rollback path
- Backfill failure behavior
- Existing nullable and unique constraints
- PII handling and retention

La règle de preuve évite beaucoup de faux positifs. Sans fichier, ligne et raison, une remarque doit devenir une question.

Script de gate

Enregistrez ce fichier sous scripts/review-diff-gate.mjs.

#!/usr/bin/env node
import { execSync } from "node:child_process";

const baseRef = process.env.BASE_REF || "origin/main";
const maxFiles = Number(process.env.MAX_REVIEW_FILES || 25);
const maxLines = Number(process.env.MAX_REVIEW_LINES || 800);

function git(command) {
  return execSync(command, { encoding: "utf8" }).trim();
}

const files = git(`git diff --name-only ${baseRef}...HEAD`)
  .split(/\r?\n/)
  .filter(Boolean);

const numstat = git(`git diff --numstat ${baseRef}...HEAD`);
const changedLines = numstat
  .split(/\r?\n/)
  .filter(Boolean)
  .reduce((total, line) => {
    const [added, deleted] = line.split(/\s+/);
    return total + (Number(added) || 0) + (Number(deleted) || 0);
  }, 0);

const riskyPatterns = [
  /^src\/auth\//,
  /^src\/billing\//,
  /^db\/migrations\//,
  /^infra\//,
  /^\.github\/workflows\//,
];

const riskyFiles = files.filter((file) =>
  riskyPatterns.some((pattern) => pattern.test(file))
);

let failed = false;

if (files.length > maxFiles) {
  console.error(`Too many files changed: ${files.length} > ${maxFiles}`);
  failed = true;
}

if (changedLines > maxLines) {
  console.error(`Too many changed lines: ${changedLines} > ${maxLines}`);
  failed = true;
}

if (riskyFiles.length > 0) {
  console.log("Risk-sensitive files changed:");
  for (const file of riskyFiles) console.log(`- ${file}`);
}

if (failed) {
  console.error("Split the PR or add a reviewer-approved exception.");
  process.exit(1);
}

console.log(`Review gate passed: ${files.length} files, ${changedLines} lines.`);

Exécution locale :

BASE_REF=origin/main MAX_REVIEW_FILES=25 MAX_REVIEW_LINES=800 node scripts/review-diff-gate.mjs

GitHub Actions et CODEOWNERS

Ajoutez .github/workflows/review-gate.yml.

name: review-gate

on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  diff-gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: "22"

      - name: Run diff size gate
        env:
          BASE_REF: origin/${{ github.base_ref }}
          MAX_REVIEW_FILES: "25"
          MAX_REVIEW_LINES: "800"
        run: node scripts/review-diff-gate.mjs

Puis routez les zones sensibles avec CODEOWNERS.

# .github/CODEOWNERS
/src/auth/ @example-org/security
/src/billing/ @example-org/payments
/db/migrations/ @example-org/backend-leads
/.github/workflows/ @example-org/platform
/infra/ @example-org/platform

Ne faites pas de la sortie IA le premier blocage dur du merge. Stabilisez d’abord lint, typecheck, tests et taille de diff. Pour la suite, lisez le guide CI/CD et l’amélioration de qualité des PR.

Prompt de revue

Review the current PR diff against main.

Rules:
1. Stay inside the diff scope unless a referenced file is required.
2. Do not rewrite code silently.
3. For each finding, include file, line, severity, evidence, and suggested action.
4. If business intent or data contract is unclear, ask a question instead of guessing.
5. Ignore style-only preferences unless they break CLAUDE.md or project conventions.

Focus areas:
- Security: auth, authorization, injection, XSS, secrets, audit logs
- Performance: N+1 queries, cache invalidation, repeated rendering, large payloads
- Tests: missing coverage for changed behavior, migrations, and edge cases
- Data migration: rollback, backfill, nullable fields, unique constraints
- CI and ownership: required checks, CODEOWNERS, risky paths

Output:
## Must fix
## Should fix
## Questions
## No issue found in

Pièges et vérification

Premier piège : demander à Claude Code de tout revoir et tout corriger en une passe. Cela agrandit le diff avant validation des constats. Faites d’abord la revue, choisissez les corrections, puis lancez les tests.

Deuxième piège : accepter des remarques sans preuve. Si Claude Code ne cite pas fichier, ligne et comportement modifié, traitez le point comme une question.

Troisième piège : sous-estimer les migrations. Des tests verts ne prouvent pas que les données de production sont sûres. Vérifiez NULL existants, doublons, locks, rollback et backfill.

J’ai vérifié les exemples comme flux minimal : le script dépend de Git et Node 22, l’Action exécute le même script, et les templates forcent Claude Code à rester dans le diff. En équipe, commencez une semaine en mode avertissement, ajustez les seuils, puis rendez obligatoires seulement les contrôles fiables. Pour continuer, utilisez la checklist de gate avant commit.