What This Does

This playbook establishes a structured git commit workflow with quality gates. Before committing, verify the build passes, write meaningful commit messages, and ensure only intentional changes are staged.

Prerequisites

Claude Code installed and configured
A git repository

The CLAUDE.md Template

Copy this into a CLAUDE.md file in your project:

# Git Commit Protocol

## Command
`/commit` — Run the commit workflow with quality checks

## Pre-Commit Checklist

Before staging anything:
- [ ] Build passes (`npm run build` or equivalent)
- [ ] Tests pass (`npm test` or equivalent)
- [ ] Lint passes (`npm run lint` or equivalent)
- [ ] No console.logs or debugger statements in production code
- [ ] No secrets/credentials in committed files
- [ ] Changes match intended task

## Staging Rules

**Stage intentionally:**
```bash
git add [specific files]    # Good: Intentional
git add .                   # Dangerous: May include unintended files

Always review before committing:

git status                  # What's staged?
git diff --staged           # What exactly are the changes?

Exclude patterns:

.env files — Never commit
node_modules/ — In .gitignore
Build artifacts — Usually in .gitignore
Large binary files — Use LFS or exclude

Commit Message Format

<type>: <subject>

[optional body]

[optional footer]

Types

feat: New feature
fix: Bug fix
refactor: Code restructure (no behavior change)
docs: Documentation only
test: Adding/updating tests
style: Formatting (no code change)
chore: Maintenance (deps, build, etc.)

Subject Rules

Imperative mood: "Add feature" not "Added feature"
Under 50 characters
No period at end
Capitalize first letter

Body Rules (if needed)

Blank line after subject
Wrap at 72 characters
Explain "why" not "what" (code shows what)

Examples

Good:

feat: Add user authentication with JWT

Implemented login/logout with JWT tokens stored in httpOnly cookies.
Chose cookies over localStorage for XSS protection.

Closes #123

Bad:

updated some stuff

Commit Workflow

Step 1: Review Changes

git status
git diff

Step 2: Run Quality Checks

npm run build
npm test
npm run lint

Step 3: Stage Selectively

git add src/components/Auth.tsx
git add src/hooks/useAuth.ts

Step 4: Review Staged

git diff --staged

Step 5: Commit with Message

git commit -m "feat: Add JWT authentication"

Step 6: Verify

git log -1  # Check commit looks right

Common Mistakes

Mistake: Committing broken code Fix: Always run build/tests before committing

Mistake: Committing too much at once Fix: Small, focused commits (one logical change each)

Mistake: Vague commit messages Fix: Follow the format. Future you will thank present you.

Mistake: Committing secrets Fix: Use .gitignore, pre-commit hooks, and review diffs carefully

PR-Ready Commits

When preparing for a pull request:

Each commit should be atomic (one logical change)
Each commit should pass tests independently
Consider squashing WIP commits before PR
Rebase on main to avoid merge commits

Quality Score for Commits

Before committing, score against:

Score 80+ to commit. Below 80, fix issues first.


## Step-by-Step Setup

### Step 1: Add to your CLAUDE.md

Add the commit protocol to your project's CLAUDE.md.

### Step 2: Test the workflow

Make a small change, then:

/commit


Claude should guide you through the full workflow.

## Example Usage

**User:**
> "/commit"

**Claude:**
> ## Commit Workflow
>
> ### Step 1: Review Changes
> ```bash
> $ git status
> Modified: src/components/Button.tsx
> Modified: src/styles/button.css
> Untracked: src/components/Button.test.tsx
> ```
>
> ### Step 2: Quality Checks
> - Build: ✓ Passed
> - Tests: ✓ 47/47 passing
> - Lint: ✓ No errors
>
> ### Step 3: Review Diff
> Changes look intentional:
> - Button.tsx: Added loading state prop
> - button.css: Loading spinner styles
> - Button.test.tsx: Test for loading state
>
> ### Step 4: Proposed Commit
> ```
> feat: Add loading state to Button component
>
> Added isLoading prop that shows a spinner and disables the button.
> Includes accessibility attributes (aria-busy, aria-disabled).
> ```
>
> **Quality Score: 90/100**
>
> Stage all 3 files and commit with this message?

**User:**
> "Yes, commit"

**Claude:**
> ```bash
> $ git add src/components/Button.tsx src/styles/button.css src/components/Button.test.tsx
> $ git commit -m "feat: Add loading state to Button component
>
> Added isLoading prop that shows a spinner and disables the button.
> Includes accessibility attributes (aria-busy, aria-disabled)."
>
> [main a1b2c3d] feat: Add loading state to Button component
>  3 files changed, 45 insertions(+), 2 deletions(-)
>  create mode 100644 src/components/Button.test.tsx
> ```
>
> Committed successfully.

## Tips

- **Small commits > big commits**: Easier to review, revert, and understand.
- **Don't commit WIP**: Use stash or a WIP branch instead.
- **Review your own diff**: Catch accidental changes before they're committed.
- **Use conventional commits**: The format enables auto-changelogs and semantic versioning.

## Troubleshooting

**Problem**: Accidentally committed a secret

**Solution**: Immediately: `git reset HEAD~1`, remove secret, re-commit. If pushed, rotate the secret immediately — it's compromised.

**Problem**: Commit is too big

**Solution**: For future commits, commit more frequently. For past commits, consider interactive rebase to split.

**Problem**: Commit message doesn't follow format

**Solution**: Use `git commit --amend` to fix the message (only before pushing).

Git Commit Workflow