Git Commit Guidelines
Related Skills: See standalone-commits for making each commit reviewable and auditable and for ordering multi-file changes into dependency-ordered waves. See pull-request for PR titles, descriptions, changelog entries, issue references, and merge guidance.
PR Boundary
PR titles, PR bodies, changelog entries, issue links, username verification, CODEOWNERS notes, and merge strategy belong to pull-request.
Working in a worktree
Several agent harnesses keep worktrees of this repository at once.
- Verify
HEADbefore committing (git rev-parse --abbrev-ref HEAD). A handoff may claim a fresh branch that does not exist, and another session may have switched the worktree since you last looked. git stashis shared across all worktrees. A baregit stashorstash popcan take another worktree's entry. Commit to a branch instead.- A branch cut from whatever was checked out carries unmerged work. Before opening a PR, run
git diff --stat origin/main...HEADand confirm the scope.
Deleting worktrees and branches belongs to worktree-hygiene.
References
This skill keeps its rules inline. For PR work, use pull-request.
Conventional Commits Format
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
Commit Types
feat: New features (correlates with MINOR in semantic versioning)fix: Bug fixes (correlates with PATCH in semantic versioning)docs: Documentation only changesrefactor: Code changes that neither fix bugs nor add featuresperf: Performance improvementstest: Adding or modifying testschore: Maintenance tasks, dependency updates, etc.style: Code style changes (formatting, missing semicolons, etc.)build: Changes to build system or dependenciesci: Changes to CI configuration files and scripts
Scope Guidelines
- Scope is OPTIONAL: only add when it provides clarity
- Use lowercase, placed in parentheses after type:
feat(transcription): - Prefer specific component/module names over generic terms
- Your current practice is good: component names (
EditRecordingDialog), feature areas (transcription,sound) - Avoid overly generic scopes like
uiorbackendunless truly appropriate
When to Use Scope
- When the change is localized to a specific component/module
- When it helps distinguish between similar changes
- When working in a large codebase with distinct areas
When NOT to Use Scope
- When the change affects multiple areas equally
- When the type alone is sufficiently descriptive
- For small, obvious changes
Description Rules
- Start with lowercase immediately after the colon and space
- Use imperative mood ("add" not "added" or "adds")
- No period at the end
- Keep under 50-72 characters on first line
Breaking Changes
Mark a breaking change with ! after the type or scope, as in feat(api)!: change endpoint structure, and say what breaks in a BREAKING CHANGE: footer.
Examples Following Your Style:
feat(transcription): add model selection for OpenAI providersfix(sound): resolve audio import paths in assets modulerefactor(EditRecordingDialog): implement working copy patterndocs(README): clarify cost comparison sectionchore: update dependencies to latest versionsfix!: change default transcription API endpoint
Commit Messages Best Practices
The "Why" is More Important Than the "What"
The commit message subject line describes WHAT changed. The commit body explains WHY.
Good commit (explains motivation):
fix(auth): prevent session timeout during file upload
Users were getting logged out mid-upload on large files because the
session refresh only triggered on navigation, not background activity.
Bad commit (only describes what):
fix(auth): add keepalive call to upload handler
The first commit tells future developers WHY the code exists. The second makes them dig through the code to understand the purpose.
Other Best Practices
- NEVER include Claude Code or opencode watermarks or attribution
- Each commit should represent a single, atomic change
- Keep skill and agent-instruction changes in dedicated commits, separate from app and package changes, so they can be cherry-picked onto local
main. - Write commits for future developers (including yourself)
- If you need more than one line to describe what you did, consider splitting the commit
What NOT to Include:
Generated with [Claude Code](https://claude.ai/code)Co-Authored-By: Claude <noreply@anthropic.com>- Any references to AI assistance
Generated with [opencode](https://opencode.ai)Co-Authored-By: opencode <noreply@opencode.ai>- Tool attribution or watermarks