Commit Style — Team Commit Message Conventions
Write commit messages that pass the team's commit-msg hook on the first try
and read well in git log years later.
Procedure
Read the project's style file first: .claude/idev/commit-style.md.
If it exists, its rules override everything below. If it doesn't exist,
apply the defaults below (and mention that /idev:hooks install-git-hooks
sets up the style file + enforcement hooks).
Derive the ticket ID from the branch name when the style requires one:
git branch --show-current, extract the first ABC-123-shaped token.
The prepare-commit-msg hook does this automatically too — don't add the
prefix twice.
Write the message:
- Subject:
type(scope): imperative summary — conventional-commit types
(feat, fix, docs, refactor, perf, test, build, ci,
chore), ≤ 72 chars, no trailing period.
- Body (for anything non-trivial): the why, not a list of what — the
diff already shows what. Wrap at ~72 columns.
- Trailers last, each on its own line (
Co-Authored-By:, Refs:), per
the team's policy in the style file.
Check before committing: if .git/hooks/commit-msg exists, the message
must match its pattern (default: optional ABC-123: ticket prefix +
conventional-commit subject). If the hook rejects a commit, fix the
message — never bypass with --no-verify unless the user explicitly asks.
Defaults (when no style file exists)
feat(auth): add refresh-token rotation
Sessions died after 15 minutes because the access token was never
refreshed. Rotate the refresh token on each renewal per OWASP.
Refs: ABC-123
Pull request format
When creating a PR (any platform — az repos pr create on Azure DevOps,
gh pr create on GitHub), unless .claude/idev/commit-style.md overrides:
- Title: same convention as the commit subject (ticket prefix + typed
imperative summary). For a single-commit branch, reuse the subject.
- Description:
## What
2-4 bullets of user-visible change (not a commit list — the platform shows those).
## Why
The problem/ticket context in 1-3 sentences.
## Testing
What was actually run: build, tests, browser-test report path if UI.
## Notes for reviewer
Risky spots, decisions needing eyes, rollback hint. Omit if none.
Anti-patterns
- "fix stuff", "wip", "updates" — the hook rejects these; so should you.
- Restating the diff in the body.
- Bundling unrelated changes to share one message — split the commits.
1---2name: commit-style3description: Team commit-message conventions. Use when writing a commit message, committing or amending changes, or when asked about the project's commit format. Reads the per-project style from .claude/idev/commit-style.md.4---56# Commit Style — Team Commit Message Conventions78Write commit messages that pass the team's `commit-msg` hook on the first try9and read well in `git log` years later.1011## Procedure12131. **Read the project's style file first**: `.claude/idev/commit-style.md`.14 If it exists, its rules override everything below. If it doesn't exist,15 apply the defaults below (and mention that `/idev:hooks install-git-hooks`16 sets up the style file + enforcement hooks).17182. **Derive the ticket ID from the branch name** when the style requires one:19 `git branch --show-current`, extract the first `ABC-123`-shaped token.20 The `prepare-commit-msg` hook does this automatically too — don't add the21 prefix twice.22233. **Write the message**:24 - Subject: `type(scope): imperative summary` — conventional-commit types25 (`feat`, `fix`, `docs`, `refactor`, `perf`, `test`, `build`, `ci`,26 `chore`), ≤ 72 chars, no trailing period.27 - Body (for anything non-trivial): the **why**, not a list of what — the28 diff already shows what. Wrap at ~72 columns.29 - Trailers last, each on its own line (`Co-Authored-By:`, `Refs:`), per30 the team's policy in the style file.31324. **Check before committing**: if `.git/hooks/commit-msg` exists, the message33 must match its pattern (default: optional `ABC-123: ` ticket prefix +34 conventional-commit subject). If the hook rejects a commit, fix the35 message — never bypass with `--no-verify` unless the user explicitly asks.3637## Defaults (when no style file exists)3839```40feat(auth): add refresh-token rotation4142Sessions died after 15 minutes because the access token was never43refreshed. Rotate the refresh token on each renewal per OWASP.4445Refs: ABC-12346```4748## Pull request format4950When creating a PR (any platform — `az repos pr create` on Azure DevOps,51`gh pr create` on GitHub), unless `.claude/idev/commit-style.md` overrides:5253- **Title**: same convention as the commit subject (ticket prefix + typed54 imperative summary). For a single-commit branch, reuse the subject.55- **Description**:5657```markdown58## What592-4 bullets of user-visible change (not a commit list — the platform shows those).6061## Why62The problem/ticket context in 1-3 sentences.6364## Testing65What was actually run: build, tests, browser-test report path if UI.6667## Notes for reviewer68Risky spots, decisions needing eyes, rollback hint. Omit if none.69```7071## Anti-patterns7273- "fix stuff", "wip", "updates" — the hook rejects these; so should you.74- Restating the diff in the body.75- Bundling unrelated changes to share one message — split the commits.
TheophilusChinomona