majiayu000 Atomic Commits
Creates well-structured, semantic commits following Conventional Commits specification. Automatically analyzes changes and creates atomic, focused commits.
Core Principles
- Atomic: Each commit represents ONE logical change
- Semantic: Type prefix describes the nature of the change
- Scoped: Optional scope indicates the affected module/component
- Descriptive: Message explains WHAT and WHY, not HOW
Workflow
Step 1: Analyze Changes
Run these commands to understand the current state:
git status
git diff --staged
git diff
Step 2: Identify Commit Types
For each logical change, determine the appropriate type:
| Type | When to Use |
|---|---|
feat |
New feature for the user |
fix |
Bug fix for the user |
docs |
Documentation only changes |
style |
Formatting, missing semicolons (no code change) |
refactor |
Code change that neither fixes a bug nor adds a feature |
perf |
Performance improvement |
test |
Adding or fixing tests |
build |
Build system or external dependencies |
ci |
CI configuration files and scripts |
chore |
Other changes that don't modify src or test files |
revert |
Reverts a previous commit |
Step 3: Determine Scope
Analyze changed files to suggest scope:
api/→ scope:apicore/database.py→ scope:dbagents/faq_agent/→ scope:faq-agenttests/→ scope:tests- Multiple areas → consider splitting into multiple commits
Step 4: Create Atomic Commits
If changes span multiple concerns, split them:
git add -p # Stage hunks interactively (but explain to user)
Or stage specific files:
git add <specific-files>
git commit -m "<type>(<scope>): <description>"
Step 5: Validate Message Format
Before committing, validate the message follows the pattern:
<type>(<scope>): <description>
[optional body]
[optional footer(s)]
Rules:
- Type is required and lowercase
- Scope is optional, lowercase, in parentheses
- Description starts lowercase, no period at end
- Max 72 characters for first line
- Body wrapped at 72 characters
- Breaking changes: add "!" after type/scope or "BREAKING CHANGE:" in footer
- NEVER add auto-generated labels like "Generated with Claude Code", "Co-Authored-By", or any AI attribution
- Commit messages must be clean and professional, as if written by the developer
Commit Message Template
<type>(<scope>): <short description>
<body - explain WHAT and WHY>
<footer>
Breaking Changes
For breaking changes, use one of:
feat(api)!: change authentication method
feat(api): change authentication method
BREAKING CHANGE: API now requires Bearer token instead of API key
Multi-Commit Strategy
When changes are complex, create separate commits for:
- Preparation: Refactoring needed before the feature
- Core: The main feature/fix implementation
- Tests: New or updated tests
- Docs: Documentation updates
Example sequence:
refactor(auth): extract token validation to separate function
feat(auth): add OAuth2 support
test(auth): add OAuth2 integration tests
docs(auth): update authentication guide
Interactive Mode
When asked to commit, always:
- Show the user what will be committed (files and diff summary)
- Suggest the commit type and scope
- Propose a commit message
- Ask for confirmation before executing
References
See CONVENTIONS.md for detailed type definitions. See EXAMPLES.md for real-world examples.