Lesson 330 of 2116
Bisecting Bugs With AI Help
Git bisect is a precision tool — and AI agents are excellent bisecters. Learn to structure a bisect session with an agent, including auto-bisect with an AI-written test script.
Lesson map
What this lesson covers
Learning path
The main moves in order
- 1When the Bug Was Born
- 2git bisect
- 3regression
- 4binary search
Concept cluster
Terms to connect while reading
Section 1
When the Bug Was Born
A regression is a bug that didn't used to be there. Knowing when it appeared is more than half the fight. `git bisect` performs binary search through your history, asking you to mark each commit good or bad until it finds the first bad one. AI agents are surprisingly good at running this loop for you.
The 5-step manual bisect
Manual bisect, the textbook flow. AI changes step 2 and step 3 dramatically.
# 1. Start the bisect at a known-bad and a known-good commit
git bisect start
git bisect bad HEAD # current commit is broken
git bisect good v2.4.0 # last release was fine
# Git checks out a middle commit and waits for your verdict.
# 2. Test it. Either run a script, run the app, or both.
npm test -- --grep "login flow"
# 3. Tell git what you found
git bisect bad # or `good` if the test passed
# 4. Repeat (5-7 iterations for ~100 commits)
# 5. When done
git bisect resetWhere AI plugs in
Compare the options
| Step | Manual | With AI |
|---|---|---|
| Decide good vs bad | You run the test, eyeball output | Agent runs the test and reports verdict |
| Diagnose between commits | You diff the commits, read the changes | Agent summarizes commit diffs and risk areas |
| Write the repro test | You write it before bisecting | Agent generates a minimal repro from your bug report |
| Final root cause | You read the offending diff | Agent explains why that diff broke things |
AI-assisted automated bisect
`git bisect run` takes a script and runs it on each candidate commit. The script's exit code (0 = good, non-zero = bad) decides the verdict. Have an AI agent write the script for you, then unleash bisect on it.
The agent writes the test, git does the search. You drink coffee.
# Step 1: ask the agent to write a minimal repro script
# Prompt: "Write a bash script test-regression.sh that exits 0
# if our login redirects to /dashboard, and 1 if it 500s.
# Use curl. No browser. Save the response."
# Step 2: make sure the script works on HEAD (should fail) and on v2.4.0 (should pass)
chmod +x test-regression.sh
./test-regression.sh; echo $? # 1
git checkout v2.4.0
./test-regression.sh; echo $? # 0
# Step 3: run automated bisect
git bisect start HEAD v2.4.0
git bisect run ./test-regression.sh
# Git crawls the history, runs the script per commit,
# and prints the first bad commit when done. ~30 seconds for 100 commits.Common bisect failures and AI fixes
- Test fails for unrelated reasons (missing dep) — agent re-runs `npm install` per commit
- Old commits don't build — agent marks those as `git bisect skip`
- Bug is intermittent — agent runs the test 5 times and votes majority
- Bug needs DB state — agent reseeds the DB before each test
End-to-end automated regression hunt — works in any git project.
# Useful prompt to a Claude Code session
"I have a regression. Bug: <description>.
Steps to reproduce: <steps>.
1. Find the last commit where this worked (assume it's tagged or in the last 200 commits).
2. Write a minimal bash script test-regression.sh that returns 0/1 based on whether the bug is present.
3. Validate the script works on HEAD (returns 1) and on the suspected good commit (returns 0).
4. Run `git bisect run ./test-regression.sh` and report the first bad commit.
5. Open that commit's diff and summarize, in 3 bullets, why this change introduced the bug."After the bisect
Once the agent finds the first bad commit, the next prompt is gold: "Read the diff of <commit-hash>. Explain in plain English what changed, why someone made that change, and the most surgical fix that preserves the original intent." You get history, intent, and a fix in one turn.
“Bisect is the closest thing software has to a time machine.”
Key terms in this lesson
The big idea: bisect plus AI agent equals a near-automated regression detective. Spend your effort writing a tight repro script and let the machinery handle the search. The first-bad-commit you find is usually so small the fix is obvious.
End-of-lesson quiz
Check what stuck
15 questions · Score saves to your progress.
Tutor
Curious about “Bisecting Bugs With AI Help”?
Ask anything about this lesson. I’ll answer using just what you’re reading — short, friendly, grounded.
Progress saved locally in this browser. Sign in to sync across devices.
Related lessons
Keep going
Creators · 11 min
AI-Assisted Git Bisect and Regression Hunting
Use Claude to narrow bisect ranges using commit messages, diffs, and CI history.
Creators · 12 min
Test-Driven Prompting — Failing Tests Are the Best Spec
Test-driven development meets AI: paste a failing test, ask the agent to make it green, iterate. Learn the discipline that makes AI code reliably correct because correctness is now executable.
Creators · 14 min
Debug With Error Receipts
Do not tell the AI 'it broke.' Bring receipts: URL, action, expected result, actual result, console error, network error, and the exact time it happened.