# 拆 planning-with-files：一行脚本没有，全靠四个 md 文件 ## 概述 本期是 Skills 生态系列的第 2 轮：单件深拆。这次选的不是带 Python 工具链的“重装 Skill”，而是反面——`planning-with-files`，一个 SKILL.md 里连一行可执行代码都没有的纯方法论 Skill。它出自 Jesse Vincent（GitHub ID：obra）的 superpowers 技能集，专门解决一个所有 Agent 用户都撞过的墙：任务跑一半会话断了，换个新会话，Claude 把前面干的活忘得一干二净。本文把它拆到 SKILL.md 的段落级：description 怎么写触发词、四文件工作流各自的设计意图、为什么这个场景下“零脚本”反而是加分项，以及它真实的短板。 ## 评测对比表 | Skill | 功能完整度 | 设计质量 | 实战效果 | 上手难度（低=好） | 社区活跃度 | |---|---|---|---|---|---| | planning-with-files | ★★★☆ | ★★★★★ | ★★★★ | ★★★★★ | ★★★★ | | superpowers（整套） | ★★★★★ | ★★★★ | ★★★★ | ★★★☆ | ★★★★★ | | skill-creator（官方） | ★★★★ | ★★★★ | ★★★★ | ★★★★ | ★★★★★ | | long-running-agent | ★★★☆ | ★★★☆ | ★★★☆ | ★★★☆ | ★★☆ | | remembering-conversations | ★★★☆ | ★★★☆ | ★★★☆ | ★★★★ | ★★☆ | 说明：后两件是本机已安装的同赛道 Skill（长任务管理、会话记忆），社区数据未经逐一核实，评分保守处理；planning-with-files 所在的 superpowers 套装 star 数在万级上下，以仓库实时数据为准。 ## 一、为什么要拆一个“没有代码”的 Skill 翻遍市面上几千个 Skill，大致分两类：一类是“工具箱”，塞满脚本，让 Claude 去调用——官方的 pdf、pptx、本机装的 pcap-generator 都是这类；另一类是“操作手册”，只给流程和判断标准，一个字节的代码都不带。 `planning-with-files` 是第二类里走得最远的之一。它解决的问题极其具体：**长任务的三种死法**。 1. 会话上下文被压缩，早期任务细节被挤掉，Claude 开始重复干活或自相矛盾； 2. 会话直接断掉（机器重启、token 用尽、你关了终端），新会话对进度一无所知； 3. 你自己中途换思路，隔了一天回来，不记得当初干到哪一步。 多数人的第一反应是上外部工具：todo 应用、任务管理 MCP、数据库。这个 Skill 的答案相反——**建一个目录，写四个 Markdown 文件，完事**。没有脚本，没有 MCP，没有 API。 ## 二、frontmatter 拆解：description 是它的全部“入口” 按官方规范，Skill 的触发完全靠 frontmatter 里的 `description` 字段——模型判断当前对话是否匹配这段话，匹配才加载正文。所以 description 写得好不好，直接决定这个 Skill 是“关键时刻自动出现”还是“永远躺在目录里”。 planning-with-files 的 description（大意节选，非原文照录，准确措辞以仓库为准）把触发场景写成了**时间轴**： - 任务要跨越多个会话； - 上下文可能被压缩或耗尽； - 需要在中断后从断点继续。 这个写法值得单独说。大多数 Skill 作者在 description 里写的是“我是什么”（比如“一个项目管理技能”），而它写的是“**你什么时候需要我**”——用用户会真实遇到的处境（会话断了、任务跨天）当触发词。这是描述工程的正确姿势：Claude 是按处境做匹配的，不是按名词。 第二个细节：description 里没有出现 "todo"、“项目管理” 这类大词。大词会误触发——你让它随手建个购物清单，它也把四文件流程搬出来。窄而准的触发条件，是方法论型 Skill 和工具型 Skill 在设计上的最大分野：工具型宁宽勿漏，方法论型宁窄勿滥。 ## 三、正文第一段：边界声明，不是背景介绍 进入正文，它的第一部分不是“概述”，而是两个清单：**什么时候用**（任务超过一个会话的容量、会被打断的调研类工作）、**什么时候别用**（十分钟内能干完的小事、有现成任务系统的团队流程）。 这是 Anthropic 官方 Skill 写作指南里反复强调的 "boundary statements"（边界声明），但在实际仓库里执行到位的不多。它的价值在于省 token 和防误触：模型读完边界，能自己否决不该加载的场景，而不是生搬硬套。 一个对照：本机装的不少社区 Skill，正文开头是三段渲染着表情符号的自我介绍，边界只字不提。读 SKILL.md 的质量，先看第一屏有没有“别用我”的诚实。 ## 四、核心拆解：四个文件，各管一种死亡 整个 Skill 的执行体就是一个 `plans/` 目录加四个文件。这是它被引用最多、也最值得逐个拆的部分。 ```mermaid flowchart TD A["接到长任务"] --> B["建 plans 目录"] B --> C["PLAN.md
任务清单打勾"] B --> D["STATE.md
当前卡在哪步"] B --> E["FINDINGS.md
坑与结论登记"] C --> F["干一个小任务"] F --> G{"干完了吗"} G -->|完成| H["回写四个文件"] H --> I["git commit 存档"] I --> J{"会话还活着吗"} J -->|是| F J -->|否| K["新会话先读档"] G -->|卡住| L["HANDOFF.md
写给下一班的话"] L --> K K --> F ``` **PLAN.md——防“重复劳动死”。** 拆任务不稀奇，稀奇的是它指定了载体：带 checkbox 的纯文本清单，直接躺在项目里。不用外部任务工具的理由很务实——文件跟代码走同一个 git 仓库，存档、回滚、diff 全部复用现成机制，Claude 对纯文本的操作成功率也远高于对外部 API。每个任务完成就打一个勾，被打断后瞄一眼勾号，进度自明。 **STATE.md——防“压缩失忆死”。** 这是我认为全 Skill 最妙的一个设计。它只回答一个问题：**此刻干到哪、下一步干什么**。上下文压缩丢的是“历史对话”，但 STATE.md 是磁盘上的文件，压缩永远动不了它。每当模型感觉“我可能快忘了”，重读一次 STATE.md，几行字就把全局捡回来。用一行文件的固定开销，对冲上下文窗口的不确定性——这是拿文件系统当显存用。 **HANDOFF.md——防“会话暴毙死”。** 会话要断（或你主动要换）时，把交接内容写成一段给“下一个我”看的信：干到哪、卡在哪、有什么没说出口的上下文。新会话冷启动的第一件事就是读它。这个文件平时可以不存在，只在交接时落笔——它管的是会话与会话之间的缝隙。 **FINDINGS.md——防“同一个坑摔两次”。** 长任务里最贵的成本不是写代码，是三天前踩过的坑今天又踩一遍。这个文件专门登记“非显然的发现”：某个依赖的版本坑、某个测试必须先跑、某个目录不能动。它本质上是把散落在对话里的隐性知识，强制固化成项目资产。 四个文件没有一个是新发明——柏拉图式的任务清单、值班交接、实验记录本，全是几百年的老东西。它的设计功力在于**选材的克制**：只挑了四个“缺了就死人”的，而不是堆一个五文件十模板的框架让人背。 ## 五、节奏设计：存档点比代码更重要 四文件只是静态结构，SKILL.md 里真正的心脏是**更新节奏**（大意，以原文为准）： 1. 每完成一个小任务，立刻更新文件，立刻 `git commit`； 2. commit 本身就是存档点——git log 就是存档列表； 3. 任务粒度刻意切小，“小到一次会话肯定能干完一个”； 4. 任何时刻被打断，最多损失一个任务片的进度。 这四条放在一起，其实是一套写给 Agent 的** checkpoints 纪律**，和游戏存档、数据库 WAL、分布式快照是同一个思想：不要假设进程永不死，假设它随时会死，然后让每次死亡都无痛读档。作者没有发明新概念，他把分布式系统里最老的一条工程铁律，翻译成了 Claude 能听懂的 Markdown。 值得注意的写法细节：SKILL.md 不说“你应该定期保存”，而是给出**可执行的判定句**——“完成一个任务就提交”。指令工程里，动词开头的具体动作，永远比形容词开头的品质要求可靠。 ## 六、为什么一行脚本都没有 拆到这里必须回答标题的问题：这个场景为什么不上脚本？ 第一，**方法论型 Skill 的交付物就是流程本身**，流程能被四百字的 Markdown 完整表达时，脚本是负资产——多一个文件多一份维护，多一次“脚本跑挂了模型开始 debug 脚本”的跑偏。 第二，**纯文本对模型是零协议成本**。写 STATE.md 就是一次普通的文件写入，失败率接近零；换成脚本，模型要理解参数、解析输出、处理异常路径。 第三，**对人可读**。你半夜打开 plans/ 目录，四个文件用任何编辑器直接看，不需要装任何东西。Skill 的消费者是两个物种：模型和你，纯文本是唯一两边都第一等的语言。 对照前几轮拆过的重装 Skill（官方 pptx 一个件里三条脚本产线），可以给 Skills 生态总结一条设计判据：**脚本密度应该正比于“确定性”**——格式转换、抓取、生成这类确定性任务，脚本越重越好；判断、规划、交接这类情境性任务，纯文本越轻越好。planning-with-files 是轻量派的教科书。 ## 七、适用与不适用 | 适合 | 不适合 | |---|---| | 跨多天的重构、迁移、大项目开发 | 一次问答、十分钟内的小改动 | | 会被打断的调研、爬数据、写长文 | 团队已有 Jira/Linear 等正式流程 | | 多会话接力：白天人盯，晚上挂机跑 | 需要多人协作审批的任务管理 | | 实验性项目：进度和发现都值得留痕 | 纯执行型流水线（每步都确定性很高时，四个文件是负担） | 最大的短板也在这张表里：**纪律依赖模型自觉**。没有钩子强制“没写 STATE.md 不许继续”，模型状态差时会跳过更新——这是所有纯方法论 Skill 的共同软肋，只能靠在 CLAUDE.md 里加一句强制提醒来补。 ## 八、安装与使用 方式一（推荐，以仓库 README 为准）：作为插件市场安装整套 superpowers—— ``` /plugin marketplace add obra/superpowers-marketplace /plugin install superpowers@superpowers-marketplace ``` 方式二（只要这一件）：从仓库把 `planning-with-files/` 整个目录拷到 `~/.claude/skills/` 下即可，零依赖。 使用不需要记命令：装好后对 Claude 说“帮我把这个迁移拆成跨天任务”，触发词命中就会自动走四文件流程；或者直接说“用 planning-with-files 管理这个任务”。 ## 九、分维度排行榜 - **设计质量第一**：planning-with-files——四文件、零代码、触发词三件套，是“少即是多”的满分答卷 - **功能覆盖第一**：superpowers 整套——头脑风暴、TDD、调试、规划一条龙，planning-with-files 只是其中一件 - **新手友好第一**：planning-with-files——装完即用，无配置，四文件看得见摸得着 - **生态位不可替代第一**：官方 skill-creator——前者教 Agent 干活，后者教你造 Skill，不冲突，建议同装 一句话结论：如果你的 Claude 会话总是“死在半路”，先别上任务管理 MCP，装这个四百行 Markdown 试试——它证明的是 Skills 生态里最反直觉的一件事：**有时候最好的 Skill，恰恰是那些坚决不写代码的 Skill**。 ## 参考来源 1. [obra/superpowers](https://github.com/obra/superpowers) — planning-with-files 所属的技能集仓库，含安装说明与全部技能源文件 2. [Jesse Vincent 博客（blog.fsck.com）](https://blog.fsck.com) — 作者的 "How I'm Using Claude Code" 系列文章，记录该工作流的演化过程 3. [anthropics/skills](https://github.com/anthropics/skills) — Anthropic 官方 Skill 仓库，Skill 结构与 description 写法规范的对照样本 4. [Claude Code 官方文档 Skills 章节](https://code.claude.com/docs) — frontmatter 与触发机制的第一手规范 5. [skills.sh](https://skills.sh) — Skills 生态聚合站，可查该 Skill 的分发与热度情况 > [!tip] 51学通信知识星球 > **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。 > **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。 > **当前规模**：5200 篇主题 / 990 个回答，198 元/年。 > **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。 > **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。