：LLM 无状态性与外部记忆需求

我们人类在处理复杂任务时通常会在脑海里维持一份心理清单。或者干脆写在便签纸上，方便一步步对照执行。这样即使事情再多再杂，也不容易遗漏。

大语言模型却完全不同——它在本质上是无状态的。每一次 API 调用都是一次独立的推理，模型并不会自动“记住”上一轮说过什么、做过什么。虽然可以把整个对话历史反复塞给模型，让它看起来好像保持了上下文。但这种记忆完全是被动的，还受限于的长度。

是当模型需要执行多步骤任务时问题就暴露出来了：

• 模型在几轮对话之后就可能忘掉还没完成的任务；
• 一旦触发对话压缩，旧的上下文就被丢弃；
• 使用者无法直观地看到 AI 当前做到哪一步；按理说，
• 子 Agent 和主线程的任务状态还会互相干扰。老实说，

为了解决这些痛点。Claude Code 引入了 TodoWrite 工具。它的本质，就是为 AI Agent 提供一个外部工作记忆——一个独立于对话历史、可读可写、还能自动提醒的代办任务管理工具。也让使用者获得了透明的进度感知。

TodoWrite 工具的设计理念

任务参数的设计

TodoWrite 工具本质是一个大模型工具。所以需要对其进行工具定义，接下来在请求大模型的时候将其带上，大模型再自主判断是否需要使用 TodoWrite，需要使用 TodoWrite 的时候就生成代办任务列表。 Claude Code 规定了每个任务对象强制包含以下三个字段，缺一不可：

字段	类型	说明	示例
	string	任务内容。祈使句"修复登录页的样式问题"	"修复登录页的样式问题"
	enum"pending"/"inprogress"/"completed"	任务状态"pending"/"inprogress"/"completed"	"inprogress"
form "active_form"	string	进行时描述，用于 UI 展示"正在修复登录页样式"	"正在修复登录页样式"

为什么需要同时提供 & in_progress 状态时面板上应展示动态进行时文本，给使用者更自然的进度感知。

状态机与约束

上一小节中讲到的 status 字段就包含了以下三种状态：

pending ────→ in_progress ────→ completed ↑ │ └───────────┘

有限且有方向 的 状态机

让每个 todo 项 的 生命周期 都 清晰可追踪。同 时 给 使用者 一个 “进度条”，使用者不需要翻 对话 历史 去 猜 AI 在 干嘛。话说回来，TodoWrite 会渲染成 一个 实时 面板。当前 在 做 什么 、还 剩 什么 、做完 了 什么，一目了然。就 像 外卖 App 上 的 “商家 正在备餐 → 骑手 正在配送”。怎么说呢，最佳 实践 要求.这 也 符 合 人类 的 工作习惯——一次只 做 一 件事。避免 上下 文 切换 混乱。

H4 id=""> 工具定义

• Pseudo code for tool definition and integration into an agent loop is given below..

This example shows how tool is defined as a function with JSON schema validation and n added to agent's tool set.

The agent loop uses this definition to invoke tool when necessary.

H4 id=""> 状态隔离与会话管理

• The state is kept in a global dictionary keyed by session_id..

This ensures that multiple concurrent sessions do not interfere with each or’s todo lists.

H4 id=""> TodoWrite 工具实现

• A Python implementation of core TodoWriteTool class is provided..

The execute method validates input,updates state,clears completed lists automatically。and prints a visual panel to terminal.

The printpanel method uses ANSI colors to render a clear task list showing status icons and progress counts.

H3 id=""> 自动提醒机制

• The todo_reminder attachment automatically injects reminders into conversation if no updates have been made for a number of turns..

This mechanism uses two thresholds – TURNSSINCEWRITE and _TURNSBETWEEN_REMINDERS – to control when reminders appear and how often y repeat.

A helper function gettodoreminder_attachments checks wher a reminder should be injected based on se thresholds and current state of incomplete tasks.

H4 id=""> 集成到 Agent Loop 的入口点

• An injection point is added right after receiving user input before calling LLM again ..

An additional injection point occurs after each tool execution cycle before anor LLM call .

H3 id=""> 使用者痛点 && 如何解决

• 遗忘TodoWrite 将所有待办事项保存在外部存储，而不是依赖对话上下文，从而防止因窗口溢出或压缩导致失去信息。

进度不可见实时面板显示每个 task 的 status icon 和描述，让使用者随时知道 AI 正在做什么和剩余多少工作。

上下文切换混乱通过限制同一时间只有一个 task 为 inprogress。而且使用 sessionid 隔离不同工作区，实现更一致、更可控的人机协作流程。

H3 id="">

• TodoWrite 为 Claude Code 提供了一套完整、可 且高效的方法来管理多步骤 AI 交互中的外部记忆和进度跟踪。. It addresses core pain points such as forgetting tasks,compression loss,opaque progress visibility。and cross‑agent interference while keeping interaction natural for both human users and large language models.

。

---