A git workflow for Claude Code that actually holds up

Why git matters more, not less, with an agent

When you write code by hand, git is a safety net. When Claude Code writes code with you, git is the steering wheel. Every commit is a save point you can return to without ceremony. Every branch is an experiment you can keep or throw out. The agent moves fast, and the speed only pays off if you can roll back any individual change without unwinding the whole session. A clean git workflow is what makes that possible.

Most messy Claude Code sessions are not Claude Code failures. They are git hygiene failures. A six hour session with one giant commit at the end means a six hour bisect when you find a bug. The same session with twenty small commits means a two minute git log and a clean revert. The cost of small commits is almost nothing. The cost of skipping them is felt every time something breaks.

Branch per slice, not per day

Start every meaningful task on its own branch. Not one branch per day, not one branch per project, one per slice of work. A slice is a thing you would describe in a single sentence in standup. Add OAuth login. Refactor the search endpoint. Replace the chart library. Each slice gets a branch off main with a name that matches the slice. When the slice is done, you merge or you throw it out. Either is fine. The point is that the branch exists.

• Name branches with a short kind prefix like feat, fix, or chore, then a slug of the slice
• Keep slice scope tight enough that the branch can live for less than a day
• Push the branch to the remote on the first commit so you have a backup off your laptop
• Open a draft PR early if you work in a team, even before the slice is done
• Delete merged branches the same day, both local and remote, so the list stays readable

Commit cadence that matches the agent

Commit when a small thing works. Not when the feature is done, not when the file is clean, when a small thing works. After the first endpoint returns the right shape. After the migration runs. After the test goes green. Each of these is a save point. The commit message should be short and specific, the kind you would write to your future self at 11pm on a Tuesday. Add reset email route. Fix off by one in pagination. Migrate users table to uuid primary key.

Reading the diff before you stage

Run git diff before you stage and read it. Not because Claude Code did something wrong, but because reading the diff is how you stay in the loop. Two minutes of git diff per commit is the difference between owning the code and reviewing the code. If you can describe every line in the diff in your own words, you understand the change. If you cannot, slow down and ask Claude Code to walk you through it before you stage.

Stash for experiments you might keep

git stash is your low ceremony scratch space. When you want to try a different approach but you are not ready to throw the current one away, stash it. When you want to test a quick hypothesis on a clean tree, stash the dirty work first. Claude Code will happily produce the alternative without touching the stash, and you can pop the stash back if the new approach loses. Stash is the move that lets you experiment without committing nervous work.

1. 1Run git stash push with a message that names what you stashed
2. 2Try the alternative approach with Claude Code on a clean tree
3. 3If the alternative wins, drop the stash with git stash drop and commit the new path
4. 4If the alternative loses, pop the stash back with git stash pop and continue from where you were
5. 5Keep stashes short lived since a stash that lives for days is a bug waiting to happen

Reset for sessions that went sideways

When a session drifts and you realize the last hour produced more confusion than code, the right move is usually git reset. Hard reset to the last good commit, take a breath, restate the goal to Claude Code in one tighter sentence, and try again. The hour you reset is not lost. It is the experiment that taught you what the right prompt is. The second pass at the same slice almost always finishes in less than half the time.

Rebasing and squashing only when it earns you something

You do not have to squash. Twenty small commits in a PR are fine and often easier to review than a single squashed monster. Squash when the small commits include throwaway experiments that do not belong in main history. Rebase against main before you open the PR so the diff is clean against current code. Beyond that, do not optimize git history for aesthetics. Optimize it for recoverability and review.

Using a co author trailer

Many teams want to mark which commits were authored with Claude Code in the loop. A co authored by trailer in the commit message is a clean way to do it. Add one line at the end of the message that says co authored by claude code with a placeholder email. The history then makes clear who pressed enter and what tool participated. This is helpful for code review and for understanding cost per project over time.

Merging to main

Treat merges to main like deploys. The slice works, the tests pass, the PR has been reviewed, you merge. Do not merge a branch you have not run locally. Do not merge a branch with a commented out test. Do not merge to main on the day you are about to take a flight. The boring rules are boring because they keep main shippable, and main being shippable is what lets you start the next slice with confidence. The /guides/deploying-to-vercel-with-claude-code guide picks up from here.

Pick a single merge strategy and stick with it across the project. Squash merges keep history linear and easy to read at the cost of losing the small commits inside the branch. Merge commits preserve everything at the cost of a busier log. Rebase and merge sits in between. Whichever you pick, set it as the default in your repo settings so you do not have to remember the choice each time. Consistency matters more than which option you picked.

Tags and releases

When a project ships its first real release, tag it. git tag with a version number gives you a permanent reference you can come back to. Claude Code can draft release notes from the commit range between tags, which is the fastest part of cutting a release. The discipline pays off when a user reports a bug on a specific version and you can check out the exact commit in seconds. Without tags, you are guessing at what was deployed when, and the guessing compounds across a year of changes.

Hooks that catch problems before push

Local hooks are the cheapest line of defense. A pre commit hook that runs the linter, formats the diff, and runs the smallest test suite catches problems before they ever leave your machine. Claude Code can set this up in one round with husky or whatever your stack prefers. The hook should be fast, under five seconds, so you do not start hating it after a week. Slower hooks belong in CI where you can run them in parallel and not in your face. The point of the local hook is the fast catch, not a comprehensive check.

Working with co authors and reviewers

