Checkpoint Workflow for Long Tasks

Break long agent runs into committed checkpoints you can bisect and revert.

WorkflowIntermediate

Why

GitHub's 2024 enterprise survey of 2,000 developers found 97% have used AI coding tools at work, and Stack Overflow's 2024 survey found 76% of developers use or plan AI tools (up from 70%). A 30-minute autonomous run that ends broken is unrecoverable.

Checkpoints (commit per step, gate after each) turn it into a bisectable history where you can revert exactly the bad step.

When

Use checkpoints for any task >5 steps or >10 minutes. Skip for quick one-shot edits.

How

1. Create a dedicated branch. 2. After each logical step: run gate, commit if green, stop if red. 3. Use conventional commits so the history reads as a plan. 4. On red, paste the error back; fix; continue. 5. Merge with --no-ff to preserve the step history.

Example

git checkout -b feat/books-hub [step 1: data layer] tsc green → commit [step 2: API route] tsc green → commit [step 3: page] tsc red → paste error → fix → green → commit git log --oneline shows 3 bisectable commits; revert step 3 alone if needed.

Common Problems

⚠Error: Cannot find module 'xxx' → run `npm install xxx` (or `pnpm add xxx`); verify it is in package.json dependencies.
⚠Error: "Command not found: claude" or "cursor" → ensure the binary is on PATH: `which claude` / `which cursor`; reinstall globally if missing.
⚠TypeError: Cannot read properties of undefined (reading 'x') → add a null guard or optional chaining `obj?.x`; trace the undefined source via the stack.

Best Practices

✓Commit per logical step with conventional messages.
✓Run the full gate (check + test + build) before each commit.
✓Measure the outcome with a concrete metric (time saved, defect rate, test coverage) so the practice can be justified and improved.

FAQ

What is Checkpoint Workflow for Long Tasks?

Break long agent runs into committed checkpoints you can bisect and revert. It helps developers quickly grasp the core value and use cases of Checkpoint Workflow for Long Tasks.

How do I get started with Checkpoint Workflow for Long Tasks?

To get started with Checkpoint Workflow for Long Tasks, focus on these points first: Create a dedicated branch.

What are common mistakes with Checkpoint Workflow for Long Tasks?

Common mistakes when using Checkpoint Workflow for Long Tasks include: Error: Cannot find module 'xxx' → run `npm install xxx` (or `pnpm add xxx`); verify it is in package.json dependencies.; Error: "Command not found: claude" or "cursor" → ensure the binary is on PATH: `which claude` / `which cursor`; reinstall globally if missing.; TypeError: Cannot read properties of undefined (reading 'x') → add a null guard or optional chaining `obj?.x`; trace the undefined source via the stack..

What are the best practices for Checkpoint Workflow for Long Tasks?

Best practices for Checkpoint Workflow for Long Tasks include: Commit per logical step with conventional messages.; Run the full gate (check + test + build) before each commit.; Measure the outcome with a concrete metric (time saved, defect rate, test coverage) so the practice can be justified and improved..

How do I learn more about Checkpoint Workflow for Long Tasks?

Start with the official docs, then search real-world examples on GitHub. Validate patterns in a small scratch repo before applying them to production code.