Part of Mechanisms of Vibe Coding

Mechanism: Checkpoint

One-sentence definition

A checkpoint is a mandatory pause — human or automated — between agent output and merge, where you review the diff, re-run checks, and explicitly approve or reject before changes become permanent.

The problem

The agent loop passes verify. You are tired. You click merge because green tests and a confident summary feel enough. Later you find a debug flag, a widened permission, or a dependency you would never have approved if you had read the diff.

Automation can verify; it cannot replace judgment on intent. Checkpoints catch “technically passes tests but wrong for the product” — and completion bias when the agent stopped talking and you treated that as ship approval.

Symptoms:

• Merges without reading the full diff
• Surprises in review from teammates who were not in the chat
• Tests pass but behavior changed in ways stakeholders did not expect
• No record of who approved agent-generated changes

How it works

Insert a gate after verify, before merge:

  Agent output + verify pass
       │
       ▼
  Checkpoint (review diff + intent + risk)
       │
       ├── approve ──► merge / commit
       │
       └── reject ──► revert or re-prompt with feedback

A useful checkpoint answers four questions:

1. Diff — What files changed? Anything out of scope or constraints?
2. Intent — Does this still match the goal?
3. Risk — Auth, payments, PII, deletes, new deps, config?
4. Evidence — Verify output from this session, not the agent’s description?

Checkpoints can be solo (you with a checklist), pair (second human on risky PRs), or automated (required CI + CODEOWNERS + no direct push to main).

When to use it

• Every agent-generated PR or commit you did not write line-by-line
• Security-sensitive, data-handling, or infra changes
• After any loop longer than two passes
• Team repos with review culture — treat agent work like junior contributor work

When not to use it

• Throwaway sandbox with no shared branches — still verify, but checkpoint can be lighter
• Changes you personally typed and only used AI for autocomplete — review as normal human code
• Replacing verify with “someone glanced at it” — checkpoint adds intent review, not duplicate test runs

Failure modes

Rubber stamp — Checkpoint exists but diff unread. Fix: Minimum bar: scan every changed file name and skim hunks.

Checkpoint before verify — Reviewing code that still fails tests. Fix: Verify first, checkpoint second.

Checkpoint only on big diffs — Small diffs smuggle risky one-liners. Fix: Same gate for small agent changes; size is not safety.

No reject path — Approve-only habit. Fix: Keep rollback ready; rejection is normal.

Stale checkpoint — Approved diff, then agent edited again. Fix: Re-checkpoint after any new agent pass.

Minimal example

Context: Health endpoint fix verified green — ready to commit.

Steps:

1. Run verify one more time yourself: npm test -- health.test.ts.

1. Checkpoint checklist (30 seconds):

– Files: only health.ts, bootstrap.ts?

– Intent: returns ok: true after startup — matches goal?

– Risk: no new deps, no env secrets, no broad refactors?

– Evidence: paste test output in PR description or commit message?

1. If any box fails → do not commit; revert or re-prompt. If all pass → commit with message referencing the goal.

Done when: You can point to the checkpoint moment — not “I think I looked.”

Tool instances (optional deep-dive)

Portable idea above; this section is tool-specific. Date: June 2026.

Cursor

• Use Source Control diff view before accept-all; reject hunks outside fence.
• Plan mode checkpoint: approve plan before Agent executes — design gate before code gate.
• PR workflow: Agent branch → you review in GitHub/GitLab → merge; never push straight to main for agent loops.
• Rules: “Summarize diff and risks before asking me to commit.”

Other tools

GitHub required reviews, pre-merge hooks, git diff --stat in CI comments — checkpoints as process.

Related mechanisms

• Verify loop — runs before the checkpoint gate
• Rollback / snapshot — what to do when checkpoint fails
• Completion bias — checkpoint counteracts premature “done”

Try it yourself

Exercise: After your next agent fix, run a written four-question checkpoint before commit. Answer each in one sentence in a scratch note or PR template.

You need: One verified agent diff; two minutes

Done when: You either committed with four answers recorded or rejected with a specific reason (not “felt wrong”).