Améliorer la qualité des Pull Requests avec Claude Code

Une Pull Request est l’endroit où une équipe propose, relit et fusionne un changement. La documentation officielle de GitHub en fait un espace central de collaboration, et ce rôle devient encore plus visible quand Claude Code accélère l’implémentation. Le problème n’est plus seulement d’écrire le code, mais de rendre le changement lisible : description vague, diff trop grand, preuves de test absentes, impact sécurité mal expliqué et commentaires de revue qui tournent en boucle.

Dans ce guide, Claude Code sert d’assistant qualité pour les PR, pas seulement de générateur de texte. Un diff est l’ensemble des lignes modifiées, la CI est la barrière automatisée de build et de test, un diff-size budget est une limite de taille de PR, et le handoff est la note courte qui permet au prochain relecteur de reprendre sans tout relire. Pour compléter, voyez aussi la revue de code avec Claude Code et les stratégies de test.

flowchart LR
  A["Implémenter avec Claude Code"] --> B["Remplir le modèle de PR"]
  B --> C["Limiter le diff en CI"]
  C --> D["Ajouter les preuves de test"]
  D --> E["Préparer le handoff"]
  E --> F["Rédiger les notes de version"]

Les références officielles utilisées sont GitHub Pull Requests, création d’un modèle de PR, syntaxe des workflows GitHub Actions, branches protégées, secrets dans GitHub Actions, Claude Code docs et, si vous classez vos commits, Conventional Commits.

Fixer le standard dans un modèle de PR

Demander à Claude Code de “rédiger une bonne description de PR” produit des résultats variables. Le plus robuste est de placer le contrat de revue dans .github/pull_request_template.md. GitHub peut afficher automatiquement ce contenu dans le corps de la PR, ce qui transforme une habitude orale en règle visible dans le dépôt.

## Ce qui change
<!-- Séparer implémentation, configuration, documentation et fichiers générés. -->

## Pourquoi ce changement est nécessaire
<!-- Lier issue, incident, demande utilisateur ou décision de conception. -->

## Points de revue
- [ ] Logique métier
- [ ] UI/UX
- [ ] Contrat API ou base de données
- [ ] Sécurité et confidentialité

## Preuves de test
- [ ] Tests automatisés:
- [ ] Vérification manuelle:
- [ ] Captures ou vidéo:

## Taille du diff
- Fichiers modifiés:
- Lignes ajoutées/supprimées:
- Pourquoi la PR n'a pas été découpée:

## Sécurité et exploitation
- [ ] Aucun secret, token ou donnée personnelle
- [ ] Les logs n'exposent ni identifiants ni données personnelles
- [ ] Permissions, variables d'environnement et feature flags vérifiés
- [ ] Plan de rollback écrit

## Handoff pour les relecteurs
<!-- Fichiers à lire d'abord, décisions ouvertes, risques et PR suivantes. -->

Les champs les plus révélateurs sont “pourquoi la PR n’a pas été découpée” et “plan de rollback”. S’ils restent vides, la PR est souvent trop large ou mal préparée pour la production. Claude Code peut remplir la structure, mais la structure définit le niveau attendu.

Générer le corps de PR à partir de faits

Une fois le modèle en place, Claude Code doit le remplir à partir du diff. Le prompt doit interdire les affirmations non vérifiées. Si les tests n’ont pas été exécutés, la bonne réponse est “non exécuté”, pas une phrase rassurante.

git diff origin/main...HEAD | claude -p "
Lis ce diff et rédige le corps de la Pull Request avec .github/pull_request_template.md.

Règles:
- N'invente aucun fait absent du diff
- Si les preuves de test manquent, écris 'non exécuté'
- Explique les termes techniques à leur première apparition
- Limite le focus de revue aux 3 fichiers ou zones les plus importants
- Vérifie secrets, tokens, données personnelles et logs risqués
- Termine par les points qu'une personne doit confirmer
"

Ce format transforme la description en carte de lecture. Le relecteur sait s’il doit commencer par la fonction d’autorisation, l’écran modifié ou le fichier de migration. Claude Code lit vite, mais la responsabilité finale des faits reste humaine.

Bloquer les PR trop grandes en CI

Les grosses PR diminuent la qualité de revue. Claude Code peut renommer, reformater, refactorer, ajouter des tests et documenter dans la même session. C’est utile, mais cela mélange les intentions. Un diff-size budget rend la limite explicite.

