tl;dr: Claude struggles to maintain focus over long sessions and large codebases. To mitigate this, require Claude to maintain a detailed plan in a file and use subagents to complete the plan's tasks one after the other.
Claude Code is great at doing small, self-contained tasks. It starts to show its limitations over the course of longer sessions and larger codebases. As its context fills with information that is no longer relevant, it loses track of the task at hand, its design decisions become less sensible, and it gets worse at following basic instructions as a session progresses.
Often, the biggest struggle with Claude Code is just to help it remember what it's supposed to be working on. As we run out of context space, the agent gets "dumber" and "dumber" until eventually we need to start a new session.
Two simple techniques have gone a long way for me in remedying this:
- Claude Code's Subagents feature
- Using a Captain Claude to maintain a strict "Planning Checklist" policy
These two techniques complement each other, and can help lengthen the amount of time your Claude Code session context stays relevant to the task.
At any time, you can instruct Claude Code to do something with a subagent. Using a subagent spins up a "sub-Claude" separate from the main Claude in your terminal session. This is really useful for tasks that eat up a lot of tokens - when you're using a subagent, you're not filling up the main agent's context window with the subtask.
For example, let's say you're doing some debugging with Claude Code and you need to look at a 2,000 line log file. Asking your main Claude agent to read this log file will use up about 10% of your session context, and will fill that context with a lot of information that will ultimately not be relevant to your task.
In situations like this, I will often prompt Claude to "please use a subagent to look at the log file, and surface the relevant error up to you." This way, we still get the speed of Claude scanning the log file for us, but our primary Claude agent doesn't get so bogged down with the details - it just receives the error relevant to the task, and gets back to work, never losing focus.
You can get pretty fancy with configuring these subagents (see docs), but I usually keep it simple by just asking Claude to use a subagent in my prompt. "Please use a subagent to do tasks X, Y, Z".
One of Claude Code's many tools is a Todo List tool, where Claude can create Todo lists for itself to help it stay on-track. These are useful, but they are short lived. In addition to these built-in Todo lists, I've had a lot of success with requiring Claude to always maintain a Detailed Planning Checklist in a markdown file throughout whatever task we're working on. This Checklist should be:
- In a
*.mdfile checked into the repo - Encompassing the full context of whatever task you're working on - approximately "story" size.
- Updated frequently - at least every time you commit, ideally more
- Most importantly: Tasks on the list should contain enough detail that a subagent could pick them up and have enough context to complete the task.
You can probably see where this is going...
So, overall the strategy becomes:
- For your task, construct a detailed plan from start to finish and save it to a document in the repo.
- It is essential that the planning document contains detailed technical information about the task, and is kept up-to-date with the current state of the task.
- Implement: do most of the heavy lifting with subagents
- ... Orchestrated by a higher-level "Captain Claude" to maintain high-level context and keep the planning document up to date
To get started each morning, I'll normally start a new task with a prompt like this:
"Today we will be working on (copypaste Jira story). Relevant files and directories are A, B, C, D. Please take some time to take a deep look at all relevant files/directories, and ultrathink about the best way to complete this task. Let me know if you have any questions before we get started."
Claude inevitably asks a few questions. I answer the questions, then prompt:
"If you have no other questions, let's put together a detailed plan. In a markdown file in this repo, write a detailed step-by-step plan for the full task. Each task item in the document should contain enough information and context that a subagent could pick up the task and complete it using just the information contained in the task description."
This will probably result in a long, long planning document. It will be quite verbose, and not fun to read. You should read it very carefully anyway. I am certainly guilty of quickly scanning this document, glossing over obviously bad implementation choices made by Claude, and regretting it later. This is a time when you want to be most critical.
Once you've confirmed the plan looks good, send Claude the first iteration of your "loop prompt":
"Please update our planning document to best reflect the current state of our repo. Remove redundant, outdated or inaccurate information and update with new information when appropriate.
Then, continue with the plan we've put together in the planning document. For each step, use a subagent to complete the task. Once a subagent completes a task, run all tests to make sure it is truly completed. Stop to let me know each time we've reached a checkpoint. I will perform all git operations."
At each checkpoint, you'll want to triple-check Claude's work, run all tests yourself, and commit your work. Then continue resending your "loop prompt", tweaking the results, and committing, until your task is completed.
- caveats
- subagents lacking context
- planning doc getting too verbose/out of touch with reality
- knowing when to
/compact
- testing loop
- give subagents more context by writing test output to log files, etc