Guide Commit Navigator
A agent template for git workflows. Streamlines development with pre-configured patterns and best practices.
Commit Navigator Guide
Your agent for writing clear, consistent git commits — covering commit message conventions, atomic commits, interactive staging, and commit best practices for team collaboration.
When to Use This Agent
Choose Commit Navigator Guide when:
- Writing descriptive, well-structured commit messages
- Creating atomic commits that each represent a single logical change
- Using conventional commit format for automated changelog generation
- Reviewing commit history for quality and consistency
- Training teams on git commit best practices
Consider alternatives when:
- You need git branching strategy — use a Git Flow Manager agent
- You need PR creation and review — use a code reviewer agent
- You need CI/CD pipeline setup — use a DevOps agent
Quick Start
# .claude/agents/commit-navigator.yml name: Commit Navigator Guide model: claude-sonnet tools: - Read - Write - Edit - Bash - Glob - Grep description: Git commit guide for writing clear messages, creating atomic commits, and following conventional commit standards
Example invocation:
claude "Review my staged changes and suggest well-structured commit messages following conventional commit format — split into logical atomic commits if the changes cover multiple concerns"
Core Concepts
Conventional Commit Format
<type>(<scope>): <subject>
<body>
<footer>
Types:
feat: New feature
fix: Bug fix
docs: Documentation only
style: Formatting (no logic change)
refactor: Code change (no feature/fix)
perf: Performance improvement
test: Adding/modifying tests
chore: Build, tooling, dependencies
Examples:
feat(auth): add SSO login with SAML2 support
fix(cart): prevent duplicate items on rapid add
refactor(api): extract validation into middleware
Atomic Commit Principles
| Principle | Description | Example |
|---|---|---|
| Single purpose | One logical change per commit | Separate refactor from feature |
| Self-contained | Commit works independently | Don't break the build mid-commit |
| Reviewable | Easy to review in isolation | Keep diffs focused and readable |
| Revertable | Can be reverted without side effects | No unrelated changes bundled |
Configuration
| Parameter | Description | Default |
|---|---|---|
convention | Commit format (conventional, angular, custom) | conventional |
scope_required | Require scope in commits | false |
max_subject_length | Maximum subject line length | 72 |
body_required | Require commit body | false |
breaking_change_format | Breaking change notation | footer |
Best Practices
-
Write the subject line as an imperative command. "Add search endpoint" not "Added search endpoint" or "Adding search endpoint." The subject line completes the sentence "If applied, this commit will [subject]."
-
Keep the subject line under 72 characters. Git log, GitHub, and most tools truncate long subject lines. If you can't summarize the change in 72 characters, the commit may be doing too much.
-
Use the body to explain why, not what. The diff shows what changed. The body should explain why the change was necessary, what alternatives were considered, and any context that helps reviewers understand the decision.
-
Create atomic commits, each building on the last. Each commit should leave the codebase in a working state. Avoid WIP commits on shared branches — use interactive rebase to clean up history before pushing.
-
Reference issue numbers in commit messages. "fix(auth): resolve SSO timeout (#1234)" links the commit to the issue tracker. This creates a traceable chain from issue to commit to deployment.
Common Issues
Commits are too large and mix multiple concerns. A single commit with refactoring, a new feature, and a bug fix is hard to review and impossible to revert cleanly. Use git add -p to stage hunks selectively and create separate commits for each concern.
Commit messages are vague and unhelpful. "Fix bug," "Update code," and "WIP" don't help future readers. Every commit message should answer: what changed and why? If you can't write a clear message, the commit may be doing too much.
Teams don't follow commit conventions consistently. Enforce conventions with commitlint and husky pre-commit hooks. Automated enforcement is more reliable than code review — humans miss inconsistencies, tools don't.
Reviews
No reviews yet. Be the first to review this template!
Similar Templates
API Endpoint Builder
Agent that scaffolds complete REST API endpoints with controller, service, route, types, and tests. Supports Express, Fastify, and NestJS.
Documentation Auto-Generator
Agent that reads your codebase and generates comprehensive documentation including API docs, architecture guides, and setup instructions.
Ai Ethics Advisor Partner
All-in-one agent covering ethics, responsible, development, specialist. Includes structured workflows, validation checks, and reusable patterns for ai specialists.