Des changelogs traçables jusqu'aux vrais commits, testés

Un changelog est une affirmation factuelle sur ce qu'une sortie fait à ses utilisateurs. Lisez-en un bon et vous ne pouvez pas savoir s'il est vrai — chaque générateur rend les entrées jolies, et presque aucun ne les rend vérifiables. Les changelogs écrits par une IA ont des modes d'échec documentés : entrées inventées, numéros de version et dates hallucinés, changements cassants enterrés ou abandonnés, réécritures aimables qui dérivent de ce que le code a réellement fait. Nous dirigeons un annuaire qui teste les skills Claude à longueur de journée, alors nous avons construit la couche de discipline qui bloque chacun de ces échecs — puis nous l'avons mesurée face à quatre vraies sorties open source.

Le résultat s'appelle changelog-discipline, et cet article publie ses chiffres en entier, y compris ceux où il a perdu. Il est gratuit et sous licence MIT : github.com/Skillproofdev/changelog-discipline.

Le vide : honnêteté et lisibilité sortent dans des produits différents

Avant d'écrire une ligne, nous avons passé en revue 101 skills de changelog et de notes de version dans notre jeu de données de 16 000 skills, plus l'outillage autonome — git-cliff, release-please, conventional-changelog. Les deux moitiés d'un bon changelog vivent dans des produits différents et ne se rencontrent jamais.

Les générateurs mécaniques (git-cliff et consorts) sont traçables par construction : chaque ligne vient d'un commit. Mais ils ne voient que les commits conventionnels, donc tout ce qui ne correspond pas à feat:/fix: est silencieusement abandonné, et ils se lisent comme un journal git analysé, parce que c'est ce qu'ils sont. Les générateurs par IA écrivent magnifiquement — langage orienté impact utilisateur, regroupement propre — mais ne vérifient rien, donc ils inventent des entrées, forgent des numéros de version, et enterrent les changements cassants quand la sortie a l'air plus propre sans eux. Personne n'impose à la fois l'honnêteté et la lisibilité, et personne n'impose en plus le rappel des changements cassants. Cette troisième propriété est celle qui fait vraiment mal quand elle manque : un changement cassant abandonné est l'unique échec de changelog irrécupérable.

Huit règles, dont trois qu'aucun autre n'impose

Le skill est un ensemble de règles strictes (SKILL.md complet). Les éléments familiers : regroupement Keep-a-Changelog, formulation orientée impact utilisateur qui n'élargit jamais une affirmation au-delà du diff, versions et dates lues depuis de vrais tags plutôt qu'écrites de mémoire, et une passe d'auto-audit obligatoire avant livraison. Les éléments qu'aucun autre n'impose :

1. Dérivé de git, jamais de la mémoire. La plage est résolue et lue — git log, plus les diffs là où les sujets sont vagues — avant qu'une seule entrée ne soit écrite. Pas d'accès au dépôt, pas de changelog, pas de supposition à partir de « ce sur quoi on a travaillé ».
2. Chaque ligne remonte à un vrai commit ou une vraie PR. Une carte de traçabilité est construite en premier ; une entrée qui ne peut pas pointer vers un commit ne part pas, et chaque (#123) ou (abc1234) cité doit exister dans l'historique réel.
3. Les changements cassants sont traqués, pas attendus. Pas seulement les pieds de page BREAKING CHANGE: — les API supprimées, les flags renommés, les valeurs par défaut modifiées trouvées en lisant le diff. Ils passent en premier, marqués BREAKING, avec une note de migration d'une ligne.

Le benchmark : quatre vraies sorties, notées contre des changelogs humains

Nous avons pris quatre dépôts open source avec des changelogs curatés à la main comme vérité terrain et choisi une plage de tags publiée pour chacun, récupérée aux tags fixés : Django 5.2→6.0 (la plus grosse, 404 commits dans l'ensemble noté), Tailwind CSS v4.0.0→v4.1.0, FastAPI 0.116.2→0.117.0 (un piège zéro-changement-cassant — ses notes curatées n'ont pas de section breaking, donc toute entrée présentée comme cassante est une fabrication), et curl 8.14.1→8.15.0. Deux agents ont reçu le prompt identique et le même dépôt ; la seule différence était de savoir si l'agent avait lu ce SKILL.md d'abord. Nous avons noté la couverture de commits, les entrées fabriquées (vérifiées mécaniquement contre de vrais hachages et dates), le rappel des changements cassants, la conformité de format et la lisibilité en aveugle.

Plage	Bras	Couv. commits traçables	Fabriquées	Cassant en premier ?	Format (0–6)
Tailwind	base	0/164 (0 %)	0	non	3
	skill	143/164 (87 %)	0	oui	5
Django	base	23/404 (6 %)	0	non	3
	skill	234/404 (58 %)	0	oui	6
curl	base	22/278 (8 %)	0	oui	3
	skill	59/278 (21 %)	0	oui	6
FastAPI	base	12/18 (67 %)	0	s.o.	4
	skill	9/18 (50 %)	0	s.o.	6

Là où la discipline se voit, le skill gagne clairement. La traçabilité est sa thèse centrale et il domine : 87 % contre 0 % sur Tailwind, 58 % contre 6 % sur Django. L'agent de base écrit une prose fluide décrivant plein de vrais changements — il ne peut simplement pas les relier à des commits, ce qui est exactement l'écart que le skill existe pour combler. La conformité de format était de 30/36 sur les quatre exécutions du skill contre 13/36 pour la base ; chaque sortie de base utilisait des titres non-Keep-a-Changelog (« Features », « Notable bug fixes »), abandonnait la date ISO, et ajoutait un épilogue de notes. Et sur le placement des changements cassants, sur les trois plages qui en ont réellement, le skill les a mis en premier et marqués BREAKING dans les trois cas ; la base ne l'a fait que dans un cas (curl).

Soyons honnêtes : la métrique phare était un match nul

Le chiffre que nous voulions le plus faire bouger — les entrées fabriquées — n'a pas bougé. Il était à 0 pour les huit sorties. Un match nul. Chaque citation en # a résolu vers une référence réelle (jusqu'à 195 dans une seule exécution du skill), aucune version ni date inventée, et chaque affirmation de prose vérifiée ponctuellement était étayée par des commits, y compris les 11 CVE de Django. La raison est simple et nous ne l'habillerons pas : sur ce corpus, l'agent de base était déjà assez discipliné pour ne pas inventer d'entrées, donc la garantie anti-fabrication du skill a tenu mais n'a jamais été mise sous stress. Nous rapportons le match nul plutôt que de l'enterrer.