Dans un projet Node, ajoutez scripts/check-pr-size.mjs. Le script ignore les lockfiles et les sorties générées, puis compte ce que les relecteurs doivent vraiment inspecter.

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

const [range = "origin/main...HEAD", maxLinesRaw = "700", maxFilesRaw = "35"] =
  process.argv.slice(2);
const maxLines = Number(maxLinesRaw);
const maxFiles = Number(maxFilesRaw);

const ignored = [
  /^package-lock\.json$/,
  /^pnpm-lock\.yaml$/,
  /^yarn\.lock$/,
  /^dist\//,
  /^coverage\//,
];

function numeric(value) {
  const parsed = Number(value);
  return Number.isFinite(parsed) ? parsed : 0;
}

const output = execFileSync("git", ["diff", "--numstat", range], {
  encoding: "utf8",
}).trim();

let files = 0;
let lines = 0;

for (const row of output.split(/\r?\n/).filter(Boolean)) {
  const [added, deleted, file] = row.split("\t");
  if (ignored.some((pattern) => pattern.test(file))) continue;
  files += 1;
  lines += numeric(added) + numeric(deleted);
}

if (files > maxFiles || lines > maxLines) {
  console.error(
    `PR is too large: ${files} files / ${lines} changed lines. ` +
      `Budget is ${maxFiles} files / ${maxLines} lines.`,
  );
  console.error("Split formatting, generated files, and behavior changes into separate PRs.");
  process.exit(1);
}

console.log(`PR size OK: ${files} files / ${lines} changed lines.`);

Ajoutez ensuite le workflow GitHub Actions. Les workflows sont stockés dans .github/workflows; vous pourrez ensuite rendre ce job obligatoire sur une branche protégée.

name: PR quality

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

permissions:
  contents: read
  pull-requests: read

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

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

      - name: Install dependencies
        run: npm ci

      - name: Run project checks
        run: |
          npm run lint --if-present
          npm test --if-present

      - name: Enforce PR size budget
        run: node scripts/check-pr-size.mjs "origin/${{ github.base_ref }}...HEAD" 700 35

Les chiffres sont à adapter. Je commence souvent à 700 lignes et 35 fichiers, avec une exception documentée pour les migrations ou refactorings mécaniques. Le but n’est pas d’interdire une grande PR, mais de forcer son explication.

Rendre les preuves de test reproductibles

“Tests OK” ne suffit pas. Le corps de PR doit contenir commandes, résultats, vérifications manuelles, captures pour l’UI et éléments non vérifiés. Claude Code peut mettre en forme cette section, mais il ne doit jamais marquer comme réussi un test non exécuté.

claude -p "
Prépare la section preuves de test pour la Pull Request de cette branche.

Format:
## Tests automatisés
- Commande:
- Résultat:
- Cause d'échec, le cas échéant:

## Vérification manuelle
- Écran, API ou job vérifié:
- Données d'entrée:
- Résultat attendu:
- Résultat réel:

## Non vérifié
- Points encore non vérifiés:
- Qui doit les vérifier avant merge:

N'écris que des faits. Ne marque pas une commande non exécutée comme réussie.
"

Trois cas reviennent souvent. Une PR UI doit montrer captures, largeurs d’écran et accessibilité. Une PR API doit préciser compatibilité, réponses d’erreur et logs. Une migration ou un batch doit fournir dry run, rollback et estimation de durée. Cette distinction rend la revue plus rapide.

Ajouter un passage sécurité et confidentialité

Le code assisté par IA peut modifier plus de fichiers que prévu. Un secret peut apparaître dans un exemple, un log, une fixture ou une capture. Les secrets GitHub Actions servent aux workflows, mais ils ne doivent pas être imprimés dans les logs ni copiés dans une PR.

Relis ce diff sous l'angle sécurité et confidentialité.

Checklist:
1. Secrets, tokens, API keys, cookies et session IDs
2. Données personnelles dans logs, fixtures, captures ou erreurs
3. Contrôles de permission appliqués côté serveur, pas seulement dans l'UI
4. Permissions GitHub Actions trop larges
5. Réponses d'erreur exposant chemins internes ou identifiants
6. Feature flags ou variables d'environnement modifiant le rollout

Retourne une sévérité High/Medium/Low et les fichiers concernés.
Ajoute aussi les zones suspectes que tu ne peux pas confirmer.

