La mayoría de los mensajes de commit solo repiten el diff, que es justo lo que git ya sabe. Este es un prompt para copiar y pegar que toma un diff en staging y lo convierte en un mensaje de Conventional Commit que explica la intención, se niega a mezclar cambios sin relación y es lo bastante mecánico para usarlo en cada commit. Te llevas la plantilla completa, las variables que puedes ajustar, cuatro variantes y las formas en que puede fallar para que estés pendiente.
En resumen
- Pega un diff en staging y te devuelve un mensaje de Conventional Commit centrado en la intención: asunto de menos de 60 caracteres y un cuerpo que explica el porqué.
- El detector de mezclas es lo más valioso. Detecta los commits «feat + arreglo de paso + reformateo» y se niega a escribir un solo mensaje para todo eso.
- Define tus scopes permitidos en el prompt, o se inventa uno nuevo a partir del nombre de la carpeta cada vez que lo usas.
- Pásale «git diff --staged», nunca todo el working tree, o te va a describir cambios que todavía no incluiste en el commit.
- Trae cuatro variantes: one-liner escueto, scopes de monorepo, footer de breaking change y resumen para squash-merge.
Abre el historial de cualquier repo y la mayoría de los mensajes se leen como una versión peor del diff: «update user.ts», «fix bug», «cambios». El diff ya te dice qué cambió línea por línea. Lo que jamás te va a decir es por qué, y eso es justo lo que vas a andar buscando a las 2am dentro de seis meses haciendo un «git blame». Este recurso es un prompt para copiar y pegar que corrige el incentivo: deja el formato de Conventional Commit en piloto automático para que no pierdas tiempo discutiéndolo, y dedica el cuerpo a la intención. Al final te llevas la plantilla completa, los espacios que vale la pena ajustar, cuatro variantes para distintos flujos y las formas concretas en que falla para que las detectes a tiempo.
01 · El prompt
Aquí lo tienes completo. Mételo en un slash command de Claude Code, en un prompt guardado, o simplemente pégalo en el chat con tu diff en staging debajo.
You are writing a Conventional Commit message for the staged diff below.
FORMAT
type(scope): subject
<blank line>
body, 1 to 3 short lines
RULES
- Subject: imperative mood ("add", not "added"/"adds"), under 60 chars,
no trailing period, lowercase after the colon.
- Types: feat, fix, refactor, perf, docs, test, build, ci, chore.
- Scope: choose ONE from this allowed list: [auth, api, ui, db, infra, deps].
If nothing fits, omit the scope entirely; do NOT invent a new one.
- Body explains WHY this change exists (the problem, the decision,
the tradeoff). Do NOT restate what the diff already shows line by line.
- If the change is trivial and self-evident (typo, version bump), the
body may be a single line or omitted.
SPLIT CHECK (do this first)
- If the diff mixes UNRELATED concerns (e.g. a feature plus an unrelated
bug fix, or logic changes tangled with bulk reformatting), do NOT write
one message. Instead, say so plainly and list how to split it into
separate commits (which files/hunks go in each). Stop there.
OUTPUT
- Output ONLY the commit message, with no fences, no preamble, no
"Here is...". If you triggered the SPLIT CHECK, output only the
split advice instead.
STAGED DIFF:
<paste the output of: git diff --staged>
Esa es la pieza central. Todo lo de abajo es para ajustarla a tu repo y para saber cuándo no fiarte de ella.
Consejo
En Claude Code, guarda esto como un slash command (un archivo Markdown dentro de «.claude/commands/») y haz que él mismo corra «git diff --staged»; así nunca pegas el diff a mano. El cuerpo del comando es el prompt de arriba, con la sección del diff reemplazada por la salida del shell del comando.
02 · Cómo adaptarlo
El prompt funciona tal cual, pero hay dos cambios que lo hacen encajar con tu repo en vez de con uno genérico.
Primero, la lista de scopes permitidos. La línea «choose ONE from this allowed list: [auth, api, ui, db, infra, deps]» es lo más importante que puedes personalizar. Si la dejas genérica, el modelo adivina el scope a partir del nombre de tu carpeta de nivel superior: hoy «components» y mañana «component», y tu historial nunca agrupa bien. Reemplaza la lista entre corchetes con los scopes reales de tu proyecto. Si no usas scopes, cambia la línea por «Do not use a scope» y quita «(scope)» del bloque de formato.
Segundo, la lista de types. Los nueve types por defecto son el conjunto común de Conventional Commits, pero cada equipo tiene los suyos. Si tu CI dispara releases según el type del commit (muchos lo hacen: «feat» sube la versión minor y «fix» sube la patch), haz que la lista de types del prompt coincida exactamente con lo que reconoce tu herramienta de release. Un «chore» donde la herramienta esperaba «build» no dispara el release que querías, y encima lo hace en silencio.
Dónde correrlo
- Antes del commit, de forma interactiva. Pegas el diff, lees el mensaje, ajustas una palabra y haces el commit. Es lo más honesto: no pierdes el control.
- Como comando de Claude Code. «/commit-msg» lee el diff en staging e imprime el mensaje para que lo apruebes. Lo más rápido para el día a día.
- Nunca del todo desatendido. No lo metas en un hook que haga commit automático con el mensaje generado. El split check es un consejo, no una compuerta. Al modelo todavía se le puede escapar un diff enredado, y un mensaje equivocado ya guardado en el commit es peor que no tener automatización.
03 · Las variables que puedes ajustar
Piensa en el prompt como si tuviera un puñado de perillas. Estas son las que vale la pena mover.
- Scopes permitidos. Lo de arriba; el cambio que más rinde.
- Largo del asunto. 60 caracteres es un valor seguro que aguanta casi cualquier herramienta. Algunos equipos lo mantienen en 50 (el ancho clásico de «git log --oneline»). Bájalo en el bloque RULES si quienes revisan son estrictos.
- Verbosidad del cuerpo. «1 to 3 short lines» sirve para casi todo. En un codebase donde los commits suelen cargar el razonamiento de diseño, súbelo a «up to 5 lines» y agrega «reference the issue or ticket ID if one applies».
- Vocabulario de types. Que coincida con tu automatización de release, como ya vimos.
- Idioma. Agrega «Write the message in Spanish» (o el idioma que sea) y el formato queda idéntico; solo cambia la prosa. La gramática «type(scope):» es neutral al idioma a propósito.
Importante
Deja la etiqueta «STAGED DIFF» y la instrucción «git diff --staged» tal cual están. La falla silenciosa más común es pegar «git diff» (lo que no está en staging) o «git diff HEAD» (todo), lo que hace que el modelo describa con toda seguridad cambios que no van en el commit que estás por hacer.
04 · Variantes
Cuatro reescrituras listas para usar en situaciones comunes. Cada una reemplaza o amplía una parte del prompt base.
One-liner escueto. Para commits triviales y obvios, donde un cuerpo sobra. Cambia FORMAT y RULES por:
Output a single Conventional Commit subject line, nothing else.
Format: type(scope): subject, imperative, under 60 chars, no body.
Use this only when the change is genuinely self-explanatory; if it
carries any non-obvious intent, say "needs a body" and stop.
Monorepo con scopes por paquete. Cuando el scope debe ser el paquete afectado y no un área genérica, reemplaza la regla del scope por:
Scope: the name of the package directory the change lives in, taken
from the path (e.g. packages/<name>/... -> scope is <name>). If the
diff spans multiple packages, that's a SPLIT CHECK trigger: one
commit per package. Do not invent a scope outside the path.
Footer de breaking change. Para librerías que siguen SemVer y necesitan marcar el cambio incompatible. Agrega esto a RULES:
If the change alters a public API in a backward-incompatible way, add
"!" after the type/scope (e.g. feat(api)!: ...) AND a footer:
"BREAKING CHANGE: <what broke and how to migrate>". Only do this for
genuinely incompatible changes, not internal refactors.
Resumen para squash-merge. Cuando haces squash de una branch de feature y quieres un solo mensaje que resuma muchos commits, pásale «git log main..HEAD» en lugar de un diff y usa:
Summarize this branch's commits into ONE Conventional Commit message.
Subject names the feature; body lists the 2-4 substantive changes as
bullet points (skip merge commits and pure-formatting commits).
05 · Detalles a cuidar y concesiones
Los modos de falla, sin maquillaje, para que no te agarren por sorpresa.
- Todavía se le puede escapar un diff enredado. El split check atrapa los casos obvios, como un feature junto a un arreglo sin relación, pero una mezcla sutil (un refactor que cambia el comportamiento sin avisar) se le puede colar. El prompt reduce los mensajes malos; no te ahorra leer tu propio diff.
- Los diffs grandes cuestan tokens y atención. Un diff de 2,000 líneas da un mensaje más vago que uno de 40, porque el modelo tiene que resumir más. El arreglo no es un mejor prompt, son commits más pequeños. Si el diff es demasiado grande para describirlo en tres líneas, esa es la señal de que hay que dividirlo.
- El texto generado puede alejarse del estilo de la casa. Si tu equipo tiene convenciones que el prompt no codifica (prefijos de ticket, una lista de palabras prohibidas, un trailer obligatorio de co-author), la salida no las va a incluir. Pon esas reglas de forma explícita en vez de esperar que el modelo las adivine.
- No dejes que entierre una decisión de verdad. El cuerpo debe capturar la intención, pero una decisión de arquitectura realmente importante va en un ADR o en la descripción del PR, no apretada en tres líneas de commit. Usa el commit para el porqué local; usa el doc largo para el que carga peso.
Sobre la elección del modelo: esto corre bien en cualquier modelo Claude actual, y un mensaje de commit es claramente una tarea de bajo esfuerzo, así que no tiene sentido gastar los tokens de un modelo de gama alta en eso. Si llamas a la API directo en vez de usar Claude Code, claude-haiku-4-5 lo resuelve limpio y barato. Deja el extended thinking apagado acá; la tarea no necesita deliberar y tú quieres la respuesta rápida.
Un buen prompt de commits es una cosa pequeña que va sumando. Escribes el mismo mensaje de cinco segundos cientos de veces al año, y la diferencia entre «update auth» y una línea que nombra la decisión real es la diferencia entre un historial que puedes leer y uno que pasas de largo. Ajusta los scopes una vez, guárdalo como comando y deja que el formato se encargue solo.
Puntos clave
- El cuerpo está para el porqué, la decisión y la concesión, porque el diff ya carga el qué.
- Define en el prompt tus scopes permitidos reales; una lista genérica es de donde salen las variaciones y el historial desordenado.
- El split check es un consejo que reduce los commits enredados, no una compuerta. Mantén la supervisión humana antes de hacer el commit.
- Pásale «git diff --staged» exacto, y antes de buscar un prompt mejor, busca commits más pequeños.
- Es una tarea de bajo esfuerzo: usa un modelo barato como «claude-haiku-4-5», guárdalo como comando y deja que vaya sumando.
Preguntas frecuentes
¿Por qué no dejar que el modelo lea todo mi working tree en vez de un diff en staging?
Porque el commit solo incluye lo que pusiste en staging. Si le pasas el diff sin staging o el completo, va a describir cambios que no van a estar en el commit: un mensaje seguro de sí mismo y equivocado. Pásale siempre «git diff --staged» para que el mensaje coincida con el snapshot que de verdad vas a guardar en el commit.
No deja de inventar nombres de scope. ¿Cómo lo detengo?
Reemplaza la lista de ejemplo «[auth, api, ui, db, infra, deps]» con tus scopes reales y deja la instrucción de omitir el scope cuando nada encaje. Sin lista permitida, el modelo adivina a partir del nombre de la carpeta y esa adivinanza cambia cada vez, que es justo lo que rompe la agrupación del historial.
¿Puedo confiar en el split check para mantener mis commits limpios de forma automática?
Trátalo como un revisor inteligente, no como una compuerta. Atrapa sin problema las mezclas obvias (un feature más un arreglo sin relación), pero un refactor que cambia el comportamiento sin avisar se le puede colar. Mantén un paso de aprobación humana: nunca lo metas en un hook que haga commit automático sin que tú leas el resultado.
¿Qué modelo de Claude debería usar para esto?
Cualquier modelo actual sirve, pero un mensaje de commit es una tarea de bajo esfuerzo, así que no ganas nada gastando un modelo de gama alta. Si llamas a la API directo, «claude-haiku-4-5» es la elección correcta: rápido y barato. Deja el extended thinking apagado; la tarea no necesita deliberar. En Claude Code, usa el modelo que ya esté corriendo en la sesión.
¿Sirve para idiomas que no sean inglés?
Sí. Agrega «Write the message in Spanish» (o el idioma que sea) y solo cambia la prosa: la gramática «type(scope): subject» es neutral al idioma a propósito, así que tus herramientas y generadores de changelog la siguen parseando igual. Deja los types del commit en inglés aunque el cuerpo esté en otro idioma; es lo que esperan las herramientas de release.
Mi diff es enorme y el mensaje sale vago. ¿Ahora qué?
Eso es una señal, no un problema del prompt. Un diff de 2,000 líneas no se deja comprimir honestamente en tres líneas, así que el modelo resume y pierde lo específico. El arreglo real son commits más pequeños: si no puedes describir el cambio en un cuerpo corto, lo más probable es que haga más de una cosa y convenga dividirlo.
¿Prefieres que lo hagamos por ti?
Esto mismo lo construimos para negocios como el tuyo. La primera conversación es gratis y sin compromiso.
Escríbenos por WhatsAppPrimera conversación gratis. Te responde el fundador.
Recursos relacionados
El skill de mensajes de commit: escribe el porqué, no el diff
Un skill empaquetado de Claude Code lee el diff que tienes en stage y escribe un commit convencional cuyo cuerpo explica el razonamiento, no las líneas que cambiaron. Qué hace, cuándo debe activarse, cómo funciona por dentro, una corrida real con su salida, la config que importa y el único hábito que decide si tu git log vale la pena dentro de seis meses.
Un prompt de postmortem sin culpas que no se queda en el primer error humano
La mayoría de los postmortems se quedan en la primera persona que se equivocó, lo bautizan como causa raíz y cierran con una acción que dice 'hay que tener más cuidado', lo que garantiza que el mismo incidente vuelva. Este es un prompt para copiar y pegar que convierte una línea de tiempo cruda en un reporte sin culpas: empuja más allá de la causa inmediata hasta la falla de proceso o sistema, y descarta toda acción que dependa de que alguien esté atento en vez de una barrera real. Te llevas la plantilla completa, cómo adaptarla a tu equipo, las variables que puedes ajustar, cuatro variantes y las formas en que falla sin que te des cuenta.
El skill que describe PRs: convierte un diff en una descripción que el revisor sí va a leer
Un skill empaquetado de Claude Code lee el diff contra tu rama base y redacta la descripción del pull request: qué cambió, por qué y cómo probarlo paso a paso. Así tu revisor deja de adivinar tu intención a partir del código pelado. Qué hace, cuándo debe dispararse, cómo funciona por dentro y lo único que jamás va a saber y que te toca poner a ti.