Le problème

Prenons une boutique en ligne en monorepo : quatre services Symfony (order, stock, shipping, billing) et le front Vue.js shop, servi par Caddy. Un SDK TypeScript est généré depuis l'OpenAPI de order.

Une pull request annonce un refactoring : la configuration commune aux quatre services part dans un bundle partagé, app/config. Chaque service n'en garde que ses différences. Le diff touche plusieurs dizaines de fichiers, et la description affirme « Comportement inchangé, les tests passent ».

Relire ne permet pas de le vérifier, pour trois raisons.

Le résultat ne se lit pas dans le diff. Symfony fusionne la configuration importée avec celle du service, et les règles de fusion varient d'une option à l'autre. Savoir si order garde son pool de cache de production demande de rejouer cette fusion de tête, quatre fois.

Les tests ne voient pas tout. Ils tournent dans l'environnement test. Un réglage propre à prod, perdu dans la fusion, ne fait échouer aucun test.

La description est une affirmation, pas une preuve. Quand un agent de code écrit la PR, sa prose a la même assurance, que la vérification ait eu lieu ou non. Le relecteur ne peut pas juger un « comportement inchangé » ; il peut rejouer une commande.

Le même problème revient avec un Caddyfile découpé en fragments, ou un SDK régénéré. Par définition, un refactoring ne change pas le comportement externe : c'est une propriété qui se vérifie, à condition de choisir quoi comparer.

Les options

Relire le diff ligne à ligne

  • Ce qu'elle règle : le relecteur juge les noms, la lisibilité et l'intention, sans outil à écrire.
  • Ce qu'elle coûte : un effort qui suit la taille du diff, pour un résultat qui ne s'y lit pas : configuration fusionnée, fichiers importés, code généré. Les pratiques de revue de Google conseillent déjà d'isoler les refactorings des autres changements.

S'appuyer sur la suite de tests

  • Ce qu'elle règle : elle existe déjà, tourne en CI et vérifie les comportements qui comptent.
  • Ce qu'elle coûte : une suite verte dit que rien de testé n'a cassé, pas que rien n'a changé. La configuration de production, un Caddyfile ou un Dockerfile sont rarement couverts.

Des tests de snapshot

  • Ce qu'ils règlent : une sortie de référence est commitée, puis comparée à chaque exécution (toMatchFileSnapshot de Vitest, spatie/phpunit-snapshot-assertions en PHP). La garde est permanente.
  • Ce qu'ils coûtent : des références à maintenir, et vitest -u accepte n'importe quel écart si personne ne relit. C'est un dispositif durable pour une question ponctuelle.

Une preuve d'équivalence par refactoring

  • Ce qu'elle règle : on capture ce que le système consomme, avant et après, et on compare. Le diff est vide, ou chaque écart est expliqué. Le relecteur rejoue la commande.
  • Ce qu'elle coûte : un script jetable, et une capture de la base à reconstruire. La preuve ne couvre que ce qu'elle compare.

Notre recommandation

Chaque PR de refactoring porte une preuve d'équivalence rejouable : une capture avant, une après, leur diff, et ce que la preuve ne couvre pas.

La capture porte sur ce que le système consomme, pas sur les sources. Le conteneur Symfony compilé, le JSON que Caddy exécute et le code généré sont les vrais produits d'un fichier de configuration. Deux sources qui produisent le même artefact sont équivalentes pour le système.

Ce que l'on refactore Ce que l'on compare Commande
Configuration Symfony mise en commun configuration résolue, routes, services debug:config, debug:router, debug:container
Caddyfile découpé en fragments JSON adapté caddy adapt --pretty
Configuration ou générateur d'un SDK code généré régénération, puis git status --porcelain
Tâches moon héritées tâches résolues moon task <cible> --json
Reformatage, montée de dépendances baseline PHPStan, formateur total des count, php-cs-fixer check

Le relecteur vérifie une preuve rejouable, pas la prose de la PR Commit de base git merge-base Branche du refactoring HEAD Capture « avant » artefact consommé Capture « après » artefact consommé même script, mêmes variables Écarts expliqués Comparaison diff -ru Identique commande et résultat Écart inattendu retour au code Description de la pull request Pourquoi le besoin Quoi ce qui change et ce qui reste Vérification commandes rejouables et leurs résultats Non vérifié les angles morts de la preuve Le relecteur rejoue les commandes, lit le diff qui n'est pas mécanique, juge la liste « Non vérifié »

Pour une PR écrite par un agent de code, la règle change la relecture. Le relecteur ne juge plus la prose : il rejoue une commande et lit un diff. Une sortie collée dans la description peut être fausse ou périmée ; une commande rejouée ne l'est pas.

La section « Non vérifié » complète la preuve. Elle dit ce qu'aucune commande n'a couvert : l'application cliquée contre une API en marche, une construction multi-plateforme, l'intégration dans un éditeur. Une section vide sans justification devient une question de revue.

Les compromis assumés

Comme toute recommandation, celle-ci a un prix.

