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
(
toMatchFileSnapshotde Vitest,spatie/phpunit-snapshot-assertionsen PHP). La garde est permanente. -
Ce qu'ils coûtent : des références à
maintenir, et
vitest -uaccepte 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
|
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 parCLAUDE.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.
- Martin Fowler, Refactoring : la définition du refactoring.
- Google, Small CLs : « Separate Out Refactorings ».
- Symfony, debug:config, debug:container, debug:router, recompilation hors mode debug et fusion de la configuration.
- Caddy, caddy adapt, variables d'environnement et noms des journaux.
- Git, git diff, git status et git worktree.
- PHPStan, The Baseline ; PHP-CS-Fixer, Usage (codes de sortie).
- moon, moon task.
- Vitest, Snapshot ; spatie/phpunit-snapshot-assertions.
- GitHub, modèle de pull request, sections repliées, gh pr create, événement pull_request et entrées non fiables.
- AGENTS.md ; Claude Code, CLAUDE.md et AGENTS.md.
- Lychen, pull request 243 et pull request 258 : un SDK régénéré et comparé à l'octet près, une mise en œuvre open source de ce que décrit cet article, dans un monorepo moon.
- Lychen, pull requests 245, 247, 250, 252 et 271 : des refactorings décrits avec leurs vérifications et ce qui n'a pas été vérifié, dans le même monorepo.