Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Thread-per-Task

Pattern

A reusable solution you can apply to your work.

Understand This First

  • Context Window – thread-per-task is a response to context window limits.

Context

At the agentic level, thread-per-task is the practice of giving each coherent unit of work its own conversation thread. Rather than running a long, sprawling conversation that covers multiple features, bug fixes, and refactorings, you start a fresh thread for each distinct task.

This pattern is a direct response to the limits of the context window. A long conversation accumulates context (some relevant, some stale) until the window is saturated and the agent begins losing coherence. Thread-per-task keeps each conversation focused, fresh, and manageable.

Problem

How do you prevent agentic sessions from degrading in quality as conversations grow longer and accumulate irrelevant context?

Developers naturally continue existing conversations, adding “one more thing” after the previous task is done. This is convenient but costly. Each completed task leaves behind context (file contents, intermediate reasoning, dead-end approaches) that consumes window space without benefiting the next task. Over time, the agent’s effective memory for the current task shrinks as the accumulated weight of previous tasks grows.

Forces

  • Convenience favors continuing an existing conversation rather than starting a new one.
  • Context carryover: sometimes the next task genuinely benefits from what was discussed earlier.
  • Context pollution: more often, the previous task’s context is irrelevant noise for the next one.
  • Session setup cost: starting a fresh thread means re-establishing project context, though instruction files reduce this cost.

Solution

Start a fresh conversation thread for each distinct task. A “task” is a coherent unit of work with a clear goal: fix a specific bug, implement a defined feature, refactor a module, write tests for a component. When one task is done, close the thread and open a new one for the next.

This doesn’t mean every thread must be short. A complex feature implementation might require a long conversation, and that’s fine, as long as the conversation stays focused on one task. The anti-pattern is a conversation that drifts through multiple unrelated tasks, accumulating context that’s increasingly irrelevant to whatever the agent is currently doing.

When context from a previous task is genuinely needed, transfer it explicitly: summarize the relevant findings or link to the relevant files. This is more effective than carrying an entire conversation history because you control what context enters the new thread.

Tip

If you notice an agent starting to forget instructions, repeat earlier mistakes, or produce lower-quality output, the context window may be saturated. Start a fresh thread with a focused summary of the current state rather than continuing to push through.

How It Plays Out

A developer fixes a bug in thread 1, then asks “while you’re here, can you also add input validation to the form?” The agent adds validation but uses a coding style inconsistent with the project conventions it was following five minutes ago. The conventions have scrolled out of effective context, displaced by the bug fix discussion. Starting thread 2 with a fresh context for the validation task would have produced better results.

A team adopts a strict thread-per-task discipline. Each morning, a developer opens a thread for each planned task: one for the bug fix, one for the feature, one for the documentation update. Each thread gets the agent’s full, fresh context. At the end of the day, completed threads are closed and their summaries are recorded in the progress log.

Example Prompt

“Let’s start a fresh task. Read CLAUDE.md for project conventions, then implement the email verification feature described in issue #47. Focus only on that — don’t carry over anything from previous conversations.”

Consequences

Thread-per-task keeps agent output quality high by ensuring each task gets a fresh, focused context. It makes conversations easier to review because each thread has a clear scope. It also creates a natural audit trail: completed threads document what was done and how.

The cost is the overhead of starting new threads and re-establishing context. Instruction files reduce this cost significantly, since project conventions are loaded automatically. The remaining cost is providing task-specific context, which is usually a few sentences describing the goal and pointing to the relevant files.

  • Depends on: Context Window — thread-per-task is a response to context window limits.
  • Uses: Instruction File — instruction files reduce the cost of starting fresh threads.
  • Uses: Memory — memory carries learnings across threads without carrying stale context.
  • Enables: Progress Log — each thread’s outcome feeds the progress log.
  • Enables: Subagent — subagents naturally operate as separate threads.
  • Uses: Compaction — compaction is an alternative to starting fresh when the thread must continue.