La dernière demande est volontaire. En sécurité, une zone incertaine clairement nommée vaut mieux qu’un “rien à signaler” trop rapide.

Préparer handoff et réponses de review

Un handoff évite au prochain relecteur de reconstruire le contexte. C’est précieux pour les équipes distribuées, les PR longues et les rotations. Donnez à Claude Code les commentaires et le résumé du diff.

PR_NUMBER=123
{
  gh pr view "$PR_NUMBER" --comments
  gh pr diff "$PR_NUMBER" --stat
} | claude -p "
Rédige une note de handoff pour les relecteurs de cette Pull Request.

Inclure:
- Objectif en deux phrases maximum
- Jusqu'à 3 fichiers à lire en premier
- Commentaires déjà traités
- Commentaires encore en attente de décision
- Risques CI, tests manuels et release

La note doit être lisible en moins de cinq minutes.
"

La même rigueur vaut pour les réponses de review. “Corrigé” est rarement suffisant. Une bonne réponse dit ce qui a changé, où, quel test le couvre et pourquoi une suggestion n’a pas été appliquée. Claude Code peut faire le brouillon; vous coupez ce qui est défensif ou spéculatif.

Transformer les PR fusionnées en notes de version

Une PR bien écrite facilite la release. Si le corps de PR ne peut pas devenir une note compréhensible par un utilisateur, l’impact était probablement mal expliqué. Conventional Commits aide à classer, mais les notes de version doivent rester lisibles.

gh pr list --state merged --base main --limit 20 \
  --json number,title,body,mergedAt \
  | claude -p "
Rédige un brouillon de notes de version à partir de ces Pull Requests fusionnées.

Sections:
## Nouvelles fonctionnalités
## Corrections
## Performance
## Documentation
## Changements développeurs

Règles:
- Conserver les numéros de PR
- Résumer les changements internes
- Mettre en avant breaking changes, migrations et feature flags
- Ne pas inventer d'impact absent du corps des PR
"

Ce travail ferme la boucle. Les auteurs apprennent à écrire des PR qui servent à la revue, au support et à la communication de release.

Éviter les PR IA bruyantes

Le piège principal est le bruit. Formatage non demandé, renommages larges, refactorings spéculatifs, commentaires redondants, prose trop marketing et tests non vérifiés ralentissent la revue.

Quelques règles suffisent souvent. Séparez le formatage. Gardez le diff généré aussi petit que possible. N’écrivez que des faits dans le corps de PR. Expliquez pourquoi une suggestion de Claude Code a été retenue. Séparez changements mécaniques, changements de comportement et tests quand c’est possible.

PR bruyante	PR relisible
”Claude a amélioré le module"	"Contrôles d’autorisation déplacés vers server/auth.ts”
Formatage et logique mélangés	PR de formatage séparée de la PR fonctionnelle
”Tout va bien” sans preuve	Commandes, résultats et manques listés
Pas de focus de revue	Fichiers et risques nommés au début

L’intégrer à une offre ClaudeCodeLab

Ce sujet mène naturellement vers modèles, formation et accompagnement. Une équipe n’a pas seulement besoin d’un prompt; elle a besoin d’un modèle de PR, de règles CLAUDE.md, de gates CI et de rituels de revue. Reliez l’article aux modèles CLAUDE.md, aux règles de handoff d’équipe et à la formation ou consultation.

Déployez par étapes. Semaine 1: modèle de PR. Semaine 2: limite de diff. Semaine 3: handoff de revue. Semaine 4: notes de version depuis les PR fusionnées. Trop de règles d’un coup feront rejeter le processus avant d’améliorer la qualité.

Résultat testé

J’ai testé ce flux sur un petit projet Node. La combinaison modèle de PR et limite de taille a eu le plus d’effet. Claude Code seul produisait un texte long mais irrégulier; le modèle a forcé l’apparition des tests non exécutés, des vérifications sécurité, des fichiers prioritaires et du rollback. Le budget 700 lignes et 35 fichiers a aussi aidé à séparer formatage et changement de comportement avant la demande de revue.

Résumé

Claude Code améliore la qualité des Pull Requests quand vous lui donnez des garde-fous: modèle strict, budget de diff en CI, preuves de test reproductibles, checklist sécurité et confidentialité, handoff de revue et notes de version. L’objectif n’est pas une PR plus élégante, mais une PR que les humains peuvent relire, vérifier et livrer.