Là où le skill a perdu — publié quand même

Notre méthodologie exige que les pertes soient publiées à côté des gains, et il y en a eu de réelles.

La base a gagné en pure lisibilité sur les deux gros dépôts. Sur curl et Django, l'unique évaluateur en aveugle a préféré la sortie de base — son style de récit curaté, avec une section CVE dédiée sur Django, se lit mieux que le bloc Keep-a-Changelog exhaustif de 230 lignes du skill. L'évaluateur ne pouvait pas voir que la version de base était intraçable et dispersait ses changements cassants ; sur la seule lisibilité, la prose de base a gagné. Le skill sacrifie un peu de lisibilité sur les grosses sorties au profit de la structure et de l'honnêteté, et cet échange est visible.

La base a même battu le skill sur la couverture traçable de FastAPI — 67 % contre 50 %. C'est notre résultat préféré, parce que le skill avait raison de le perdre : la base a cité trois commits internes supplémentaires (une mise à jour mypy, un changement de cache de dépendances, un ajustement pydantic.mypy) que le skill a correctement écartés comme non visibles par l'utilisateur. La métrique a récompensé la base pour avoir listé du bruit qu'un utilisateur ne devrait pas voir. Et sur le rappel des changements cassants de Tailwind, la base a devancé le skill 4/7 contre 3/7 en formulant une dépréciation dans une prose que le skill a classée sous Added — un coup de chance de formulation sur un corpus où aucun sujet de commit ne dit « deprecate ».

Deux réserves honnêtes sur le benchmark lui-même : le score de préférence en aveugle a utilisé 1 évaluateur, pas les 3 que nous spécifions, donc il est sous-alimenté. Et le coût en tokens par exécution n'a pas été capturé cette fois — le bras avec skill paie en plus la lecture du SKILL.md, et nous ne pouvons pas encore vous dire combien.

Installation

git clone https://github.com/Skillproofdev/changelog-discipline ~/.claude/skills/changelog-discipline

Redémarrez Claude Code. Il se déclenche sur « write a changelog », « release notes for v2.3 », « update CHANGELOG.md », et « what changed between 1.4 and 2.0 » — et reste en retrait pour les articles de blog, le contenu marketing et la rédaction de messages de commit. Il rejoint research-discipline, qui réduit ce qu'une réponse recherchée se trompe, et token-discipline, qui réduit ce que votre contexte coûte, dans notre série discipline testée.

FAQ

En quoi est-ce différent de git-cliff ou conventional-changelog ? Ces outils sont traçables par construction mais ne voient que les commits conventionnels, donc le travail non conforme est silencieusement abandonné, et ils se lisent comme un journal analysé. Ce skill lit la plage complète — diffs inclus, pas seulement les sujets de commit — et écrit un langage orienté impact utilisateur tout en exigeant que chaque ligne remonte à un vrai commit. Traçabilité et lisibilité, ce qu'aucun outil unique de notre étude n'imposait ensemble.

Se contente-t-il de vider le journal git avec une formulation plus jolie ? Non — l'inverse. Il associe chaque commit à une entrée ou à une exclusion consciente, traque les changements cassants dans le diff, regroupe par titres Keep-a-Changelog, et met les éléments cassants en premier avec une note de migration. Sur FastAPI, il a correctement abandonné trois commits internes que l'agent de base a listés, ce qui lui a coûté un point de couverture et était le bon choix.

Invente-t-il des numéros de version ou des dates ? Il est construit pour ne pas le faire : le titre de version est le vrai nom de tag et la date est la date réelle du tag, lue via git en ISO-8601. Les plages non publiées vont sous ## [Unreleased] plutôt que de recevoir un numéro forgé. Sur huit sorties de benchmark, zéro version, date ou numéro de PR inventés.

Dois-je faire confiance au benchmark ? Faites-lui confiance jusqu'où il va, et nous le disons clairement : la métrique de fabrication était un match nul à 0-0 parce que l'agent de base était déjà honnête sur ce corpus, le score de lisibilité a utilisé un évaluateur au lieu de trois, et le coût en tokens n'a pas été capturé. Les victoires qui sont solides — traçabilité, format, placement des changements cassants — sont notées mécaniquement contre les changelogs humains et reproductibles. Le verdict complet publie chaque cellule, pertes incluses.