Docs: Proactive Planning Behavior with `TodoWrite` Tool is Undocumented

Title: Docs: Proactive Planning Behavior with TodoWrite Tool is Undocumented

Labels: documentation, enhancement, user-experience, core-behavior

Overview

The documentation for Claude Code lists the TodoWrite tool but fails to explain its proactive, planning-oriented behavior, which is mandated by the agent's internal system prompt. This creates a significant disconnect between the documented features and the agent's actual, core interaction model, leading to a confusing user experience.

Description

For any non-trivial task, the Claude Code agent is explicitly and repeatedly instructed in its system prompt to use the TodoWrite tool to break down the problem and create a plan before taking any other action. This is a fundamental part of its operational logic.

However, the public documentation only mentions the tool's existence, completely omitting its central role in the agent's workflow.

The Problem

When a user gives a complex command (e.g., "refactor the authentication module"), they might expect the agent to immediately start reading and editing files. Instead, the agent's primary instruction is to first generate a to-do list using TodoWrite.

While this planning step is a powerful feature that provides transparency, its undocumented nature makes it feel like an unexpected or even incorrect response. It creates an expectation mismatch, leaving the user wondering why the agent isn't "doing the thing" they asked for.

Evidence from Internal System Prompt

The "hidden" system prompt for Claude Code version 1.0.98 provides undeniable evidence that this planning behavior is a core, non-negotiable directive.

1. Mandatory and Frequent Use:
The Task Management section of the prompt states:

You have access to the TodoWrite tools to help you manage and plan tasks. Use these tools VERY frequently to ensure that you are tracking your tasks and giving the user visibility into your progress. ... If you do not use this tool when planning, you may forget to do important tasks - and that is unacceptable.

This confirms the behavior is not optional but a critical requirement for the agent.

2. Explicit Planning Directive:
The same section emphasizes its role in planning:

These tools are also EXTREMELY helpful for planning tasks, and for breaking down larger complex tasks into smaller steps.

Furthermore, the first step in the Doing tasks section is:

- Use the TodoWrite tool to plan the task if required

3. Specific Triggers for TodoWrite:
The detailed instructions for the TodoWrite tool itself specify exactly when this behavior should be triggered:

When to Use This Tool Use this tool proactively in these scenarios: 1. Complex multi-step tasks 2. Non-trivial and complex tasks 3. After receiving new instructions

4. Illustrative Examples:
The prompt includes examples that perfectly match the user experience gap. For instance:

<example> user: I want to add a dark mode toggle to the application settings. Make sure you run the tests and build when you're done! Assistant: I'll help add a dark mode toggle to your application settings. Let me create a todo list to track this implementation. *Creates todo list with the following items:* 1. Creating dark mode toggle component in Settings page 2. ... 3. ... </example>

This example demonstrates the exact behavior—responding to a feature request with a plan—that is currently undocumented.

Suggested Solution

To align user expectations with the agent's core behavior, the documentation must be updated. This information should be placed in prominent locations like the Quickstart and Common Workflows pages.

Example for a new section or callout:

#### Understanding Claude's Planning Process For any non-trivial request, Claude Code is designed to first create a step-by-step plan using its to-do list tool (TodoWrite). This is a core feature, not an error. You will see this plan appear in the interface, allowing you to review and guide the agent's approach before it begins implementation. This planning-first methodology is key to how Claude tackles complex problems effectively and transparently, ensuring it stays on track and gives you full visibility into its process.

Conclusion

The internal system prompt confirms that proactive planning with TodoWrite is one of the most fundamental aspects of the Claude Code agent. Its omission from the public documentation is a critical gap. Clarifying this core interaction model will significantly improve the user experience by turning a moment of potential confusion into an appreciated display of the agent's thoughtful, structured approach.