title: "Agent Goes Off Track on Complex Tasks" last_updated: 2026-03-21 status: proven difficulty: intermediate prerequisites: [03-prompting-for-agents]

Problem: Agent Goes Off Track on Complex Tasks

Symptoms

  • Agent starts solving a different problem than what you asked
  • Agent makes increasingly wrong assumptions as the session continues
  • Changes pile up that don't relate to the original task
  • Agent edits files you didn't expect it to touch

Common Causes

  1. Task too large — The task exceeds what the agent can hold in focus. Context drifts.
  2. Ambiguous prompt — The agent interpreted your request differently than you intended.
  3. Context window full — As the session grows, earlier instructions get compressed or lost.

Solutions

For Cause 1: Decompose the Task

Break it into smaller, focused subtasks:

# Instead of:
"Refactor the entire authentication system"

# Do:
"Refactor the login function in src/auth/login.ts to use async/await instead of callbacks. Don't change anything else."

For Cause 2: Use Plan Mode

Ask the agent to plan before executing:

Before making changes, explain your plan:
1. What files will you modify?
2. What approach will you take?
3. What won't you change?

Review the plan. If it's off track, correct it before any code changes happen.

For Cause 3: Start a Fresh Session

Use checkpoint commits to save progress, then start a new session:

git add -A && git commit -m "WIP: checkpoint before next phase"
claude  # fresh session with full context window

Prevention

  • Use the plan-then-execute pattern for any task touching 3+ files
  • Use checkpoint commits every 15-20 minutes on complex tasks
  • Keep individual prompts focused on one change at a time
  • If the session feels "heavy," start fresh — it's cheaper than correcting drift