Claude Code Git Workflow: Commits, Branches, and Pull Requests

Handing an AI agent access to git is different from handing it access to a text editor. A bad edit is a diff you can undo. A bad git push --force or a squash of someone else's unreviewed commit can lose work permanently. Claude Code is genuinely useful for git — it writes better commit messages than most humans do at 5pm on a Friday, and it can draft a pull request description that actually explains why a change happened — but only if you set it up with the right conventions and guardrails from day one.

This guide covers the parts of the git workflow where Claude Code earns its keep, the commands worth knowing, and the specific things to lock down so a helpful agent never becomes a destructive one.

Why Git Workflow Discipline Matters More With an AI Agent

When you write a commit message yourself, you're slow but you know exactly what you did. When Claude writes dozens of commits a day across a fast-moving branch, three problems show up that don't exist in a human-only workflow:

None of this is a reason to avoid using Claude Code for git. It's a reason to be deliberate about the first ten minutes of setup.

Step 1 — Set Your Commit Convention in CLAUDE.md

Claude Code reads a project's CLAUDE.md file at the start of every session. This is the single highest-leverage place to lock in your git conventions, because it means you never have to repeat them in a prompt again.

markdown## Git Conventions

- Use Conventional Commits format: `type(scope): description`
  - Types: feat, fix, refactor, docs, test, chore, perf
- One logical change per commit — do not bundle unrelated fixes
- Commit messages explain *why*, not just *what* (the diff already shows what)
- Never run `git push --force`, `git reset --hard`, or rewrite history without explicit confirmation
- Always create a new commit rather than amending, unless explicitly asked to amend
- Never skip commit hooks with `--no-verify`

Once this is in CLAUDE.md, every commit Claude makes in that repo follows the same pattern without you asking.

Step 2 — Let Claude Draft Commit Messages From the Actual Diff

The single most common Claude Code git task is: make a change, then ask for a commit. Don't write the message yourself — let Claude read its own diff and summarize it. It's better at this than most developers, because it isn't attached to the code it just wrote and can describe it more objectively.

Review the staged changes and write a commit message following our
CLAUDE.md convention. Focus the message on why this change was made,
not a restatement of the diff.

A good Claude-generated commit message looks like this:

fix(auth): refresh tokens before expiry instead of on 401

Users on slow connections were hitting a race where the token
expired mid-request, causing a hard logout instead of a silent
refresh. Proactively refreshing 60s before expiry avoids the race.

Notice what's absent: no "updated auth.ts", no bullet list of every line changed. That's what git diff is for.

Step 3 — Branching: Give Claude a Naming Convention, Not Just a Task

Branch naming is another place where an unstated convention leads to chaos fast. State it once in CLAUDE.md or in your first prompt of a session:

Branch naming: <type>/<short-description>, e.g. fix/token-refresh-race,
feat/csv-export. Always branch from main unless told otherwise.

For a typical feature, the flow looks like:

bash# Claude creates a branch before starting work
git checkout -b feat/csv-export

# ... Claude makes changes, runs tests, commits incrementally ...

git push -u origin feat/csv-export

Ask Claude to commit incrementally as it completes logical units of work, rather than batching everything into one commit at the end. This gives you a reviewable history instead of one enormous diff.

Step 4 — Reviewing Claude's Own Diffs Before Committing

Before any commit, it's worth having Claude walk its own change back to you in plain language — not because you can't read a diff, but because a one-paragraph explanation surfaces intent mismatches faster than staring at syntax highlighting.

Before committing, summarize what changed and why in 2-3 sentences,
and flag anything in this diff that wasn't explicitly requested.

That last clause matters. It's a direct check against scope creep — if Claude touched a file you didn't expect, you find out before it's in history, not after.

Step 5 — Pull Requests: Description, Not Just a Title

A PR description written from the actual commit history is far more useful than one written from memory of "what we were trying to do." Ask Claude to generate it from the diff against the base branch, not from the conversation:

Draft a PR description from the full diff between this branch and main.
Include: a Summary (2-3 bullets), a Test Plan as a markdown checklist,
and nothing else — no marketing language, no restating the title.

Guardrails: What to Lock Down Before You Let Claude Touch Git

These aren't optional extras — they're the difference between "Claude speeds up my git workflow" and "Claude force-pushed over three days of a teammate's work."

• Never allow force-push to shared branches. State this explicitly in CLAUDE.md; don't rely on Claude inferring it.
• Always create new commits instead of amending, unless you explicitly ask for an amend. If a pre-commit hook fails, the commit didn't happen — amending would silently target the previous commit instead.
• Never skip hooks (--no-verify, --no-gpg-sign) unless you explicitly request it. If a hook is blocking a commit, the fix is to resolve the hook's complaint, not bypass it.
• Run git status before any destructive command (checkout ., reset --hard, clean -f) so uncommitted work is never silently discarded.
• Review what's staged before committing, especially after a broad git add . — it's the easiest way for a .env file or credential to end up in history.

Common Mistakes to Avoid

• Skipping the CLAUDE.md convention setup. Without it, every session reinvents commit message style, and your log becomes unsearchable.
• Asking for one giant commit at the end of a session. You lose the ability to bisect or revert a single logical change — ask for incremental commits instead.
• Treating PR descriptions as a formality. A description generated from the actual diff is documentation your team will thank you for in six months.
• Assuming "confirm before destructive actions" is the default. State it explicitly — don't assume an agent will treat git reset --hard with the same caution you would.
• Letting commit messages restate the diff. If the message could be inferred by reading the code, it's not adding value — the why is the only part worth writing down.

Key Takeaways

• Put your commit and branch conventions in CLAUDE.md once — it removes the need to repeat them every session.
• Let Claude generate commit messages and PR descriptions from the actual diff, not from memory of the conversation.
• Ask explicitly for a scope-creep check before every commit — it's the cheapest bug-catcher in the workflow.
• Lock down force-push, history rewrites, and hook-skipping as explicit no-gos, not assumed defaults.
• A disciplined git workflow with Claude Code produces a more reviewable history than most solo-developer habits, not less — but only with the guardrails in place.

Next Steps

Git workflow discipline, tool permissions, and agent guardrails are exactly the kind of applied-judgment scenarios tested on the Claude Certified Architect (CCA) exam — questions rarely ask "what does this command do," they ask "what should the agent be allowed to do here." If you're studying for certification, try a free practice question on AI for Anything to see how these scenarios show up in exam form.