DEV Community

Zac
Zac

Posted on

How I structure long tasks so Claude Code doesn't lose the thread

#ai #claudecode #programming #productivity

How I structure long tasks so Claude Code doesn't lose the thread

Long tasks go wrong at handoffs. Not because the agent forgets — it doesn't, until context runs out — but because the task wasn't structured for recovery in the first place.

Here's what I've found works.

Break the task before you start the session

Not during. Before.

I keep a task file at tasks/current-task.md. It has a goal statement, an ordered list of steps, and a checkpoint field. I write this before I start the session, not after I've already begun.

The step list is the key part. Each step should be independently verifiable — meaning I can tell, from the output alone, whether it's done. "Implement authentication" is not a step. "Add JWT validation middleware to routes/api.js that returns 401 for missing or invalid tokens" is.

The checkpoint pattern

After each step, the agent writes one line to last_checkpoint:

"Added JWT middleware to routes/api.js. Tests pass. Next: add refresh token endpoint."
Enter fullscreen mode Exit fullscreen mode

If the session ends mid-task (context overflow, container restart, anything), the next session reads this file first. One line tells it exactly where to pick up. No reconstruction needed.

Step granularity

Steps that are too large cause the same problems as vague prompts: the agent decides what "done" means, and sometimes it decides wrong.

I aim for steps that take 3-5 commits each. Anything that produces 20 commits in a row was probably two or three steps that should have been broken apart.

If I'm not sure how to break a task, I ask the agent to propose the breakdown before starting: "Here's the goal. Before writing any code, give me a list of 5-10 specific, testable steps." The proposed breakdown is usually pretty good, and reviewing it catches scope problems before the work starts.

What to do when a step is blocked

Write it. Specifically.

## Blocked
step: "Add refresh token endpoint"
reason: "Refresh token rotation logic is ambiguous — unclear whether to invalidate all previous tokens or just the one being refreshed"
tried: "Implemented single-token invalidation, but this conflicts with test expectations in auth.test.js line 47"
need: "Decision on rotation behavior before proceeding"
Enter fullscreen mode Exit fullscreen mode

A well-written block is worth more than a workaround. The workaround produces code that's wrong in a way that's hard to find later. The block surfaces a real decision that needs to be made.

Context overflow

At 80% context, write the checkpoint and stop the task. Start a new session that reads the checkpoint file first.

The mistake is pushing to 100%. A session that runs to the limit can't write anything — it just ends. All the state about what's in progress, what decisions were made mid-task, what the next step is: gone. An orderly handoff at 80% keeps all of that.

The pattern in plain terms

  1. Write the task file before starting
  2. Break it into specific, verifiable steps
  3. Write a checkpoint after each step
  4. Write a clear block description when stuck, rather than a workaround
  5. Handoff at 80% context, not 100%

None of this is complicated. The sessions that go wrong usually skipped one of these five things.

From running Claude Code autonomously for weeks on builtbyzac.com.

Top comments (0)