jksim/agent-skills-jksim

Higiene de Commits

Resumen

Regla 4 de las reglas de Jarrett: un cambio tiene solo los commits que necesita lógicamente. Un revisor lee un commit limpio por cada cambio, no un historial de intentos. Los comentarios son breves.

El hook commit-check advierte cuando un mensaje de git commit supera los límites. No bloquea. Tú corriges el commit.

Cuándo Usar

• Antes de cada commit.
• Antes de cada push.
• Cuando hiciste más de un commit para corregir un solo problema.
• Cuando el hook commit-check advierte.

Proceso

1. Escribir el mensaje

• Asunto: 72 caracteres o menos. Usa el imperativo: "Add rules hook", no "Added rules hook".
• Cuerpo: 5 líneas o menos. Omítelo cuando el asunto sea suficiente.
• Di qué cambió y por qué. No describas cada archivo.
• Usa inglés simplificado. Consulta la habilidad simplified-english.

2. Hacer un commit por cada cambio lógico

• Un cambio lógico: una porción de funcionalidad, una corrección o una refactorización que un revisor pueda aceptar o rechazar como una unidad.
• No mezcles una refactorización y un cambio de comportamiento en el mismo commit.
• No hagas commit de cada intento. Haz commit cuando el cambio funcione y las pruebas pasen.

3. Squashear commits de arreglo antes del push

Un commit de arreglo corrige un commit anterior dentro del mismo cambio. Ejemplos: "fix typo", "wip", "address review".

1. Haz el commit de arreglo con git commit --fixup <sha>.
2. Squashealo sin editor: GIT_SEQUENCE_EDITOR=: git rebase -i --autosquash <base>.
3. Si el rebase se detiene por un conflicto, corrige los archivos y ejecuta git add <archivos>. Luego ejecuta GIT_EDITOR=true git rebase --continue. Para detenerte, ejecuta git rebase --abort.
4. Vuelve a ejecutar las pruebas.
5. Verifica el resultado: git log --oneline <base>..HEAD.

Si el último commit es el que hay que corregir, usa git commit --amend --no-edit.

Advertencia: no reescribas commits que ya están en una rama compartida. Pregúntale primero al usuario. Una reescritura obliga a cada compañero a hacer reset.

4. Mantén los comentarios breves

• Escribe un comentario solo cuando el código no sea claro.
• Una línea suele ser suficiente. Di por qué, no qué.
• No escribas el historial de cambios en los comentarios. Git guarda el historial.

Racionalizaciones Comunes

Racionalización	Realidad
"Los commits pequeños muestran mi progreso."	El revisor necesita el resultado, no el camino. Squasea los intentos.
"Un mensaje largo da más contexto."	Los mensajes largos no se leen. Pon el contexto en la especificación o el PR.
"Haré squash después."	Después es después del push. Haz squash antes del push.
"El hook solo advierte, así que el límite es opcional."	El límite es una regla del equipo. El hook advierte para que puedas corregirlo.

Banderas Rojas

• git log muestra "wip", "fix", "oops" o "try again" antes del push.
• Más de un commit para una sola corrección de errores.
• Un cuerpo de commit que lista cada archivo modificado.
• Comentarios que repiten lo que dice el código.

Verificación

• Cada asunto tiene 72 caracteres o menos y usa el imperativo.
• Cada cuerpo tiene 5 líneas o menos.
• git log --oneline <base>..HEAD muestra un commit por cada cambio lógico.
• No quedan commits de arreglo antes del push.
• Las pruebas pasan después de cualquier rebase.

Limitación conocida: el hook no verifica git -C <dir> commit ni git -c <clave>=<valor> commit. También omite algunos mensajes que no puede leer, por ejemplo -F <archivo>.