Skill: conventional-commits
Toda mensagem de commit deste projeto segue o padrão Conventional Commits. Isso habilita changelog automático, version bump por SemVer e leitura rápida do histórico. Sem exceção.
Trigger
- Toda vez que rodar
git commit.
- Antes de abrir PR (verificar histórico do branch).
- Quando rebase/squash consolidar commits — a mensagem final também segue o padrão.
- Quando o usuário pedir "faz commit", "commita as mudanças", "abre PR".
Padrão
<type>(<scope>)?: <subject>
[<body opcional>]
[<footer opcional>]
- type (obrigatório, minúsculo):
feat | fix | docs | style | refactor | perf | test | build | ci | chore | revert.
- scope (opcional): área afetada em uma palavra (
auth, api, ui, deps). Entre parênteses.
- subject (obrigatório): descrição curta no imperativo presente, minúsculo, sem ponto final, máx 72 caracteres.
- body (opcional): linhas explicando o "porquê", não o "o quê". Separado do subject por linha em branco. Wrap a 72 colunas.
- footer (opcional): referências a issue (
Closes #123), co-autores, ou marcação de breaking change.
Tipos — quando usar cada um
| Type |
Quando |
feat |
Nova feature visível ao usuário |
fix |
Correção de bug |
docs |
Só documentação (README, JSDoc, comentários) |
style |
Formatação que não muda comportamento (espaços, ponto-e-vírgula) |
refactor |
Reestruturação sem mudar comportamento externo |
perf |
Melhoria de performance |
test |
Adicionar/atualizar testes |
build |
Sistema de build, dependências (package.json, tsconfig) |
ci |
Pipeline CI/CD (.github/workflows, scripts de deploy) |
chore |
Manutenção genérica que não cabe nas outras |
revert |
Reverte commit anterior (mensagem cita o SHA revertido) |
Breaking change
Mudança incompatível com a versão anterior. Duas formas válidas, escolha uma:
- Bang após o type:
feat!:, refactor!:, fix!:.
- Footer explícito:
BREAKING CHANGE: <descrição do impacto e migração>.
Se possível, use as duas para deixar 100% claro.
Exemplos
feat(auth): add password reset flow via email link
fix(api): handle null user-agent header without crashing
docs: update README with new install steps
refactor(checkout): extract pricing logic into PriceCalculator
perf(search): debounce input to reduce API calls from 30 to 3 per typing burst
test(auth): cover expired-token edge case in login flow
build(deps): bump playwright to 1.45.0
ci: add Node 22 to test matrix
chore: remove unused dotenv import
revert: revert "feat(auth): add password reset flow via email link"
This reverts commit a1b2c3d4 — caused regression on existing reset tokens.
Closes #482
feat(api)!: rename /users endpoint to /accounts
BREAKING CHANGE: clients hitting /users must migrate to /accounts.
The old route returns 410 Gone. See migration guide in .specs/architecture/ADR-005.md.
Steps
- Identifique o tipo dominante da mudança. Se houve fix + refactor no mesmo diff, geralmente cabe
refactor com nota no body sobre o fix incidental — ou separe em dois commits.
- Escolha o scope (opcional) com base na pasta/módulo principal afetado. Mantenha consistência com scopes já usados no histórico.
- Escreva o subject no imperativo: "add", "fix", "remove" — não "added", "fixes".
- Adicione body se a motivação não for óbvia pelo subject. Explique o "porquê", referencie a task:
Refs #task-id.
- Marque breaking change quando aplicável (
! no header e/ou BREAKING CHANGE: no footer).
- Verifique tamanho: subject ≤ 72 chars, linhas do body ≤ 72.
- Commit. Se o projeto usa
commitlint no hook commit-msg, ele bloqueia mensagens fora do padrão — corrija e tente de novo.
Definition of Done
Notas
- Para SemVer automático:
feat → minor; fix, perf → patch; feat!/fix!/BREAKING CHANGE → major.
chore e style não geram bump de versão por padrão.- Linter recomendado:
@commitlint/cli + @commitlint/config-conventional. Hook em .husky/commit-msg ou .claude/hooks/.
- Spec oficial: https://www.conventionalcommits.org/.
1---2name: conventional-commits3description: padronizar mensagens de commit seguindo Conventional Commits (type, scope opcional, subject curto, breaking change marcado)4---56# Skill: `conventional-commits`78Toda mensagem de commit deste projeto segue o padrão **Conventional Commits**. Isso habilita changelog automático, version bump por SemVer e leitura rápida do histórico. Sem exceção.910---1112## Trigger1314- Toda vez que rodar `git commit`.15- Antes de abrir PR (verificar histórico do branch).16- Quando rebase/squash consolidar commits — a mensagem final também segue o padrão.17- Quando o usuário pedir "faz commit", "commita as mudanças", "abre PR".1819---2021## Padrão2223```24<type>(<scope>)?: <subject>2526[<body opcional>]2728[<footer opcional>]29```3031- **type** (obrigatório, minúsculo): `feat | fix | docs | style | refactor | perf | test | build | ci | chore | revert`.32- **scope** (opcional): área afetada em uma palavra (`auth`, `api`, `ui`, `deps`). Entre parênteses.33- **subject** (obrigatório): descrição curta no imperativo presente, minúsculo, sem ponto final, **máx 72 caracteres**.34- **body** (opcional): linhas explicando o "porquê", não o "o quê". Separado do subject por linha em branco. Wrap a 72 colunas.35- **footer** (opcional): referências a issue (`Closes #123`), co-autores, ou marcação de breaking change.3637### Tipos — quando usar cada um3839| Type | Quando |40| --- | --- |41| `feat` | Nova feature visível ao usuário |42| `fix` | Correção de bug |43| `docs` | Só documentação (README, JSDoc, comentários) |44| `style` | Formatação que não muda comportamento (espaços, ponto-e-vírgula) |45| `refactor` | Reestruturação sem mudar comportamento externo |46| `perf` | Melhoria de performance |47| `test` | Adicionar/atualizar testes |48| `build` | Sistema de build, dependências (`package.json`, `tsconfig`) |49| `ci` | Pipeline CI/CD (`.github/workflows`, scripts de deploy) |50| `chore` | Manutenção genérica que não cabe nas outras |51| `revert` | Reverte commit anterior (mensagem cita o SHA revertido) |5253### Breaking change5455Mudança incompatível com a versão anterior. **Duas formas válidas**, escolha uma:56571. **Bang após o type**: `feat!:`, `refactor!:`, `fix!:`.582. **Footer explícito**: `BREAKING CHANGE: <descrição do impacto e migração>`.5960Se possível, use as duas para deixar 100% claro.6162---6364## Exemplos6566```text67feat(auth): add password reset flow via email link6869fix(api): handle null user-agent header without crashing7071docs: update README with new install steps7273refactor(checkout): extract pricing logic into PriceCalculator7475perf(search): debounce input to reduce API calls from 30 to 3 per typing burst7677test(auth): cover expired-token edge case in login flow7879build(deps): bump playwright to 1.45.08081ci: add Node 22 to test matrix8283chore: remove unused dotenv import8485revert: revert "feat(auth): add password reset flow via email link"8687This reverts commit a1b2c3d4 — caused regression on existing reset tokens.88Closes #4828990feat(api)!: rename /users endpoint to /accounts9192BREAKING CHANGE: clients hitting /users must migrate to /accounts.93The old route returns 410 Gone. See migration guide in .specs/architecture/ADR-005.md.94```9596---9798## Steps991001. **Identifique o tipo** dominante da mudança. Se houve fix + refactor no mesmo diff, geralmente cabe `refactor` com nota no body sobre o fix incidental — ou separe em dois commits.1012. **Escolha o scope** (opcional) com base na pasta/módulo principal afetado. Mantenha consistência com scopes já usados no histórico.1023. **Escreva o subject** no imperativo: "add", "fix", "remove" — não "added", "fixes".1034. **Adicione body** se a motivação não for óbvia pelo subject. Explique o "porquê", referencie a task: `Refs #task-id`.1045. **Marque breaking change** quando aplicável (`!` no header e/ou `BREAKING CHANGE:` no footer).1056. **Verifique tamanho**: subject ≤ 72 chars, linhas do body ≤ 72.1067. **Commit**. Se o projeto usa `commitlint` no hook `commit-msg`, ele bloqueia mensagens fora do padrão — corrija e tente de novo.107108---109110## Definition of Done111112- [ ] Mensagem segue `<type>(<scope>)?: <subject>` com type válido da lista.113- [ ] Subject ≤ 72 caracteres, imperativo, minúsculo, sem ponto final.114- [ ] Body (se presente) separado por linha em branco e com wrap em 72 colunas.115- [ ] Breaking change marcado com `!` e/ou footer `BREAKING CHANGE:`.116- [ ] `commitlint` passou (se configurado em `.commitlintrc` / hook `commit-msg`).117- [ ] Histórico do branch é coerente: sem commits "wip", "fix typo" pendurados — squash/rebase antes do PR.118119---120121## Notas122123- Para SemVer automático: `feat` → minor; `fix`, `perf` → patch; `feat!`/`fix!`/`BREAKING CHANGE` → major.124- `chore` e `style` **não** geram bump de versão por padrão.125- Linter recomendado: `@commitlint/cli` + `@commitlint/config-conventional`. Hook em `.husky/commit-msg` ou `.claude/hooks/`.126- Spec oficial: <https://www.conventionalcommits.org/>.
wesleysimplicio