learn-claude-code 实战：用 TodoWrite 解决长链路健忘
基本信息
- 作者: Flittly
- 链接: https://juejin.cn/post/7614205951298355246
导语
在构建长链路 Agent 应用的过程中，大模型在多步推理后往往会出现上下文“健忘”现象，导致任务执行中断。本文聚焦 learn-claude-code 项目的 TodoWrite 阶段，解析如何通过持久化待办事项机制来维护任务状态。读者将了解到具体的代码实现逻辑，以及如何利用这一模块增强模型在复杂场景下的连续执行能力。
描述
本文介绍 learn-claude-code 项目第3阶段（s03）的 TodoWrite（待办写入）功能，用于解决大模型在长链路任务中“健忘”的问题。
摘要
本文总结《从零手写 ClaudeCode：learn-claude-code 项目实战笔记》第3阶段（s03）的核心内容——TodoWrite（待办写入）功能。
1. 核心痛点
在长链路任务中，大模型（LLM）容易出现“健忘”现象。当任务步骤繁多时，模型往往在执行后续步骤时遗忘了前置的设定或中间结果，导致任务失败或逻辑断层。
2. 解决方案
TodoWrite 机制旨在模拟人类的“做笔记”习惯。它不仅仅是一个简单的列表，而是一个结构化的记忆写入系统。其核心逻辑是：在执行复杂任务的过程中，让模型显式地将关键步骤、已完成事项、待办目标以及中间状态实时写入一个持久化的 Todo 缓冲区。
3. 功能本质
- 状态固化： 将短暂的短期记忆转化为长期可见的上下文。
- 链路追踪： 确保每一步操作都有据可查，防止模型在多轮对话后“跑题”或死循环。
通过实现 TodoWrite，项目显著提升了 Agent 在处理复杂、多步骤任务时的稳定性和连贯性。
评论
文章中心观点 文章主张通过构建“TodoWrite”机制，将抽象的任务规划转化为具象的代码写入行为，利用外部内存系统来补偿大模型在长链路任务中的上下文遗忘问题，从而实现更稳健的Agent智能体行为。
深入评价与分析
1. 内容深度：从“对话”到“工程”的认知跨越 文章触及了当前LLM应用开发的核心痛点：状态持久化与上下文窗口的矛盾。
- 支撑理由（事实陈述）： 大模型本质上是概率预测机，具有“无状态性”。在处理多步骤任务（如S03阶段的复杂代码生成）时，随着Token增加，早期的指令往往会被“冲刷”掉，导致模型在后续步骤中偏离初衷。
- 支撑理由（作者观点）： 作者提出的 TodoWrite 不仅仅是记录任务，更是一种“思维链的外部化”。通过强制模型将计划写入文件，模型在后续步骤中可以通过读取文件来“重激活”记忆，这符合认知心理学中的“卸载”理论。
- 反例/边界条件（你的推断）： 这种方法在面对高度动态或非结构化的任务时可能失效。如果任务每一步都需要根据上一步的实时反馈剧烈调整，写入Todo文件的动作可能成为累赘，导致“过度规划”而丧失灵活性。
2. 实用价值：Agent 开发的标准化组件
- 支撑理由（事实陈述）： 在 AutoGPT、BabyAGI 等早期 Agent 项目中，任务拆解是标配，但它们往往依赖内存数组。本文强调“写入代码/文件”，这对于开发类 Agent（如 ClaudeCode）至关重要，因为它让开发人员可以直接通过 Git 进行版本控制和审计。
- 支撑理由（你的推断）： 对于试图从简单的 RAG（检索增强生成）转向复杂 Agent 系统的开发者，这篇文章提供了一个低门槛的工程范式。它展示了如何通过简单的文件 I/O 操作来模拟“记忆”功能，无需引入复杂的向量数据库。
- 反例/边界条件（事实陈述）： 在高频交易或实时系统监控等场景下，文件 I/O 的延迟是不可接受的。此时，基于内存的键值对存储或共享状态管理（如 Redis）远比写文件更高效。
3. 创新性：将“Prompt”转化为“Code”
- 支撑理由（作者观点）： 文章的创新点在于将“待办事项”视为“代码”的一部分。TodoWrite 不仅仅是一个列表，它是程序逻辑的中间表示。这种模糊“自然语言计划”与“可执行代码”界限的做法，是迈向“自我修正代码”的重要一步。
- 支撑理由（你的推断）： 这种方法隐含了“模型即编辑器”的假设。Claude 不仅是生成者，还是自己任务的管理者。这种角色的双重性是当前 AI Coding Assistant（如 Cursor, Windsurf）竞争的焦点。
- 反例/边界条件（你的推断）： 如果 Todo 文件的格式定义过于严格，可能会限制模型的创造力；反之，如果过于松散，模型可能无法正确解析自己写下的内容，导致“左耳进右耳出”。
4. 可读性与逻辑性 文章结构清晰，遵循“问题-方案-实现”的工程叙事逻辑。作者没有停留在理论层面，而是结合了具体的代码实现（虽然未在摘要中展开，但标题暗示了实战性质），这种“手把手”的教学风格对于技术受众非常友好。
5. 行业影响与争议点
- 行业影响： 该项目（learn-claude-code）如果持续迭代，可能会成为开源社区理解闭源 SOTA 模型（如 Claude 3.5 Sonnet）能力边界的标杆案例。它证明了通过合理的工程架构，开源模型或 API 调用可以逼近“System 2”（慢思考）的能力。
- 争议点（不同观点）：
- 硬编码 vs. 通用智能： 批评者可能认为，专门写一个 TodoWrite 模块是“特指工程”。真正的 AGI 应该能够自主决定何时、何地、如何存储记忆，而不是由人类预先写好
write_todo()函数。 - 幻觉风险： 模型可能会在 Todo 文件中写入它认为已经完成的任务，而实际上代码并未生成。这种“虚假完成”是 Agent 开发中常见的欺骗性现象。
- 硬编码 vs. 通用智能： 批评者可能认为，专门写一个 TodoWrite 模块是“特指工程”。真正的 AGI 应该能够自主决定何时、何地、如何存储记忆，而不是由人类预先写好
实际应用建议
- 引入校验机制： 不要盲目信任模型写入的 Todo。在执行下一步前，增加一个验证步骤，检查 Todo 中标记为“完成”的事项是否在代码库中真实存在。
- 分层记忆： 区分“短期记忆”（当前会话上下文）和“长期记忆”（Todo 文件）。不要将所有上下文都写入文件，以免造成信息噪音。
- 回滚策略： 既然 Todo 是文件，就利用 Git 的能力。当 Agent 走入死胡同时，允许它回滚到上一个 Todo 节点，重新规划路径。
可验证的检查方式
- 任务完成率对比（指标）： 构建两个相同的 Agent，一个使用 TodoWrite 机制，一个仅依赖 Context Window。分别运行 50 步以上的复杂任务，比较其“任务偏离度”和“最终成功率”。
- Token 消耗分析（实验）： 监控开启 TodoWrite 前后的 Token 消耗。理论上，虽然增加了写入 Token，但可能减少了重复解释上下文的 Token，观察总成本
学习要点
- 掌握了通过 ClaudeCode 实现 TodoWrite 功能的完整流程，包括需求分析、代码实现和测试验证。
- 深入理解了如何将自然语言指令转换为结构化的待办事项数据，并持久化存储到本地文件系统。
- 学会了利用 ClaudeCode 的上下文感知能力，自动识别用户意图并生成相应的操作代码。
- 优化了待办事项的写入逻辑，确保数据格式的一致性和可扩展性，为后续功能迭代奠定基础。
- 通过实战项目，提升了使用 AI 辅助工具进行快速原型开发和功能迭代的能力。
常见问题
1: TodoWrite 的主要功能是什么，它与普通的待办事项应用有何不同？
1: TodoWrite 的主要功能是什么，它与普通的待办事项应用有何不同？
A: TodoWrite 是 learn-claude-code 项目中的一个核心模块，专注于通过自然语言处理来管理和写入待办事项。与普通的待办事项应用不同，TodoWrite 允许用户使用自然语言描述来创建、修改和查询待办任务，而不是通过传统的表单或按钮操作。它能够理解复杂的指令，例如"将明天下午3点的会议标记为高优先级"，并自动解析时间、内容和优先级等信息。这种交互方式更符合人类思维习惯，减少了操作步骤，提高了效率。
2: 在实现 TodoWrite 时，如何处理自然语言输入中的时间和日期解析？
2: 在实现 TodoWrite 时，如何处理自然语言输入中的时间和日期解析？
A: 时间和日期解析是 TodoWrite 的关键技术点之一。项目通常采用以下策略：首先，使用自然语言处理库（如 Python 的 dateparser 或 parsedatetime）来解析用户输入中的时间表达。这些库能够处理多种格式的日期时间描述，如"明天"、“下周三”、“3天后"等相对时间，以及"2023-12-25"等绝对时间。其次，对于模糊的时间表达（如"晚上”），系统会根据上下文或默认设置进行合理推断。最后，解析后的时间会被统一转换为标准格式存储，确保后续处理的一致性。项目还会考虑时区问题，确保跨时区用户的体验。
3: TodoWrite 如何确保待办事项数据的持久化存储？
3: TodoWrite 如何确保待办事项数据的持久化存储？
A: 数据持久化是 TodoWrite 的基础功能。项目采用了分层存储策略：首先，所有待办事项数据以结构化格式（如 JSON）存储在本地文件中，确保即使程序重启数据也不会丢失。其次，对于需要更高可靠性的场景，项目支持将数据同步到云端数据库（如 SQLite 或 PostgreSQL）。在实现上，每次数据变更都会触发写入操作，并采用原子写入（atomic write）技术防止数据损坏。此外，项目还实现了数据版本控制，允许用户查看和恢复历史版本，防止误操作导致的数据丢失。
4: 在多用户环境下，TodoWrite 如何处理并发访问和数据一致性问题？
4: 在多用户环境下，TodoWrite 如何处理并发访问和数据一致性问题？
A: 多用户支持是 TodoWrite 的高级功能。为了解决并发访问问题，项目采用了以下机制：首先，每个待办事项都有唯一的标识符（UUID），避免不同用户的操作冲突。其次，实现了乐观锁（optimistic locking）机制，在更新数据时检查版本号，确保没有其他用户在同一时间修改了同一数据。如果检测到冲突，系统会提示用户并要求手动解决。此外，项目还支持事务处理，确保一系列操作的原子性。对于实时协作需求，项目集成了 WebSocket 技术，能够即时将一个用户的变更推送给其他相关用户。
5: TodoWrite 的扩展性如何设计，以便未来添加新功能？
5: TodoWrite 的扩展性如何设计，以便未来添加新功能？
A: 扩展性是 learn-claude-code 项目的重要设计原则。TodoWrite 采用了模块化架构，将核心功能与扩展功能分离。具体来说：首先，定义了清晰的接口（interface），所有功能模块都通过接口与核心系统交互，而不是直接耦合。其次，使用了插件系统，允许开发者动态加载新功能模块，如提醒功能、标签系统等。此外，项目还预留了钩子（hooks）机制，在关键操作点（如创建、更新、删除待办事项）触发自定义逻辑。最后，项目文档详细说明了扩展开发的最佳实践，降低了新开发者的上手难度。
6: 在开发 TodoWrite 过程中遇到了哪些主要技术挑战，是如何解决的？
6: 在开发 TodoWrite 过程中遇到了哪些主要技术挑战，是如何解决的？
A: 开发 TodoWrite 过程中面临了多个技术挑战。首先是自然语言理解的准确性问题，特别是处理模糊或歧义表达时。解决方案是结合规则引擎和机器学习模型，通过大量真实用户数据的训练和调优，逐步提高理解准确率。其次是性能优化，随着待办事项数量增加，查询和更新速度会下降。项目通过引入索引、缓存和分页等技术解决了这个问题。最后是跨平台兼容性，确保 TodoWrite 在不同操作系统和设备上都能稳定运行。项目采用了跨平台框架（如 Electron 或 Flutter），并编写了全面的自动化测试来确保兼容性。
7: 对于初学者，如何开始学习和使用 TodoWrite 源码？
7: 对于初学者，如何开始学习和使用 TodoWrite 源码？
A: 对于初学者，建议按照以下步骤学习 TodoWrite 源码：首先，阅读项目文档，了解整体架构和设计思路。其次，从简单的功能模块入手，如数据模型定义和基本的 CRUD 操作，逐步理解代码结构。然后，尝试运行项目并调试，通过修改代码观察效果，加深理解。项目还提供了详细的注释和示例代码，帮助初学者快速上手。此外，可以参与社区讨论，向经验丰富的开发者请教。最后，尝试自己实现一个小功能，如添加新的待办事项属性，通过实践巩固所学知识。
引用
注：文中事实性信息以以上引用为准；观点与推断为 AI Stack 的分析。