1. 长任务里 Claude Code 为什么会“失忆”如果你用 Claude Code 做过稍微复杂一点的任务大概率遇到过这种场景让它调研一个技术方案、重构一个模块、或者写一份带数据的报告前二十分钟它思路清晰工具调用到三四十次之后它开始重复问你已经回答过的问题把之前否掉的方案又提一遍最后在没验证的情况下说“已完成”。这不是模型变笨了而是它的工作记忆被上下文窗口挤爆了。Claude Code 的上下文本质上像内存条容量有限且断电即失。你执行一次/clear或者会话太长触发自动压缩之前聊过的计划、结论、踩过的坑就全没了。而文件系统像硬盘持久、可检索、容量几乎无限。Planning with Files 这个 skill 的核心思路就是把“重要信息”从对话上下文搬到项目目录的三个 Markdown 文件里让 AI 代理在长任务中有一个可恢复的外部记忆。它适合谁适合用 Claude Code 做跨会话开发、长链路调研、多阶段重构的人。如果你只是问一句答一句用不上它但只要你的任务预计超过 5 次工具调用或者需要跨多个会话推进这套机制就能明显减少返工。下面我会从 skills 目录结构讲起给出 config.toml / settings.json 骨架接入 TaoToken 统一 Key最后演示一次跨会话不丢上下文的验证动作。2. TaoToken 前置统一 Key 与 Claude Code 接入Planning with Files 本身是工作流插件它不解决模型调用的问题。你要让 Claude Code 真正跑起来得先有一个稳定的 API 入口。TaoToken 在这里的作用是提供统一的 Key 和兼容 Anthropic 的接入地址这样你在 Claude Code、Cursor、Gemini CLI 之间切换时不用每个工具配一套凭证。先到官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册然后在控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 里创建一个 API Key。创建完先别关页面Key 只显示一次复制到安全的地方。接着去 API Keys 管理页 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 确认 Key 的状态是启用。Claude Code 的接入配置通常写在~/.claude/settings.json或者项目级的.claude/settings.json。如果你用的是 Anthropic 兼容模式核心是设置ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY两个环境变量。TaoToken 的 API 地址是 https://taotoken.net/api注意这个地址不带 UTM 参数直接写进配置即可。{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-your-taotoken-key-here }, permissions: { allow: [ Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch ] } }这里有个容易踩的坑ANTHROPIC_BASE_URL末尾不要加/v1Claude Code 会自己拼接路径。如果你加了/v1请求会变成/v1/v1/messages直接 404。配置改完记得重启 Claude Code环境变量在启动时读取热改不生效。注意API Key 不要提交到 Git 仓库。项目级.claude/settings.json如果进了版本控制建议把 Key 放在用户级配置里项目级只留权限和 hooks。3. skills 目录结构与 Planning with Files 配置骨架Claude Code 的 skills 机制本质上是把一组行为约束、工具白名单和生命周期 hooks 打包成一个可复用的模块。Planning with Files 的目录结构大致长这样.claude/ skills/ planning-with-files/ SKILL.md config.toml templates/ task_plan.md findings.md progress.md scripts/ session-catchup.py check-complete.sh check-complete.ps1SKILL.md是核心头部用 YAML frontmatter 声明能力边界正文写工作流规则。config.toml负责 hooks 的注册templates/放三个文件的初始模板scripts/放会话恢复和完成校验脚本。先看SKILL.md的 frontmatter 骨架--- name: planning-with-files version: 2.10.0 description: Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks requiring 5 tool calls. user-invocable: true allowed-tools: - Read - Write - Edit - Bash - Glob - Grep - WebFetch - WebSearch hooks: PreToolUse: - matcher: Write|Edit|Bash|Read|Glob|Grep hooks: - type: command command: cat task_plan.md 2/dev/null | head -30 || true PostToolUse: - matcher: Write|Edit hooks: - type: command command: echo [planning-with-files] File updated. If this completes a phase, update task_plan.md status. Stop: - hooks: - type: command command: sh .claude/skills/planning-with-files/scripts/check-complete.sh ---allowed-tools是白名单限制这个 skill 只能做读、写、编辑、执行命令、检索这几类操作。PreToolUse的 matcher 命中写文件、改文件、跑命令、读文件、搜索这些动作时会先输出task_plan.md的前 30 行把目标和当前阶段强行塞回模型的注意力窗口。PostToolUse在每次写入后提醒更新阶段状态。Stophook 调用校验脚本只有所有 phase 都标记为 complete 才允许结束。config.toml是给不支持 YAML hooks 的环境用的等价配置[skill] name planning-with-files version 2.10.0 user_invocable true [hooks.pre_tool_use] matcher Write|Edit|Bash|Read|Glob|Grep command cat task_plan.md 2/dev/null | head -30 || true [hooks.post_tool_use] matcher Write|Edit command echo [planning-with-files] File updated. Update task_plan.md status if phase complete. [hooks.stop] command sh .claude/skills/planning-with-files/scripts/check-complete.sh三个模板文件的分工要记清楚task_plan.md是阶段状态机写 Goal 和 phasesfindings.md是知识沉淀写研究发现和关键决策progress.md是过程日志写操作记录、测试结果和错误。新手最常犯的错是把三个文件混着写结果恢复会话时找不到重点。4. 可复制配置三文件模板与 hooks 落地把模板复制到项目根目录这是工作台不是工具箱。安装目录里的 templates 只是参考真正生效的三文件必须在当前项目下。task_plan.md的初始结构# Task Plan ## Goal 用一句话写清楚这次任务要交付什么。 ## Current Phase Phase 1 ### Phase 1: Requirements Discovery - [ ] Understand user intent - [ ] Document findings in findings.md - **Status:** in_progress ### Phase 2: Planning Structure - **Status:** pending ### Phase 3: Implementation - **Status:** pending ### Phase 4: Verification - **Status:** pending ## Errors Encountered | Error | Attempt | Resolution | |-------|---------|------------|findings.md的初始结构# Findings ## Research Findings - ## Technical Decisions | Decision | Rationale | |----------|-----------|progress.md的初始结构# Progress Log ## Session Log - ## Error Log | Timestamp | Error | Resolution | |-----------|-------|------------|hooks 生效的关键是路径要对。check-complete.sh里的PLAN_FILE默认指向项目根目录的task_plan.md如果你把三文件放在子目录需要改脚本里的路径。校验逻辑很简单TOTAL$(grep -c ### Phase $PLAN_FILE || true) COMPLETE$(grep -cF **Status:** complete $PLAN_FILE || true) if [ $COMPLETE -eq $TOTAL ] [ $TOTAL -gt 0 ]; then exit 0 else exit 1 fi只要 phase 没全部 completeStop hook 就返回非零Claude Code 会认为任务未完成不允许直接收尾。这把“完成”从主观感受变成了可计算的闸门。5. 验证请求跨会话任务不丢上下文的实测配置好之后跑一次完整的跨会话验证。第一步在项目根目录启动 Claude Code输入/plan触发 skill。它会读取模板生成三文件然后你在task_plan.md里写一个真实的小任务比如“调研三个 JSON 解析库并给出选型建议”。第二步让 Claude Code 执行两次搜索或文件读取。按照 2-Action Rule每两次查看操作后必须把关键发现写进findings.md。你可以观察 PreToolUse hook 是否在每次工具调用前输出task_plan.md的前 30 行。第三步执行/clear清空上下文。这是关键动作模拟会话中断。清空后运行会话恢复脚本python .claude/skills/planning-with-files/scripts/session-catchup.py脚本会扫描~/.claude/projects/sanitized-project/下的历史会话文件找到最后一次写入三文件的位置把之后的用户消息、助手消息和关键工具调用整理成报告。你对照报告把三文件里缺失的信息补进去。第四步重新发起请求让 Claude Code 继续任务。如果配置正确它会先读task_plan.md确认当前 phase再读findings.md拿到之前的调研结论然后接着往下做而不是从头问你要做什么。验证成功的标志有三个/clear后重新提问Claude Code 能说出当前处于哪个 phasefindings.md里有之前搜索的关键结论progress.md里有操作记录。如果它重新问你“这个任务的目标是什么”说明 hooks 没生效或者三文件路径不对。6. 本篇常见错排查报错一PreToolUse hook 不触发。先检查SKILL.md的 frontmatter 缩进YAML 对空格敏感hooks下面的层级必须用两个空格递增。再确认matcher的正则是否匹配到了实际工具名Claude Code 的工具名大小写敏感Write和write不是一回事。报错二check-complete.sh一直返回非零。用grep -c ### Phase task_plan.md看总数再用grep -cF **Status:** complete task_plan.md看完成数。常见原因是状态标记写成了Status: complete少了星号或者 phase 标题用了## Phase而不是### Phase导致计数对不上。报错三session-catchup.py 找不到会话文件。这个脚本依赖~/.claude/projects/目录下的.jsonl文件。如果你用的是自定义配置目录需要改脚本里的CLAUDE_DIR变量。另外项目路径转目录名时会把斜杠替换成连字符路径里有中文或空格可能导致匹配失败。报错四TaoToken 请求 401。检查ANTHROPIC_API_KEY是否有多余空格以及 Key 是否在控制台被禁用。如果用的是项目级settings.json确认它没有被.gitignore忽略后又被其他配置覆盖。用户级配置优先级低于项目级两边都写了以项目级为准。报错五三文件被写到了安装目录。这是新手最常踩的坑。模板在.claude/skills/planning-with-files/templates/但生成的三文件必须在项目根目录。如果你在安装目录里看到了task_plan.md说明初始化时的工作目录不对删掉重新在项目根目录执行/plan。7. 继续深入模型对话、Coding Plan 与接入文档如果你只是想验证 Planning with Files 的工作流不需要写代码可以直接在模型对话里试。打开 https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 把三文件的内容贴进去让模型按 phase 推进观察它是否会在关键节点回读task_plan.md。这能帮你快速判断这套流程适不适合你的任务类型。如果你打算长期用 Claude Code 做编码和 Agent 任务建议看一下 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它针对长会话和高频工具调用做了额度优化配合 Planning with Files 的跨会话恢复能减少因为上下文重置导致的重复消耗。接入过程中遇到配置问题接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里有 Claude Code、Cursor、Gemini CLI 的完整示例。Claude Code 的 Anthropic 兼容配置在文档里有单独一节包括环境变量、settings.json 和常见报错对照表。最后说一个我自己的习惯每次开新任务前先花三十秒在task_plan.md里写清楚 Goal 和三个 phase再让 Claude Code 动手。这三十秒的投入通常能省掉后面半小时的返工。Planning with Files 的价值不在于它多复杂而在于它把“先规划再执行”这个简单原则变成了 hooks 强制执行的默认行为。