If you work in a team where some people use Claude Code and some do not, set the same git ground rules for everyone. Branch per slice, small commits, diff review before merge. The tool people use to produce the diff matters less than the discipline they use to ship it. When the rules are shared, the code review process treats Claude Code commits and hand written commits the same way, which is what you want. The reviewer is looking at the change, not the source. If your team needs to know which commits had Claude Code in the loop, the co author trailer covers that without changing the workflow.

Cleaning up after the session

At the end of a long Claude Code session, take five minutes to clean up. Delete dead branches, drop stale stashes, archive the parked todo list if you keep one. The cleanup is small in the moment and saves real cognitive load tomorrow. A clean git status when you sit down is a small gift to yourself. Members at claudecodeclub.ai who report the highest satisfaction with the tool almost always have clean local repos. The correlation is not coincidence. Cleanliness is the rest state that makes the next session start fast.

Writing commit messages worth reading

Commit messages are the only piece of context that follows the code forever. Take ten seconds to write one that explains why, not what. The diff tells you what. The message tells future you why. Add reset email route is a fine title. Add reset email route because the welcome flow blocked recovery is the same title with one phrase that saves a future debugging session. Claude Code can help draft messages from the diff when you are tired, and you can edit before you commit. The combination is much faster than typing the message yourself from a cold start.

Keep the body short or skip it. A long commit body that nobody reads is worse than a tight title. If the change really needs an explanation, put it in the PR description where the discussion lives. Commit messages live in the log forever. PR descriptions live in the conversation. Pick the right home for each piece of context.

Conflicts and how to think about them

Merge conflicts are not failures. They are git telling you that two things changed the same lines and a human has to decide which version wins. Claude Code can help walk through a conflict. Open the file, look at the markers, ask Claude Code to explain what each side was doing, then make the call. Resolve, save, run the tests, commit the merge. The reason conflicts feel painful is usually that the branches drifted for too long. Short branches and frequent rebases against main keep conflicts small and rare.

When a conflict is large enough to feel intimidating, the right move is sometimes to abort. git merge abort or git rebase abort gives you back a clean tree. Pull main fresh, rebase the changes on top, and try again with a shorter range. The conflict was usually a signal that the branch wandered into territory main also wandered into, and starting over with current main as the base produces a smaller conflict set the second time.

What Claude Code changes about authorship

When Claude Code writes a chunk of code and you approve it, who authored that commit? Practically speaking, you did. You specified what to build, you reviewed the diff, you made the decision to commit. The co-author trailer marks that Claude Code participated, but the engineering judgment was yours. This matters for teams that need to track who owns which parts of the codebase. The human who approved and committed the change is the owner. Claude Code is a tool, not a team member with accountability.

Ownership also means understanding. Do not commit code you cannot explain. If Claude Code produced a function and you cannot describe what it does in one sentence, read it until you can. This is not a high bar. It is the minimum that lets you maintain the code next month when you have forgotten the session context. The approval prompt in Claude Code is the moment to ask if anything is unclear. Use it. The alternative is a codebase that grows faster than your understanding of it, which produces maintenance debt that compounds quietly.

Reviewing diffs from a quality perspective

Reading a diff before committing has two purposes. Safety and learning. Safety because a wrong change in a diff is cheaper to catch before the commit than after. Learning because the patterns Claude Code uses are often worth absorbing. When you see a clean functional transformation where you would have written a for loop, take a moment to understand it. When you see an approach you would not have chosen, ask why it was chosen before you accept or reject it. The diff review habit is how you get better at code by using Claude Code rather than faster but shallower.

• Check that the diff changes only what you asked it to change and nothing adjacent
• Confirm imports added at the top of the file match the packages actually in package.json
• Read any new functions in full rather than skipping them because they look reasonable
• Look for deleted code that should not have been deleted - Claude Code sometimes removes things it considers cleanup
• Confirm the change does not touch files outside the scope of the current slice

Long-running projects and git archaeology

Projects that use Claude Code extensively for months end up with rich git histories. The commit messages tell a story of what was built, when, and in what order. Use git log --oneline to read the story periodically. When a bug appears, git log -S 'function name' finds every commit that touched the relevant function. When a behavior changed unexpectedly, git blame shows which commit introduced the line. These built-in git tools are much more powerful on a history with small, well-named commits than on one with a few giant ones.

The claude code CLI session itself leaves no trace in the git history other than the commits you made. That is intentional. Your history records what shipped, not how the conversation went. For debugging purposes, the history is exactly what you need. For learning purposes, keeping a session log in a personal notes file alongside the commits gives you the full picture when you want to review how a particular feature was built.

Integrating linting and formatting into the commit flow

Claude Code produces code in a style that matches the style it observed in the surrounding files. If your project uses Prettier or ESLint, run them before you commit so the diff reflects your actual standards rather than whatever the model happened to produce. A pre-commit hook that runs Prettier and ESLint with --fix is the lowest friction option. The hook runs automatically, fixes minor style issues, and re-stages the changes. You commit clean code without thinking about it.

Set up the formatter and linter configuration before the first Claude Code session on a new project. If you add them after code exists, the first formatter run produces a large noisy diff that obscures the real changes. Starting clean means every subsequent diff is about logic rather than whitespace. The setup costs ten minutes. Trying to retrofit it onto a messy codebase costs much more.

Where this workflow earns its keep

Three months in, the value of this workflow is not the individual commits. It is that you can read your own history and know what each branch was for. You can find the commit that introduced a bug in one git log search. You can revert a regression without rebuilding a week of work. The discipline is small and the compounding is large. The club at claudecodeclub.ai keeps a shared rulebook so you do not have to invent your own from scratch, and the $9 a month buys you the patterns other people already paid for in time.