Une preuve ne couvre que ce qu'elle compare. Un JSON adapté depuis le dépôt ne dit rien des fichiers que l'image copie réellement, ni des variables de production. debug:container compare des définitions de services, pas leur code. La section « Non vérifié » nomme ces angles morts.

Un script jetable à écrire. Il est parfois plus long que le changement lui-même. Les recettes ci-dessous en donnent la trame, et il voyage dans la description, pas dans le dépôt.

Elle ne remplace pas les tests. La preuve dit ce qui a changé, les tests disent si ce qui compte marche. Une configuration identique avant et après peut être fausse des deux côtés.

Un écart doit être jugé. Un diff non vide n'est pas forcément un échec : deux sites Caddy aux hôtes disjoints peuvent changer d'ordre sans effet. Le coût de la revue passe de la lecture au jugement d'une explication.

Le signal qui doit faire réexaminer ce choix : la même preuve réécrite d'une PR à l'autre. Elle mérite alors une place permanente, en test de snapshot ou en contrôle de dérive en CI. Autre signal : une régression passée malgré une preuve verte, qui comparait donc le mauvais artefact.

Mise en œuvre

Les exemples visent Symfony 7.4 LTS et 8.1, Caddy 2.11 et GitHub.

1. Un gabarit de description

GitHub préremplit le corps de chaque pull request avec .github/pull_request_template.md.

<!-- .github/pull_request_template.md -->

## Pourquoi

<!-- Le besoin, en deux ou trois phrases. -->

## Quoi

<!-- Ce qui change, ce qui ne change pas. Les commits mécaniques à part. -->

## Vérification

<!-- Pour chaque preuve : la commande exacte, ce qu'elle compare, son résultat. -->

## Non vérifié

<!-- Ce qu'aucune commande n'a couvert, et pourquoi. -->

Pour la mise en commun de la configuration, la description donne par exemple :

## Vérification

- Script de capture (bloc replié ci-dessous) sur la base et sur la branche,
  en dev, test et prod, pour `order` et `stock` : `diff -ru` vide.
- Baseline PHPStan au même total ; `php-cs-fixer check` sort en 0.

## Non vérifié

- `shipping` et `billing` : même import, capture non lancée.

Le script jetable va dans un bloc <details> replié de la description. Le relecteur peut le rejouer, et le dépôt n'en garde rien.

2. Recette : une configuration Symfony mise en commun

Le script capture, par environnement, la configuration résolue des extensions, les routes, les services et les paramètres. Il se lance là où tourne bin/console, avec jq.

#!/usr/bin/env bash
# snapshot-symfony.sh : jetable, joint à la description de la PR
# Usage : snapshot-symfony.sh <dossier de sortie absolu>
set -euo pipefail

out="$1"
extensions=(framework doctrine doctrine_migrations security api_platform monolog)

# jq -S trie les clés ; le chemin du checkout diffère d'une capture à l'autre
snap() {
  local file="$1"
  shift
  php bin/console "$@" --format=json | jq -S . | sed "s#$PWD#<projet>#g" > "$out/$file"
}

for env in dev test prod; do
  mkdir -p "$out/$env"
  for ext in "${extensions[@]}"; do
    snap "$env/config-$ext.json" debug:config "$ext" --env="$env"
  done
  snap "$env/routes.json" debug:router --env="$env"
  snap "$env/services.json" debug:container --env="$env"
  # --show-hidden ne liste que les services dont l'id commence par un point
  snap "$env/services-hidden.json" debug:container --show-hidden --env="$env"
  snap "$env/parameters.json" debug:container --parameters --env="$env"
done

La base est le commit d'où part la branche, pas la pointe de main : sinon, le diff mêle les changements fusionnés entre-temps.

# Base dans un worktree à part, branche dans le checkout courant
git worktree add ../base "$(git merge-base HEAD origin/main)"
(cd ../base/services/order && composer install --quiet && ~/snapshot-symfony.sh /tmp/order-before)
(cd services/order && ~/snapshot-symfony.sh /tmp/order-after)
diff -ru /tmp/order-before /tmp/order-after

Sans --resolve-env, debug:config laisse les variables d'environnement en placeholders : ni leurs valeurs ni le .env du poste n'entrent dans la comparaison. Hors mode debug, comme en prod, debug:container recompile le conteneur à chaque appel, sans dépendre d'un cache périmé.

Le script échoue bruyamment, et c'est voulu : deux captures vides donnent un diff vide. Les identifiants hachés, comme .service_locator.<hash>, dérivent de leur contenu : leur écart s'explique par une autre ligne du même diff.

3. Recette : un Caddyfile découpé en fragments

Le front est servi par l'image officielle de Caddy, et son Caddyfile devient un fichier partagé complété de fragments importés. Nous adaptons la configuration dans l'image de chaque révision, pour inclure ce que le Dockerfile copie réellement.

# Le JSON que Caddy exécute, adapté dans l'image de chaque révision
docker build -t shop:before ../base/fronts/shop
docker build -t shop:after fronts/shop
for rev in before after; do
  docker run --rm --env-file fronts/shop/caddy.env.example "shop:$rev" \
    caddy adapt --config /etc/caddy/Caddyfile --pretty > "/tmp/caddy-$rev.json"
