Changelogs rastreables hasta commits reales, con benchmark

Un changelog es una afirmación fáctica sobre lo que un release le hace a sus usuarios. Lees uno bueno y no puedes saber si es verdad — todo generador hace las entradas bonitas, y casi ninguno las hace verificables. Los changelogs escritos por LLM tienen modos de fallo documentados: entradas inventadas, números de versión y fechas alucinados, cambios de ruptura enterrados o descartados, reescrituras amigables que se alejan de lo que el código realmente hizo. Dirigimos un directorio que testea skills de Claude con benchmarks para ganarnos la vida, así que construimos la capa de disciplina que bloquea cada uno de esos fallos — y luego la medimos contra cuatro releases reales de código abierto.

El resultado es changelog-discipline, y este post publica sus números al completo, incluidos aquellos en los que perdió. Es gratis y tiene licencia MIT: github.com/Skillproofdev/changelog-discipline.

La brecha: honestidad y legibilidad se venden en productos distintos

Antes de escribir una sola línea, revisamos 101 skills de changelog y notas de release en nuestro dataset de 16k skills, más las herramientas independientes — git-cliff, release-please, conventional-changelog. Las dos mitades de un buen changelog viven en productos distintos y nunca se solapan.

Los generadores mecánicos (git-cliff y similares) son rastreables por construcción: cada línea viene de un commit. Pero solo ven conventional commits, así que cualquier cosa que no coincida con feat:/fix: se descarta en silencio, y se leen como un git log parseado porque eso es exactamente lo que son. Los generadores LLM escriben con belleza — lenguaje de impacto para el usuario, agrupación limpia — pero no verifican nada, así que inventan entradas, acuñan números de versión, y entierran cambios de ruptura cuando el release se ve más limpio sin ellos. Nadie exige honestidad y legibilidad a la vez, y nadie exige encima el recall de cambios de ruptura. Esa tercera propiedad es la que de verdad duele cuando falta: un cambio de ruptura descartado es el único fallo de changelog irrecuperable.

Ocho reglas, tres que nadie más exige

La skill es un conjunto de reglas estrictas (SKILL.md completo). Las partes conocidas: agrupación al estilo Keep-a-Changelog, redacción de impacto para el usuario que nunca amplía una afirmación más allá del diff, versiones y fechas leídas de tags reales en vez de escritas de memoria, y una pasada obligatoria de autoauditoría antes de entregar. Las partes que nadie más exige:

