“It worked last week.” Those four words signal the start of a debugging session nobody wants. A bug appeared, production is affected, and somewhere in the last few hundred commits lives the one change that caused it. Most engineers start guessing. The right move is to stop guessing and let a binary search do the work.
Git bisect is a built-in Git command that has existed since 2007. It finds the precise commit that introduced a regression in roughly log2(n) steps. Pair it with Claude Code and the entire loop — from writing the test script to explaining the root cause — runs without you. This is AI-augmented debugging at its most precise: the binary search algorithm does what algorithms do best, and the senior engineer’s judgment handles what algorithms cannot.
1. What git bisect Actually Does
Git bisect runs a binary search through your commit history. It needs two anchor points: a bad commit where the bug exists, and a good commit from before the bug appeared. Git checks out the midpoint, waits for the engineer’s verdict, then discards half the remaining range and repeats.
The Old Way: An engineer manually checks out commits, runs a test, notes the result, picks the next commit, repeats. For 400 commits, that could mean 200+ manual steps. For 400 commits, git bisect needs about 9.
The GoTeams Way: One bad commit is marked, one good commit, and hand the rest to the algorithm. Core workflow:
- git bisect start
- git bisect bad — HEAD is broken
- git bisect good v1.4.0 — last known-good release
- Git checks out commits halfway through history and asks: good or bad?
- When one commit remains, that is the culprit — with its full hash, author, timestamp, and diff
The session ends with git bisect reset, which returns the engineer to their starting branch. Always run it. Skipping it leaves you on a detached HEAD somewhere in the middle of history.
2. The Automation Lever: git bisect run
Manual bisect is already fast. Automated bisect is the real power move.
git bisect run accepts a script that returns exit code 0 for a good state and any non-zero code for a bad state. Git checks out each midpoint, runs your script, reads the exit code, and marks the commit good or bad automatically — all the way to the culprit, without any human input per step.
The test script is the critical piece. It needs to be deterministic: the same commit should produce the same exit code on every run. Non-deterministic tests produce unreliable bisect results. A flaky good/bad answer sends the search down the wrong half. This automation contract is exactly what Claude Code uses to drive the bisect loop end-to-end.
3. Where AI-Orchestrated Debugging Changes the Game
Git bisect finds the commit. It does not explain the why. That gap is where AI-augmented engineering adds its real value.
The standard workflow without AI: git bisect terminates, you have a commit hash, you read the diff, you reason about why that specific change broke the behaviour, you trace the consequence through the codebase, and you decide whether to revert or patch. For a subtle regression in a complex system, that reasoning step can take longer than the bisect loop itself.
With Claude Code:
- The AI writes the test script. You describe the failure in plain language: the error message, the failing route, the header, the port. Claude Code turns that into a bash script with the correct exit code contract. Specific symptoms produce reliable scripts.
- The AI drives the loop. Git bisect runs automatically. You do not type good or bad for each step.
- The AI reads the diff. Once the culprit commit is identified, Claude Code reads the change and explains which specific line or logic caused the regression — not just which commit, but why.
- The AI suggests the fix. The final output is a minimal patch recommendation, not just a problem statement.
The critical constraint that makes this work: you must instruct Claude Code to use only git bisect to identify the culprit. Without this explicit constraint, an AI agent might shortcut by reading git blame or scanning recent diffs. That guess is sometimes right. It is also wrong often enough to be unreliable, and the whole point of bisect is to eliminate guesswork entirely.
4. The Prompt Pattern That Works
The prompt below is a working template. The structure is deliberate:
I have a bug in my backend project. The authorization middleware at src/middlewares/authorization.js crashes with ReferenceError: token is not defined on every request. It was working last week but is broken on HEAD now. Failing route: GET /api/users/2. Header required: Authorization: Bearer. Server runs on: port 3000.
Constraint: Use ONLY git bisect to locate the culprit commit. Do NOT use git log inspection, git blame, manual diff reading, or any other heuristic to guess the commit. The commit MUST be identified by a git bisect run that finishes with [hash] is the first bad commit.
Please: 1. Check git log only to identify a reasonable last-known-good commit. 2. Write a small test script that reproduces the failure and returns exit code 0 when good and non-zero when bad. 3. Run git bisect run automatically with HEAD as bad. 4. Show me the full diff of the culprit commit bisect identifies. 5. Explain exactly what in the diff caused the error. 6. Suggest the minimal fix. 7. Run git bisect reset when finished.
Each element earns its place. The precise error message gives the AI enough context to write a reliable test. The explicit constraint prevents shortcuts. Steps 4 through 6 turn which commit into which line, why, and how to fix it.
5. Beyond Bugs: Where Else Bisect Applies
The algorithm does not care what it is searching for. As long as your test script can reliably return good or bad, bisect finds the transition point.
- Performance regressions. An API endpoint went from 80ms to 600ms and nobody knows when. Write a script that fails if response time exceeds a threshold. Bisect finds the commit that slowed it down.
- Build time blowups. CI used to finish in four minutes and now takes eighteen. Bisect on a script that fails when the build exceeds your time budget.
- Bundle size creep. Your frontend production bundle grew by 2MB. Bisect on bundle size to catch the dependency that caused it.
- Behavioural output changes. A report’s numbers shifted, an export format changed, a feature flag default flipped. If you can write “is this output correct?”, you can bisect it.
Any question you can phrase as “is this commit in the state I expect?” is a candidate for bisect.
6. What git bisect Cannot Do (And Why That Matters)
- Bisect finds which commit introduced a change. It does not tell you why the developer made that change, whether the change was intentional, or what the correct fix is. That reasoning belongs to a senior engineer, or to an AI acting with the knowledge of a senior engineer.
- Bisect requires a genuinely good starting point. If the bug existed from the project’s first commit, there is no good anchor to bisect toward.
- Bisect is not useful for non-deterministic bugs unless the test script is made deterministic first. A test that passes flakily gives bisect wrong information and sends the search in the wrong direction.
- Bisect does not fix anything. It identifies the culprit commit. What happens next — revert, patch, or architectural rework — is a judgment call that the algorithm cannot make.
This is the pattern at the centre of AI-orchestrated engineering: the automation handles the reliable, repeatable, algorithmic steps. The judgment about what the correct behaviour should be, and how to restore it, belongs to someone who understands the system.
7. Frequently Asked Questions
Q: How many steps does git bisect need to search 1,000 commits?
A: Approximately 10 steps. Git bisect uses a binary search algorithm, which requires roughly log2(n) steps to find a target in a sorted range. For 1,000 commits, that is about 10 steps. For 400 commits, about 9. The larger the history, the more dramatic the win over manual checking. On a codebase with active contributors and hundreds of commits per week, bisect consistently narrows a regression to a single commit in minutes rather than hours.
Q: What is git bisect run and when should I use it?
A: git bisect run is the automated form of bisect. Instead of manually marking each midpoint commit as good or bad, you provide a script that returns exit code 0 for a good state and non-zero for a bad state. Git runs the script at each step and continues automatically until it identifies the first bad commit. Use it whenever you can express the bug as a deterministic test. If your test is flaky, fix it before running bisect.
Q: Can I use git bisect with Claude Code for any type of regression?
A: Yes, as long as the regression is detectable by a script. Bisect works equally well for functional bugs, performance regressions, build size changes, and output correctness. What matters is that the test script returns a consistent exit code for any given commit. Claude Code writes that test script from a plain-language symptom description, drives the bisect loop, reads the resulting diff, and explains the root cause.
Q: Why do I need to constrain Claude Code to use only git bisect?
A: Without an explicit constraint, an AI agent may shortcut by reading git blame or scanning recent commits. The point of bisect is to eliminate guesswork entirely and produce a verified answer backed by binary search. The constraint forces the AI to follow the rigorous path. This matters most for subtle regressions where the culprit commit looks unrelated to the symptom.
Q: What should I do after git bisect identifies the culprit commit?
A: Read the diff, understand the change, and decide whether to revert or patch. Revert is faster but may undo intentional work. A targeted patch preserves the changes that were correct. Claude Code can help: it reads the diff, explains which specific line caused the regression, and proposes the minimal fix. The final decision requires someone who understands the system.
The Bottom Line
If the codebase is small and you have a strong intuition about which recent commit caused the issue, checking two or three commits by hand is fine. But for any codebase with real commit history, guessing does not scale. Git bisect turns “somewhere in the last 400 commits” into a precise, single culprit in about 9 steps. Automate the test with git bisect run and the loop runs without you. Hand the whole workflow to Claude Code and you get the culprit, the root cause, and the fix before your coffee gets cold.
GoTeams AI Bootcamp runs this playbook as part of the practical curriculum for engineers building with AI in production. Binary search handles the algorithmic work. Engineering judgment handles the rest. That combination is what GoTeams calls AI-orchestrated engineering: AI doing what automation does best, humans doing what judgment does best.
Leave a Reply