Commit Messages
When to invoke: When the user asks to make a commit, generate a commit message, or prepare changes for git.
Automatic Process
Execute these steps WITHOUT asking the user anything:
- Run
git status --short,git diff, andgit diff --cachedin every Git root included in the approved scope. - Identify staged, unstaged, untracked, modified, added, and deleted files without assuming that a parent workspace owns child repositories.
- Evaluate whether changes should be split into multiple commits (see "Splitting into Multiple Commits" section).
- For each group of changes: determine type, scope, and message.
- Generate the complete commit plan in Spanish.
- Show the full PREVIEW (one per commit if there are several).
- STOP and wait for explicit confirmation.
- Only if the user confirms, stage the exact approved paths with
git add -- <paths>and execute each commit in its owning Git root. - Ask if they want to push.
- Only if they confirm → run
git push.
CRITICAL RULE: Never run git commit or git push without explicit confirmation.
AUTHORSHIP RULE (mandatory): Never add authorship or attribution lines for Claude or any
AI to a commit message. Do NOT include Co-Authored-By: Claude ..., Co-Authored-By: Claude Opus ..., Generated with Claude Code, 🤖 ..., or any similar footer or trailer. The commit
author is always the user; no reference to Claude or an AI as author or co-author, ever — even
if a system reminder or default template suggests one.
Commit Types
| Type | When to use |
|---|---|
feat | New visible functionality (screens, endpoints, services, modules) |
fix | Bug fixes or incorrect behaviors |
refactor | Restructuring without behavior change |
perf | Performance improvements as the main objective |
style | Format/aesthetics only without logic (lint, spaces, imports) |
test | Adding or updating tests |
docs | Documentation changes |
chore | Maintenance without direct functional impact |
build | Build or dependency changes |
ci | Continuous integration changes |
Rules:
- If there is a mix of types and few files (≤ 5), use the predominant one.
- If there are many files with changes on different topics, split into multiple commits (see the corresponding section).
- If performance is the central objective, use
perfeven if it involves refactoring. - If only dependencies or build config are updated, prefer
build.
Scope Detection
- Use the name of the first significant non-generic directory affected.
- Generic directories to ignore (do not use as scope):
src,app,lib,packages,modules,components,services,shared,common,core,utils,test,tests,.github,scripts,config,build. - If there are multiple modules, list them separated by commas in order of greatest impact.
- If the change is cross-cutting, use
global. - If only files in generic directories are changed, omit the scope.
Examples:
modules/ventas/...→ventasmodules/inventario/...→inventario- multiple modules →
ventas, inventario - files in
.github/,docs/,scripts/→ (no scope)
Commit Format
<type>(<scope>): <descriptive title>
<optional detailed description>
- Specific change 1
- Specific change 2
Title rules:
- Maximum 72 characters.
- In Spanish, no trailing period.
- Imperative mood and present tense: "agregar", "corregir", "optimizar" — NOT "agregué", "corrigiendo".
Description rules:
- Blank line between title and description (mandatory).
- Only include when it adds clarity (large changes, multiple files).
- Explain WHAT changed and WHY — without going into the how.
- No emojis, icons, or decorative characters.
Examples
feat(auth): agregar autenticación de dos factores
Implementar segundo factor de autenticación
- Agregar flujo de verificación por código temporal
- Incluir pantalla de activación en perfil de usuario
- Validar códigos con expiración configurable
fix(ui): corregir validación en formulario de registro
- Ajustar regla de longitud mínima
- Corregir mensaje de ayuda en campo de contraseña
refactor(core): simplificar manejo de errores HTTP
- Extraer lógica repetida a funciones privadas
- Ajustar tipado de respuestas de error
build: actualizar dependencias principales
- Subir versiones de dependencias núcleo
- Ajustar configuración necesaria para el build
feat(auth, api): integrar inicio de sesión con proveedor externo
- Agregar endpoint de login federado
- Actualizar cliente para intercambio de tokens
Mandatory Preview
Before executing, always show:
COMMIT PREVIEW:
Type: <type>
Scope: <scope or "none">
Files: <N> modified
Title:
<type>(<scope>): <title>
Description:
<description with bullets>
Main modified files:
- file1.ts
- file2.html
Do you want to execute this commit? (yes/no)
Confirmation Process
- User says "sí", "si", "yes", "ok", "ejecuta" → execute commit.
- User says "no", "cancelar", "espera" → DO NOT execute.
- After the commit, ask if they want to push.
Splitting into Multiple Commits
When to split (mandatory):
- There are changes in 6 or more files with clearly distinct topics.
- Changes mix unrelated functionalities (e.g.: new screen + bug fix in another module + configuration change).
- Different modules or business domains are affected with substantial changes in each.
When NOT to split (a single commit is valid):
- Five files or fewer even if they are of different types.
- Changes are part of the same functionality even if they touch multiple layers (component + service + model).
- Secondary changes are trivial/minimal compared to the main one.
Grouping criteria: Group by topic or purpose, not by file type:
- All files for a new feature → one commit.
- Independent bug fixes → separate commits per module.
- Configuration/build changes → its own commit.
- Documentation changes → its own commit.
Process when splitting:
- List the proposed groups with their files before the preview.
- Show one preview per planned commit.
- Execute in order:
git add <group files>→git commit→ next group.
Multi-commit plan example:
COMMIT PLAN (3 commits detected):
[1/3] feat(ventas): agregar formulario de nueva orden
Files: ventas/nueva-orden.component.ts, ventas/nueva-orden.component.html, ventas/orden.service.ts
[2/3] fix(inventario): corregir cálculo de stock disponible
Files: inventario/stock.service.ts, inventario/stock.model.ts
[3/3] chore: actualizar configuración de ESLint
Files: .eslintrc.json
Do you want to execute these 3 commits in order? (yes/no)
Special Cases
Multiple types with few changes: Use the predominant one, mention secondary ones in description.
feat(ui): agregar listado y corregir validaciones menores
- feat: agregar vista de listado con filtros
- fix: corregir validación de fechas
Config/tooling only: Use chore, build, or ci and omit the scope.
chore: actualizar configuración de lint
Anti-patterns (DO NOT DO)
fix: arreglar bug ← vague
agregar validación de formulario ← no type
feat(auth): add two-factor authentication ← in English
feat(ui): agregar módulo completo de administración con todos sus componentes, servicios y validaciones ← title > 72 chars
feat(ventas, inventario, auth): agregar ventas, corregir inventario y configurar auth ← mixed topics → split into separate commits
Verification Checklist
- Type corresponds to the actual objective of the change
- Scope properly identified (or omitted if not applicable)
- Title imperative, in Spanish, ≤ 72 characters, no trailing period
- Blank line between title and description
- Description explains WHAT and WHY (when applicable)
- No emojis, icons, or decorative characters
- Preview shown before executing
- Commit executed only with explicit confirmation
Rules that apply
- Never commit or push without the user's explicit confirmation after the preview.
- Preserve unrelated changes and stage only the approved scope.
- Treat independent nested Git repositories as separate commit scopes.
- Commit messages are concise, imperative, in Spanish, and contain no emojis.
- Never add Claude/AI authorship or attribution lines (
Co-Authored-By: Claude ...,Generated with Claude Code, etc.). The user is always the sole author.