1. Derivado de git, nunca de memoria. El rango se resuelve y se lee — git log, más diffs donde los asuntos son vagos — antes de escribir una sola entrada. Sin acceso al repo no hay changelog, no una suposición basada en "en qué trabajamos."
2. Cada línea se rastrea hasta un commit o PR real. Primero se construye un mapa de rastreo; una entrada que no puede señalar a un commit no se publica, y cada (#123) o (abc1234) citado debe existir en el historial real.
3. Los cambios de ruptura se cazan, no se esperan. No solo pies BREAKING CHANGE: — APIs eliminadas, flags renombrados, valores por defecto cambiados, encontrados leyendo el diff. Van primero, marcados como BREAKING, con una nota de migración de una línea.

El benchmark: cuatro releases reales, puntuados contra changelogs humanos

Tomamos cuatro repos de código abierto con changelogs curados a mano como ground truth y elegimos un rango de tags publicado para cada uno, obtenido en los tags fijados: Django 5.2→6.0 (el mayor, 404 commits en el conjunto puntuado), Tailwind CSS v4.0.0→v4.1.0, FastAPI 0.116.2→0.117.0 (una trampa de cero rupturas — sus notas curadas no tienen sección de ruptura, así que cualquier entrada presentada como ruptura es una invención), y curl 8.14.1→8.15.0. Dos agentes recibieron el prompt idéntico y el mismo repo; la única diferencia fue si la agente leyó este SKILL.md primero. Puntuamos cobertura de commits, entradas inventadas (verificadas mecánicamente contra hashes y fechas reales), recall de cambios de ruptura, cumplimiento de formato, y legibilidad ciega.

Rango	Brazo	Cobertura de commits rastreable	Inventadas	¿Ruptura primero?	Formato (0–6)
Tailwind	base	0/164 (0%)	0	no	3
	skill	143/164 (87%)	0	sí	5
Django	base	23/404 (6%)	0	no	3
	skill	234/404 (58%)	0	sí	6
curl	base	22/278 (8%)	0	sí	3
	skill	59/278 (21%)	0	sí	6
FastAPI	base	12/18 (67%)	0	n/a	4
	skill	9/18 (50%)	0	n/a	6

Donde se ve la disciplina, la skill gana con claridad. La rastreabilidad es su tesis central y domina: 87% frente a 0% en Tailwind, 58% frente a 6% en Django. El agente base escribe prosa fluida que describe montones de cambios reales — simplemente no puede rastrearlos hasta los commits, que es exactamente la brecha que la skill existe para cerrar. El cumplimiento de formato fue 30/36 en las cuatro ejecuciones de la skill frente a 13/36 del base; cada salida base usó encabezados que no seguían Keep-a-Changelog ("Features", "Notable bug fixes"), se dejó la fecha ISO, y añadió un epílogo de notas. Y en la colocación de cambios de ruptura, en los tres rangos que de verdad tienen cambios de ruptura, la skill los puso primero y los marcó BREAKING en los tres; el base lo hizo en uno solo (curl).

Con honestidad: la métrica del titular fue un empate

El único número que más queríamos mover — entradas inventadas — no se movió. Fue 0 en las ocho salidas. Un empate. Cada cita con # se resolvió a una referencia real (hasta 195 de ellas en una sola ejecución de la skill), sin versiones ni fechas inventadas, y cada afirmación de prosa comprobada al azar estaba respaldada por un commit, incluidos los 11 CVE de Django. La razón es simple y no la vamos a maquillar: en este corpus el agente base ya era lo bastante disciplinado como para no inventar entradas, así que la garantía contra invenciones de la skill se mantuvo pero nunca se puso a prueba de verdad. Reportamos el empate en vez de esconderlo.

Dónde perdió la skill — publicado de todas formas

Nuestra metodología exige mostrar las derrotas junto a las victorias, y las hubo reales.

El base ganó en legibilidad pura en los dos repos grandes. En curl y Django, la única evaluadora ciega prefirió la salida base — su estilo de narrativa curada, con una sección dedicada a CVE en Django, se lee mejor que el bloque exhaustivo de 230 líneas de Keep-a-Changelog de la skill. La evaluadora no podía ver que la versión base era inrastreable y dispersaba sus cambios de ruptura; solo en legibilidad, la prosa del base ganó. La skill sacrifica algo de legibilidad en releases enormes a cambio de estructura y honestidad, y ese intercambio se nota.

El base incluso superó a la skill en cobertura rastreable de FastAPI — 67% frente a 50%. Este es nuestro resultado favorito, porque la skill tenía razón al perderlo: el base citó tres commits internos extra (una subida de versión de mypy, un cambio de caché de dependencias, un ajuste de pydantic.mypy) que la skill correctamente descartó por no ser de cara al usuario. La métrica premió al base por listar cambios que un usuario no debería ver. Y en el recall de rupturas de Tailwind, el base superó a la skill 4/7 frente a 3/7 al frasear una deprecación en prosa que la skill archivó bajo Added — suerte de redacción en un corpus donde ningún asunto de commit dice "deprecate."

Dos matices honestos sobre el benchmark en sí: la puntuación de preferencia ciega usó 1 evaluadora, no las 3 que especificamos, así que está infradimensionada. Y el coste de tokens por ejecución no se capturó en esta ronda — el brazo con la skill además paga por leer el SKILL.md, y todavía no podemos decirte cuánto.

Instalación

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

Reinicia Claude Code. Se activa con "escribe un changelog", "notas de release para v2.3", "actualiza CHANGELOG.md", y "qué cambió entre 1.4 y 2.0" — y se mantiene al margen de posts de blog, copy de marketing, y la redacción de mensajes de commit. Se suma a research-discipline, que recorta lo que una respuesta investigada se equivoca, y token-discipline, que recorta lo que tu contexto cuesta, en nuestra serie de disciplina con benchmark.

Preguntas frecuentes

¿En qué se diferencia de git-cliff o conventional-changelog? Esas herramientas son rastreables por construcción pero solo ven conventional commits, así que el trabajo no conforme se descarta en silencio, y se leen como un log parseado. Esta skill lee el rango completo — diffs incluidos, no solo los asuntos de los commits — y escribe lenguaje de impacto para el usuario mientras exige que cada línea se rastree hasta un commit real. Rastreabilidad y legibilidad, algo que ninguna herramienta de nuestra revisión exigía a la vez.

¿Solo vuelca el git log con palabras más bonitas? No — todo lo contrario. Mapea cada commit a una entrada o a una exclusión consciente, caza cambios de ruptura en el diff, agrupa por encabezados de Keep-a-Changelog, y pone los elementos de ruptura primero con una nota de migración. En FastAPI descartó correctamente tres commits internos que el agente base sí listó, lo que le costó un punto de cobertura y fue la decisión correcta.

¿Inventa números de versión o fechas? Está construida para no hacerlo: el encabezado de versión es el nombre real del tag y la fecha es la fecha real del tag, leída vía git en ISO-8601. Los rangos sin publicar van bajo ## [Unreleased] en vez de recibir un número acuñado. En las ocho salidas del benchmark, cero versiones, fechas o números de PR inventados.

¿Debería fiarme del benchmark? Fíate hasta donde llega, que decimos con claridad: la métrica de invenciones fue un empate 0–0 porque el agente base ya era honesto en este corpus, la puntuación de legibilidad usó una evaluadora en vez de tres, y el coste de tokens no se capturó. Las victorias que sí son sólidas — rastreabilidad, formato, colocación de cambios de ruptura — están puntuadas mecánicamente contra los changelogs humanos y son reproducibles. El veredicto completo publica cada celda, derrotas incluidas.