Skill Commit

Commits en Git — Buenas Prácticas

El objetivo de un buen commit es que cualquier persona del equipo (o tú mismo dentro de 6 meses) pueda entender qué se cambió y por qué con solo leer el historial de git. Un commit bien hecho facilita las revisiones de código, simplifica los reverts y hace que el proyecto sea más mantenible.

Estructura del mensaje de commit

Usa el formato de Conventional Commits adaptado al español:

<tipo>(<ámbito>): <descripción breve>

<cuerpo opcional>

<pie opcional>

Ejemplo 1:

feat(facturas): añadir campo de descuento por pronto pago

Se añade un nuevo campo en el modelo de factura que permite
aplicar un porcentaje de descuento cuando el cliente paga
antes de la fecha de vencimiento.

Ejemplo 2:

fix(informes): corregir cálculo de IVA en informe trimestral

El IVA se estaba calculando sobre el total con descuento en
lugar de sobre la base imponible. Ahora se aplica correctamente.

Ejemplo 3 (simple):

docs(readme): actualizar instrucciones de instalación

Código de tarea en el commit

Cuando el usuario proporcione un código de tarea (por ejemplo, un número de issue o tarea del roadmap como 4543, #1234, TASK-567, etc.), este código debe incluirse en el título del commit, justo después del tipo (y ámbito si lo hay), antes de la descripción. Solo se incluye el código numérico o identificador, sin enlaces ni texto adicional.

Formato con código de tarea:

<tipo>: <código> <descripción breve>

Formato con código de tarea y ámbito:

<tipo>(<ámbito>): <código> <descripción breve>

Ejemplos con código de tarea:

feat: 4543 añadir filtro por fecha de pago en las listas de anticipos de clientes y proveedores

fix: 1287 corregir cálculo de IVA en informe trimestral

feat(facturas): 3201 añadir campo de descuento por pronto pago

Si el usuario no menciona ningún código de tarea, el commit se escribe sin él, siguiendo el formato estándar.

Tipos de commit

Estos son los tipos que debes usar. Elegir el tipo correcto ayuda a generar changelogs automáticos y a entender el historial de un vistazo:

• feat: nueva funcionalidad o característica
• fix: corrección de un error o bug
• docs: cambios solo en documentación
• style: formato, punto y coma faltante, etc. (sin cambios en lógica)
• refactor: reestructuración de código sin cambiar comportamiento
• test: añadir o corregir tests
• chore: tareas de mantenimiento (dependencias, configuración, CI, etc.)
• perf: mejora de rendimiento

Reglas para un buen mensaje

La primera línea es lo más importante porque es lo que aparece en git log --oneline, en las interfaces de GitHub y en las revisiones de código:

• Escríbela en imperativo: "añadir", "corregir", "eliminar" (no "añadido", "corregido")
• Máximo 72 caracteres en la primera línea
• No termines con punto la primera línea
• Escribe en minúsculas (salvo nombres propios o acrónimos)

El cuerpo es opcional pero muy valioso cuando el cambio no es trivial. Úsalo para explicar el por qué del cambio, no solo el qué (el qué ya se ve en el diff). Sepáralo de la primera línea con una línea en blanco.

Commits atómicos

Cada commit debería representar un solo cambio lógico. Esto es importante porque permite hacer git revert de un cambio concreto sin arrastrar otros, y hace que las revisiones de código sean mucho más fáciles de seguir.

Señales de que un commit es demasiado grande:

• Necesitas usar "y" en la descripción ("añadir campo X y corregir validación Y")
• Mezcla cambios funcionales con cambios de formato
• Toca muchos archivos sin relación entre sí

Si tienes cambios mezclados en tu directorio de trabajo, usa git add -p para seleccionar solo los cambios relevantes para cada commit.

Qué NO incluir en un commit

Antes de confirmar, revisa que no estés incluyendo archivos que no deberían estar en el repositorio:

• Archivos .env o con credenciales
• Archivos binarios grandes o compilados
• Carpetas como node_modules/, vendor/, __pycache__/
• Archivos temporales o de IDE (.idea/, .vscode/settings.json personales)

Flujo al hacer commit

Cuando el usuario pida hacer un commit, sigue este orden:

1. Ejecuta git status para ver los archivos modificados y sin seguimiento
2. Ejecuta git diff (staged y unstaged) para entender los cambios
3. Ejecuta git log --oneline -5 para ver el estilo de commits recientes del proyecto
4. Analiza los cambios y redacta un mensaje de commit que siga las convenciones anteriores
5. Haz staging solo de los archivos relevantes (evita git add . a ciegas)
6. Crea el commit con el mensaje bien formateado
7. Añade siempre al final: Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Si los cambios incluyen múltiples temas distintos, propón dividirlos en varios commits separados.