Conventional Commits para coding agents: feat, fix y el ! que rompe SemVer

Git no exige un formato. Los agentes, sí: si cada sesión inventa Update files y fix stuff, el historial no sirve para changelog ni para gh pr create --fill. Conventional Commits 1.0.0 es la convención mínima encima de Git. Encaja con SemVer: fix → PATCH, feat → MINOR, BREAKING CHANGE / ! → MAJOR.

No sustituye PRs con gh. Es el subject del commit que alimenta el PR. El curso instalar un agente no cubre el mensaje.

La forma

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Tipos que la spec define con efecto SemVer: feat, fix. El resto (docs, test, refactor, chore, ci, perf, style, build) los recomienda Angular/commitlint; no suben versión salvo que lleven breaking.

Breaking:

• Footer BREAKING CHANGE: la API X ya no…
• o feat(api)!: … / feat!: …

Un ! después del type/scope es breaking. Un agente no pone ! porque el diff es grande. Lo pone si rompe consumidores.

Instrucciones para el harness (copiar)

Commit subject: conventional commits 1.0.0
feat|fix|docs|test|refactor|chore(scope): description in English or Spanish, imperative, no period
One logical change per commit. No "wip", "updates", "misc".
Breaking: type!: or footer BREAKING CHANGE:
Body only if the why is not in the subject.

Ejemplos que la spec usa (adaptados):

Mal	Bien
Update files	fix: prevent racing of requests
Added polish	feat(lang): add Polish language
breaking stuff	feat!: drop support for Node 6
docs	docs: correct spelling of CHANGELOG

Subject: imperativo, como Git. add, fix, drop. No added. ~50–72 caracteres. Sin punto final.

Scope: un área del repo (guias, api, auth). No el nombre del agente.

Qué no hacer

• Un commit por archivo tocado. Un commit por cambio lógico.
• Meter BREAKING CHANGE en el body sin el footer. La spec pide footer o !.
• feat para un typo. Eso es fix o docs.
• Mentir el type para pasar un linter (chore que es un feat).
• Co-author falso. Si el agente escribe, Co-authored-by solo si la org lo pide.

git commit -m "$(cat <<'EOF' con subject + blank + body. El agente que pasa -m una sola línea está bien si no hay body.

FAQ

¿Español o inglés? El del repo. Este sitio mezcla feat(guias): + español. Sé consistente en el PR, no en cada idioma del modelo.

¿commitlint obligatorio? No. La convención vive en AGENTS.md. Añade husky cuando un humano se canse de wip.

¿Varios footers? Sí, estilo git trailer (Reviewed-by:, Refs: #123). Fixes #123 cierra el issue al merge del PR.

¿style es CSS? En Angular, style = formato (prettier), no CSS. Para CSS visible usa feat/fix.

Si el linter de commits rechaza el subject, no pongas --no-verify. Reescribe la línea. Un agente que salta hooks es el mismo que pushea a main.

Verificado 2026-09-03 contra Conventional Commits 1.0.0 (summary + examples).