El mensaje de commit que coincide con el diff: benchmark

Un mensaje de commit es una afirmación sobre un diff. "add rate limiting to login" dice que el diff añadió limitación de tasa al login — y o bien lo hizo, o también tocó otros tres archivos que el mensaje nunca menciona, o "mejora el rendimiento" sin que nadie lo haya medido. No puedes saber cuál por leer el mensaje. Tienes que leer el diff, y casi nadie lo hace. Dirigimos un directorio que testea skills de Claude con benchmarks para ganarnos la vida, así que hicimos lo aburrido: pusimos a Claude a escribir mensajes de commit para 15 diffs reales de código abierto, dos veces cada uno, y comprobamos cada mensaje contra los cambios realmente staged.

El resultado es commit-discipline, y llega con los números de antes/después adjuntos: la cobertura del diff pasó de 83% a 97%, los asuntos entraron en 50 caracteres en 15 de 15 diffs (frente a 6 de 15), y las afirmaciones inventadas bajaron de 1 a 0. Es gratis y tiene licencia MIT: github.com/Skillproofdev/commit-discipline.

La brecha: todos comprueban el formato, nadie comprueba la verdad

Antes de escribir una sola línea, revisamos 80 skills centradas en commits dentro de nuestro índice de 16.682 skills, más las skills de commits independientes publicadas para Claude Code. La capa de formato es un espacio saturado y resuelto. El cumplimiento de Conventional Commits es universal. Modo imperativo, asuntos de 50 caracteres, pies BREAKING CHANGE: — comunes, bien documentados, lo mínimo esperable. Si lo único que quieres es un type(scope): subject bien formado, docenas de skills ya lo hacen.

Lo que ninguna exige es la capa de debajo: si el mensaje es verdadero respecto al diff. ¿Da cuenta de cada cambio lógico que está staged? ¿No inventa nada — sin motivo adivinado, sin "mejora el rendimiento" sin medir, sin describir un cambio que en realidad no está ahí? Esa es la capa de honestidad, y estaba libre de competencia en el terreno. Cada competidor o ejecuta git diff --cached como una sugerencia no exigida, o directamente trabaja a partir de listas de archivos — nombres de archivo, que te dicen dónde cambió algo pero nunca qué ni por qué. commit-discipline convierte en Regla 1 leer el diff completo y prohíbe de raíz el atajo de los nombres de archivo.

Ocho reglas, cuatro que nadie más codifica

La skill es un conjunto de reglas estrictas (SKILL.md completo). Las partes conocidas se aplican con rigor: un tipo ganado por lo que el diff le hace al comportamiento, un scope que debe poder derivarse de las rutas (nunca inventado), un asunto imperativo de ≤50 caracteres, cambios de ruptura en un pie. Las partes que nadie más exige:

1. Completitud de cobertura del diff. Después de redactar, recorre el diff contra el mensaje: cada cambio lógico contabilizado, nada descrito que no esté staged. Control de alucinaciones para mensajes de commit.
2. Lee el diff staged completo, nunca los nombres de archivo. Regla 1, con el atajo prohibido. El mensaje describe el diff, así que el diff — todo él — es la entrada.
3. Una lista concreta de vaguedades prohibidas. update, fix stuff, improve, misc, cleanup sin objeto, wip, address feedback — bloqueadas como palabras que no pueden sostener el mensaje, cada una con un patrón de reemplazo (update deps → bump axios 1.6→1.7).
4. Un contrato de salida. El entregable es solo el mensaje en un bloque de código — sin preámbulo, sin narración del diff paso a paso, sin un pie Co-Authored-By sorpresa.

A eso se suma un cuerpo que explica por qué e impacto en vez de repetir el diff (con una prueba de eliminación: si una línea se puede reconstruir leyendo el diff, se corta), y una recomendación de división para diffs de varios asuntos — límites de archivo concretos y un asunto borrador por commit — en vez de un mensaje paraguas que tapa dos cambios distintos.

El benchmark: 15 diffs reales, mensajes originales eliminados

Sacamos 15 fixtures de curl, redis, express, fastapi, eslint, django, rust-analyzer y astro en SHAs fijados: funcionalidades, corrección de bugs, refactors, dos cambios de ruptura genuinos, dos diffs de varios asuntos plantados, tareas de docs y CI, y commits de más de 400 líneas con muchos archivos. Cada diff fue a dos agentes Claude Sonnet con prompts idénticos. La única diferencia: uno leyó este SKILL.md primero, el otro no. Puntuamos de tres formas — cumplimiento mecánico de Conventional Commits por script, cobertura del diff contra una lista de cambios de referencia preregistrada, y juicio ciego de preferencia A/B.

Métrica	Baseline	Con la skill
Cumplimiento de spec (7 comprobaciones mecánicas, media)	91.4%	98.1%
— asunto ≤ 50 caracteres	40% (6/15)	100% (15/15)
Cobertura de diff (vs listas de cambio de referencia, media)	83.2%	96.7%
Afirmaciones inventadas (total en 15)	1	0
Recall de cambios de ruptura (2 fixtures)	2/2	2/2
Detección de división (2 diffs de varios asuntos plantados)	0/2	2/2
Preferencia ciega A/B (skill vs baseline)	—	9 victorias / 4 derrotas / 2 empates

