Git Commit Messages

Overview

Write commit messages and PR descriptions with clear subject lines, explanatory bodies, and optional trailers. Be autonomous when intent is clear, interactive when clarification needed.

Commit Message Format

Subject Line

•Separate from body with blank line
•Limit to 50 characters
•Start with lowercase tag + colon: cli:, rfd:, api:, db:, release:
•Capitalize first word after tag
•Imperative mood ("Add feature" not "Added feature")
•No period at end

Body

•Wrap at 72 characters
•Explain "what" and "why", not "how"
•Prose over bullet lists (bullets only when truly needed)
•May use markdown like backticks for code/commands
•Include verbatim commands when changes were generated (go generate, protoc)

Do NOT

•Use semantic commits (feat:, fix:, chore:)
•Add "Generated by Claude" or co-author trailers
•End subject with period

Example

code

rfd: Update with recent decision to drop DMS

After extensive testing, AWS DMS showed no benefits over logical
replication while being less stable and slower. The production CLI
will use logical replication only, with cluster_name instead of
tenant_id for easier tenant identification.

Trailers

Add at end of body when relevant:

Trailer	Purpose
`link:`	Reference URL for context
`issue:`	GitHub issue being addressed
`poc:`	Proof of concept repository/URL
`gen-command:`	Command that generated changes
`commit-group:`	Groups related commits that could be one

Example with Trailers

code

api: Add user permissions endpoint

Adds GET /api/v1/users/{id}/permissions for fetching effective
permissions. Required for the new RBAC dashboard.

issue: https://github.com/org/repo/issues/123
gen-command: go generate ./pkg/api/...

Interactive vs Autonomous

Autonomous (just write the message) when:

•Single file or tightly related files changed
•Tag obvious from paths (rfd/ -> rfd:, cmd/cli/ -> cli:)
•Purpose clear from diff or conversation context

Interactive (ask questions) when:

•Changes span multiple unrelated areas
•Multiple valid tags could apply
•The "why" isn't clear
•Large refactor where intent matters
•Need to split generated vs manual changes

Questions to Ask

•What tag best describes this change?
•What's the motivation behind this change?
•Should this be split into multiple commits?
•Any trailers to add?

PR Descriptions

Title

Same as commit subject: ~50 chars, tag prefix, imperative mood, no period.

Body

code

## Summary
<1-3 sentences explaining the "why">

## Test plan
<How to verify — manual steps, test commands, etc.>

Optional Sections

•## Breaking changes — if any
•## Related — links to issues, RFDs, other PRs

Do NOT

•Add "Generated by Claude" footers
•Use bullet lists in summary unless truly needed