done
diff -u /tmp/caddy-before.json /tmp/caddy-after.json

Les variables {$VAR} sont remplacées avant l'analyse du Caddyfile, avec l'environnement de la commande : les deux captures reçoivent donc le même fichier d'exemple. Les placeholders {env.VAR}, résolus à l'exécution, restent tels quels dans le JSON.

Un écart courant vient de l'ordre des sites : quand deux blocs changent de place, leurs routes peuvent s'inverser. Les noms générés de leurs journaux (log0, log1) suivent aussi cet ordre. Avec des hôtes disjoints, l'écart est sans effet : la description le dit.

4. Recette : un SDK régénéré

Quand la configuration du générateur part dans un package commun, le code généré ne doit pas bouger d'un octet.

# Régénérer avec la configuration commune, puis exiger un dossier inchangé
moon run order-api-sdk:generate-api
changes=$(git status --porcelain -- libs/typescript/order-api-sdk/generated)
[ -z "$changes" ] || { echo "$changes"; exit 1; }

git diff --exit-code ignore les fichiers non suivis : un fichier généré en plus passerait inaperçu. git status --porcelain les liste.

Changer de générateur, passer d'openapi-typescript à @hey-api/openapi-ts par exemple, change la sortie par construction. La preuve porte alors sur l'entrée : l'ancien générateur, relancé sur la spécification commitée, reproduit l'ancien code à l'octet. Le contrat n'a donc pas bougé, et la vérification de types des fronts couvre les appels.

5. Deux garde-fous : la baseline PHPStan et le formateur

Une baseline PHPStan enregistre chaque erreur acceptée avec un count. Un refactoring ne doit pas en faire monter le total.

# Total des erreurs de la baseline, sur la base puis sur la branche
total() { grep -E '^[[:space:]]+count: [0-9]+$' | awk '{ s += $2 } END { print s + 0 }'; }
git show "$(git merge-base HEAD origin/main):services/order/phpstan-baseline.neon" | total
total < services/order/phpstan-baseline.neon

Un total égal n'exclut pas un échange : une erreur corrigée, une autre ajoutée. Si aucun fichier ne bouge, la preuve stricte est un diff vide de la baseline.

php-cs-fixer check sort en 8 quand des fichiers restent à corriger, en 0 sinon. Le reformatage a son propre commit, qui se prouve en le rejouant : sur son parent, php-cs-fixer fix produit exactement ce commit.

6. L'exiger d'un agent de code

AGENTS.md, à la racine du dépôt, est lu par Codex, Cursor ou l'agent de code de GitHub Copilot. Claude Code lit CLAUDE.md : une ligne @AGENTS.md l'y importe.

<!-- AGENTS.md (extrait) -->

## Pull requests de refactoring

- Avant de modifier, capturez ce que le système consomme : configuration résolue
  (`debug:config`, `debug:router`, `debug:container`), JSON adapté de Caddy,
  code généré, tâches moon résolues (`moon task <cible> --json`).
- Après le changement, refaites la même capture, comparez avec `diff -ru`
  et expliquez chaque écart.
- Séparez les commits mécaniques (déplacement, reformatage) des autres.
- Suivez `.github/pull_request_template.md` : commandes exactes et résultats
  dans « Vérification », angles morts dans « Non vérifié ».

Ces fichiers restent du contexte, pas une contrainte. Un agent qui écrit lui-même le corps de la PR (gh pr create --body) peut aussi s'écarter du gabarit. Un job de CI vérifie donc la présence des sections.

# .github/workflows/pr-description.yml
name: pr-description

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

permissions: {}

jobs:
  sections:
    runs-on: ubuntu-latest
    steps:
      - name: Sections Vérification et Non vérifié
        env:
          BODY: ${{ github.event.pull_request.body }}
        run: |
          for section in '## Vérification' '## Non vérifié'; do
            grep -qF -- "$section" <<< "$BODY" || { echo "::error::Section absente : $section"; exit 1; }
          done

Le corps passe par une variable d'environnement, comme GitHub le recommande contre l'injection de script. Le job s'ajoute aux checks exigés sur main, à côté de la quality gate : séparé, il se relance quand la description change. Il vérifie la forme ; le fond reste au relecteur.

Checklist

  • Les refactorings isolés dans leur PR, ou dans leurs commits.
  • Une capture de l'artefact consommé, pas des sources, avant et après.
  • Le commit d'où part la branche comme base de comparaison.
  • Le même script, qui échoue bruyamment, et les mêmes variables pour les deux captures.
  • Un diff vide, ou chaque écart expliqué dans la description.
  • Une section « Non vérifié » remplie, ou justifiée si elle est vide.
  • Les tests toujours lancés : la preuve ne les remplace pas.
  • La règle dans AGENTS.md, importée par CLAUDE.md, et vérifiée en CI.

Sources

Versions relevées le 15 novembre 2026 : Symfony 7.4 LTS et 8.1, Caddy 2.11.9.