1. 长会话里 Claude Code 为什么会“失忆”用 Claude Code 写代码短任务很爽一旦任务拉长到几十轮工具调用问题就来了。我试过让它重构一个用户模块明确说了用 TypeScript、遵循 ESLint前 20 轮它老老实实照做到第 50 轮突然新建了一个.js文件还理直气壮地说“没注意到这个要求”。这不是模型变笨而是 Context Window 的结构性限制上下文一满早期的规则、约束、目标会被挤出去AI 只能靠最近几轮对话“自由发挥”。更麻烦的是 TodoWrite 这类内存态计划。上下文一重置待办清单直接消失你只能重新描述一遍需求等于每次会话都从零开始。错误也没有被持续记录同一个坑踩三次每次都要重新排查。真正有用的信息技术决策、踩坑结论、约束条件反而被大量无关的工具输出冲淡了。planning-with-files 这个插件解决的正是这个问题。它借鉴了 Manus 的 Context Engineering 思路核心不是让模型更强而是把“记忆”从易失的上下文窗口搬到磁盘上的 Markdown 文件里。AI 干活前先读笔记本干完活往笔记本里写上下文丢了也不怕因为关键状态都在文件里。它适合谁适合用 Claude Code 做多步骤重构、技术预研、复杂 Bug 排查、跨会话长任务的开发者。单文件改个文案这种小活用它反而累赘。下面我会拆开讲三文件模式、Hooks 触发时机、可复制的配置片段最后演示一次跨会话记忆恢复的完整验证动作让你在本地跑通可复现的流程。2. planning-with-files 的三文件模式与 Hooks 触发时机planning-with-files 的核心是“三文件模式”3-File Pattern每个复杂任务维护三个 Markdown 文件分工像一个小团队。task_plan.md是导航员承载元认知能力。它记录目标、阶段、待办清单和当前状态。关键设计是用了 Markdown 复选框[ ]/[x]AI 能直观识别哪些任务没完成不需要复杂解析。文件里还有Final Goal和Constraints两个区块前者是不可动摇的终极目标后者是硬约束比如“必须用 TypeScript禁用 any”。findings.md是研究员承载长期记忆。调研发现、技术决策、错误日志都写在这里。它有个 Action RuleAI 每执行 2 次搜索或 API 调用必须把关键信息总结写入防止重要发现被上下文冲刷。错误用表格记录包含 Error、Attempt、Root Cause、Resolution 四列方便回溯。progress.md是记录员承载情景记忆。按 Session 分段记录执行日志、测试结果、失败尝试。它配合 Strike Error Protocol同一错误第 1 次记录分析第 2 次必须换方案第 3 次触发全局反思并向用户求助打破死循环调试。光有文件还不够真正的技术壁垒在 Hooks。Hooks 是 Claude Code 的事件拦截器能在关键节点自动执行脚本把行为规范“硬编码”进 AI 的决策流程。核心有三类PreToolUse 在 AI 使用任何工具前触发脚本读取task_plan.md提取当前阶段和下一步待办通过echo输出提醒。这些输出会被注入到 AI 的下一轮上下文实现“注意力注入”相当于每次动手前提醒它“你该看计划了”。PostToolUse 在工具调用完成后触发负责把进度和发现写入findings.md和progress.md。Stop 在 AI 试图结束任务时触发做质量门禁。脚本统计task_plan.md里未勾选的复选框数量如果大于 0就用非零退出码阻止 AI 结束并列出剩余待办。这样 AI 没法“偷懒提前下班”。安装很简单项目级安装用claude plugins install OthmanAdi/planning-with-files全局安装用/plugin marketplace add加/plugin install。安装后 AI 会自动识别复杂任务并激活也可以手动触发/planning-with-files:plan。Windows 用户注意项目提供了 PowerShell 版本的 Hook 脚本避免 bash 兼容问题。3. 可复制的 Hooks 配置与 Markdown 模板这一节给你能直接抄的配置。先看 Hooks 定义以 Cursor 的.cursor/hooks.json为例Claude Code 的插件清单结构类似{ hooks: { PreToolUse: { description: 在AI使用任何工具前触发, script: hooks/pre-tool-use.sh, args: [--check-plan, --refresh-context] }, PostToolUse: { description: AI完成工具调用后触发, script: hooks/post-tool-use.sh, args: [--log-progress, --check-findings] }, Stop: { description: AI试图结束任务时触发, script: hooks/check-complete.sh, args: [--validate-phases, --report-status] } } }pre-tool-use.sh的核心逻辑是检查计划文件、提取当前阶段、输出提醒#!/bin/bash PLAN_FILEtask_plan.md if [[ ! -f $PLAN_FILE ]]; then echo 警告未找到 $PLAN_FILE请先创建任务计划 exit 1 fi CURRENT_PHASE$(grep -A2 ## Current Status $PLAN_FILE | grep Phase: | awk {print $2}) NEXT_STEP$(grep -A10 ## Next Steps $PLAN_FILE | grep - \[ \] | head -1 | sed s/.*- \[ \] //) cat EOF [PreToolUse Hook 提醒] 当前阶段Phase $CURRENT_PHASE 下一步待办$NEXT_STEP 请确认你即将执行的操作是否服务于上述目标 EOFcheck-complete.sh做结束前校验#!/bin/bash PLAN_FILEtask_plan.md PENDING_COUNT$(grep -c \- \[ \] $PLAN_FILE 2/dev/null || echo 0) if [[ $PENDING_COUNT -gt 0 ]]; then echo [Stop Hook 拦截] 任务未完成剩余 $PENDING_COUNT 项 grep \- \[ \] $PLAN_FILE | sed s/.*- \[ \] / - / exit 1 fi echo [Stop Hook 通过] 所有阶段已完成 exit 0再看task_plan.md模板这是 AI 的“宪法”# Task Plan ## Current Status - Status: in_progress - Phase: 2/4 - Last Updated: 2026-02-25 ## Next Steps - [x] 分析项目需求与依赖 - [x] 设计技术方案架构 - [ ] 实现核心业务逻辑 - [ ] 编写单元测试用例 ## Final Goal 完成用户认证模块开发支持 JWT Refresh Token 双机制 兼容旧版 API v1.x密码加密使用 bcrypt(salt rounds12) ## Constraints Notes - 必须使用 TypeScript禁用 any 类型 - 遵循项目 ESLint 配置禁止修改 .eslintrc - 数据库操作需添加事务回滚机制findings.md的错误日志表模板# Findings Knowledge Base ## Key Discoveries - 库 auth-lib2.0 在 Node 18.15 有兼容问题建议锁定 18.12 ## Errors Encountered | Error | Attempt | Root Cause | Resolution | |-------|---------|------------|------------| | JWT验证失败 | 1 | 时区配置错误 | 统一使用 UTC 时间戳 | | 数据库连接超时 | 2 | 连接池过小 | max_connections20加重试 | ## Decisions Made ### 决策选择 passport-jwt 而非原生 jsonwebtoken - Reason: 内置 refresh token 续期逻辑社区活跃 - Trade-offs: 增加一个依赖包15KBprogress.md按 Session 分段# Progress Log Session History ## Session 1 - 2026-02-25 14:00-15:30 ### Completed - [x] 初始化项目结构配置 tsconfig.json - [x] 实现 JWT token 生成函数 ### Failed Attempts - 尝试同步验证中间件阻塞事件循环P99 延迟 80ms→320ms - 决策切换到异步中间件 ### In Progress - 实现 refresh token 自动续期逻辑如果你用的 IDE 不支持 Hooks可以在.cursorrules或.clinerules里用系统提示词模拟工作流启动复杂任务前必须读task_plan.md每 2 次信息收集操作必须写findings.md每次工具调用后记录progress.md任务结束前验证所有复选框为[x]。4. 验证一次跨会话记忆恢复配置好之后怎么确认它真的在工作我设计了一个最小验证流程你可以跟着跑一遍。第一步启动一个复杂任务。在 Claude Code 里输入/planning-with-files:plan 帮我开发一个带 refresh token 的用户认证系统观察 AI 是否自动创建了task_plan.md、findings.md、progress.md三个文件。打开task_plan.md确认里面有 Current Status、Next Steps、Final Goal、Constraints 四个区块且 Next Steps 是带复选框的清单。第二步让它干一部分活。比如让它实现 JWT 生成函数。执行过程中PreToolUse Hook 应该会在每次写文件前输出提醒你可以在 Claude Code 的日志里看到“当前阶段Phase X下一步待办XXX”。干完后检查progress.mdSession 1 的 Completed 里应该多了这条记录。第三步模拟上下文丢失。直接关闭当前会话或者用/clear清空上下文。这一步是关键传统方式下 AI 会完全忘记之前做了什么。第四步触发会话恢复。在项目settings.json里加上{ env: { PLANNING_WITH_FILES_AUTO_RECOVER: 1 } }然后重新打开会话输入“继续之前的任务”。恢复脚本会扫描~/.claude/projects/下最近修改的 planning 文件提取progress.md最后一条记录的时间戳检索该时间之后的会话日志生成补全报告。你应该看到类似输出[Session Recovery] 检测到中断的会话 (2026-02-25 15:30) 最后进度完成 JWT 验证中间件待实现 refresh token 端点 建议下一步1) 创建 /auth/refresh 路由 2) 编写 token 续期逻辑第五步验证 AI 是否真的“记得”。问它“我们之前决定用哪个库做 JWT 验证为什么”。如果它回答“passport-jwt因为内置 refresh token 续期逻辑减少自定义代码”说明它读到了findings.md里的决策记录。再问“当前阶段还剩哪些待办”它应该能准确列出task_plan.md里未勾选的项。这套流程跑通你就有了一个可复现的记忆留存闭环。核心验证点是上下文清空后AI 仍能通过文件恢复目标、约束和进度而不是重新问你一遍需求。5. 常见报错与排查实际用下来最容易卡在几个地方。下面按真实报错对照排查。401 未授权 / invalid api key。如果你在配置里接了自定义 API 端点检查 Base URL 和 Key 是否匹配。用 TaoToken 的话Base URL 填https://taotoken.net/apiKey 在控制台的 API Keys 页面生成。注意 Base URL 不要带 UTM 参数否则部分客户端会解析失败。三件套要写全Base URL、Key、Model ID缺一个都可能 401。local proxy failed / connection refused。Hook 脚本里如果调用了本地服务或网络请求先确认脚本本身有执行权限chmod x hooks/*.sh。Windows 下如果用的是.sh脚本检查是否装了 Git Bash 或 WSL否则换成项目提供的.ps1版本。另外检查settings.json里的env字段有没有拼错JSON 不允许尾随逗号。reading choices of undefined。这个报错通常出现在 API 返回体解析阶段说明请求根本没拿到正常响应。先看 Hook 脚本的echo输出有没有混进非预期内容污染了上下文。再确认 Model ID 拼写正确比如claude-sonnet-4-5这类标识要和平台文档一致。如果用了 Coding Plan确认套餐还在有效期内。OAuth token expired / authentication failed。Claude Code 本身的登录态过期重新走一次登录流程即可。如果你用的是 Codex 的auth.json方式检查文件里的 token 字段有没有过期必要时重新生成。注意auth.json的路径要和客户端读取路径一致放错目录等于没配。Hook 不触发。先确认插件真的装上了claude plugins list能看到 planning-with-files。再看.cursor/hooks.json或对应 IDE 的 hooks 配置路径对不对不同 IDE 路径不同Claude Code 看.claude-plugin/manifest.jsonCursor 看.cursor/hooks.jsonVS Code Continue 看.continue/prompts/。如果路径对但没反应检查脚本退出码PreToolUse 返回非零会阻止工具调用可能被误认为“没触发”。Stop Hook 一直拦截任务结束不了。说明task_plan.md里还有未勾选的[ ]。要么继续完成要么明确说明跳过原因并把该项改成[x]或者在计划里删掉不做的项。别直接删文件绕过那样就失去了质量门禁的意义。排查时有个通用技巧单独在终端跑一遍 Hook 脚本看输出是否符合预期。比如bash hooks/pre-tool-use.sh如果报command not found就是依赖没装如果输出为空就是 grep 没匹配到检查 Markdown 标题格式是否和脚本里的## Current Status完全一致大小写和空格都敏感。6. 把记忆留在文件里而不是上下文里planning-with-files 的价值不在于让模型变聪明而在于把易失的上下文状态转成磁盘上的持久文件。三文件各司其职Hooks 在关键节点做注意力注入和质量门禁Session Recovery 让跨会话续接成为可能。你不需要一次配全所有 Hook可以先从task_plan.md加一个 Stop Hook 开始跑顺了再补 PreToolUse 和 PostToolUse。如果你还没接 Claude Code 的 API可以到 TaoToken 的 API Keys 页面生成 KeyBase URL 用https://taotoken.net/apiModel ID 按文档填。想先验证模型对话效果可以去模型对话试几轮。长期做编码和 Agent 任务的话Coding Plan 更划算。接入细节看接入文档Claude Code 相关配置在 ClaudeCodeAnthropic 页面有完整说明。最后留一个实用习惯每次会话结束前花 10 秒扫一眼progress.md的最后一条记录确认它准确描述了当前状态。这条记录就是下次会话恢复的锚点写清楚“做到哪、下一步是什么、有什么坑”比任何总结都管用。