Dos cosas destacan. Primero, el cumplimiento mecánico ya era fuerte en el baseline — tipos correctos, modo imperativo, pies de ruptura y verbos no vagos salían de fábrica. Toda la brecha de formato estaba en la extensión del asunto: el baseline se pasaba de 50 caracteres en 9 de 15 diffs; la skill nunca. Segundo, la verdadera separación está en la cobertura. El baseline se dejaba habitualmente cambios secundarios — los tests añadidos, la entrada del changelog, el segundo asunto escondido en un diff "único" — mientras que la skill los contabilizaba. Ese salto de 83% a 97% es de donde vino la mayoría de las victorias de preferencia, y es lo que ningún verificador de formato te puede dar.

La detección de división es el ejemplo más claro. En los dos diffs de varios asuntos plantados (t05, t12), el baseline escribió un mensaje paraguas en cada uno; la skill propuso la división las dos veces. En t07 — un commit de curl que elimina TLS-SRP — la skill incluso captó un hunk de seis setopt sin relación que el baseline absorbió en silencio dentro de su mensaje, que fue la única invención del baseline en toda la ejecución: una justificación de eliminación inventada ("prácticamente sin uso") que el diff no respaldaba. La skill marcó ese hunk como una pregunta para el usuario en vez de adivinar.

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

Nuestra metodología exige mostrar las derrotas junto a las victorias, y esto no fue un barrido limpio.

El baseline superó a la skill en tres fixtures. En t03 (redis), t13 (rust-analyzer) y t15 (fastapi) — todos diffs de alcance ajustado — el baseline captó un detalle concreto que la skill pasó por alto: un límite de trait &mut dyn SourceDatabase ampliado (t13), una extracción de deduplicación _build_dependant (t15), y uno de dos algoritmos de conteo de diffs (t03). La presión de completitud de la skill es real pero no absoluta; en diffs pequeños de un solo archivo el baseline iguala o supera a la skill.

La disciplina de división de la skill se disparó de más una vez. En t14 dividió un commit de dos líneas de CI-más-dependencia — añadir Node 26 a la matriz, subir de versión mocha — en dos, defendible según la letra de "un commit, un asunto" pero algo que la mayoría de revisores mantendría como un único commit ci:. Tres divisiones correctas, una división de más. Contado como una derrota de preferencia y señalado.

Y el matiz más importante: n=15 es directional, no estadísticamente significativo, y el juicio de cobertura y preferencia lo hizo un juez de la misma familia de modelo — no se configuró en la máquina de pruebas un juez de clase GPT de otra familia. La preferencia en particular conlleva riesgo de autopreferencia: quien escribe y quien juzga comparten familia de modelo. Barajamos las etiquetas con una semilla preregistrada y las descegamos después de puntuar, pero no vamos a fingir que un recuento de preferencia de 9-4-2 de un juez de la misma familia es un veredicto. Es una señal. El protocolo completo, las puntuaciones por fixture y la divulgación del método de juicio están en bench/results/verdict.md.

Instalación

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

Reinicia Claude Code. Se activa con "haz commit de esto," "escribe un mensaje de commit," al hacer commit de cambios staged, y en peticiones de revisión o limpieza de mensajes — y se mantiene al margen de las operaciones de git que no son sobre mensajes: crear ramas, rebasar, resolver conflictos. Se suma a nuestra serie de disciplina junto a token-discipline, que recorta lo que cuesta una sesión, y research-discipline, que recorta lo que una respuesta se equivoca. Esta recorta lo que a un mensaje de commit se le escapa.

Preguntas frecuentes

¿Claude ya no escribe mensajes de commit decentes? En formato, sí — esa fue la sorpresa del benchmark. El baseline clavó el tipo, el modo y los pies de ruptura de fábrica. Donde se quedó corto fue en cobertura: se dejó cambios secundarios en más de la mitad de los diffs de varios asuntos y varios archivos, y se pasó del asunto de 50 caracteres en 9 de 15. El trabajo de la skill es esa brecha, no el formato que todo el mundo ya clava.

¿Esto es solo un linter de Conventional Commits? No, y ahí está la clave. El cumplimiento de Conventional Commits es un espacio saturado y resuelto — docenas de skills lo hacen. commit-discipline exige la capa de debajo: que el mensaje dé cuenta de cada cambio lógico del diff y no invente nada. El formato aquí es lo mínimo esperable; la honestidad frente al diff es el producto.

¿Va a hacer commit o push por mí? No. Escribir el mensaje es el trabajo; ejecutar git commit es una instrucción aparte que la skill no toma por su cuenta. Tampoco añadirá pies Co-Authored-By ni "Generated with" a menos que el log de tu proyecto o tus propias instrucciones muestren que los quieres.

¿Debería fiarme del número de preferencia 9-4-2? Trátalo como directional, no como un veredicto. Lo juzgó una agente de la misma familia de modelo con las etiquetas cegadas, porque no había un juez de otra familia disponible en la máquina de pruebas — así que conlleva riesgo de autopreferencia, y n=15 no es estadísticamente significativo. Los números de cobertura (83%→97%) se apoyan en una lista de cambios de referencia preregistrada y son el resultado más sólido; los tres fixtures donde perdió la skill están nombrados arriba.