长任务翻车，很少是因为模型不会做，而是因为它忘了自己做到哪。上下文一压缩，前面想清楚的取舍就没了；会话一断，昨天定下的阶段顺序也没了。**planning-with-files** 的全部野心，就是把这件事从「求模型记性好」变成「求文件还在」。 它是 2026 年上半年最出圈的规划类 Skill 之一，作者 OthmanAdi，README 自述「不到 24 小时就引爆」。2026 年 6 月中旬的公开数据是约 2.3 万星、2000 多次 fork。它没有脚本、没有 MCP、没有向量库，全部内容就是一份 Markdown 协议加两个延伸文档。 也正因为薄，它特别适合逐行拆。下面按 SKILL.md 的原始顺序，一段一段看它到底做对了什么。 ## 一、开头两句话，先重新定义问题 SKILL.md 的第一句是： > Work like Manus: Use persistent markdown files as your "working memory on disk." 这句话干了三件事。**借势**：Manus 是长程 Agent 的公开样板，读者立刻知道它想复刻什么。**给心智模型**：working memory on disk，把「规划」翻译成「一块不会掉电的内存」。**给手段**：persistent markdown files，具体到文件格式，不留解释空间。 注意它没有写「帮你更好地规划任务」。那种写法是在功能层面竞争，而这句话是在问题层面竞争：它不说自己规划得更聪明，它说自己解决了「记忆会丢」这个更底层的问题。整份 SKILL.md 后面的所有设计——为什么用 Markdown、为什么落磁盘、为什么是三个文件——都是这句话的推论。 写 Skill 的人常犯一个错：开头急着罗列能力。这份文件开头只做定位，能力留到后面用表格说。 ## 二、Quick Start：四个动词，四个时间点 紧接着是： > Before ANY complex task: > > 1. **Create `task_plan.md`** in the working directory > 2. **Define phases** with checkboxes > 3. **Update after each phase** - mark [x] and change status > 4. **Read before deciding** - refresh goals in attention window 四行全是动词开头：Create、Define、Update、Read。它们不是四个步骤，而是四个**时间点**：任务开始前、计划建立时、每个阶段结束后、每次决策前。 这是整份文件最值得抄的写法。多数提示词会写「要经常维护计划」「保持计划更新」，模型读完点头，然后继续凭记忆干活。这里把「经常」拆成了「after each phase」和「before deciding」两个可判定的时刻——阶段结束是一个事件，重大决策是一个事件，都能被模型识别。 第四条尤其关键：**Read before deciding**。大多数规划类提示词只要求「写计划」，不要求「读计划」。结果计划写完就变成存档，模型该跑偏还是跑偏。这一条把「读」变成了决策的前置动作，理由也写得很准确：refresh goals in attention window——不是「提醒自己」，而是把目标重新放回注意力窗口。 「Before ANY complex task」里的 ANY 用了全大写，看起来像要把触发范围拉到最大。但别急，文件后半段有一节专门踩刹车，后面会讲。 ## 三、三文件表：一份文件契约 第三个板块是一张三列表格： | File | Purpose | When to Update | |------|---------|----------------| | `task_plan.md` | Track phases and progress | After each phase | | `notes.md` | Store findings and research | During research | | `[deliverable].md` | Final output | At completion | 三列分别是：文件、职责、更新时机。这实际上是一份**契约**——每个文件只干一件事，每件事只在特定时机发生。 最妙的是第三行的 `[deliverable].md`。它不是固定文件名，而是一个占位符：交付物叫什么，由任务本身决定。前两个文件是过程文件，第三个是结果文件。所以「三文件」并不是机械地创建三个空 Markdown，而是三种角色的分工： - `task_plan.md` 存**状态**：我在哪、下一步是什么、做过哪些决定。 - `notes.md` 存**素材**：查到什么、出处在哪、综合判断是什么。 - `[deliverable].md` 存**产物**：最终要交出去的东西。 理解了这个角色划分，就不会出现「把研究笔记塞进计划文件、把计划状态写进交付物」的混乱。很多团队照抄三文件却用不好，问题就出在只抄了文件名，没抄职责边界。 ## 四、四个 Loop：写盘节奏才是核心 Core Workflow 用 code block 画了四个循环： ``` Loop 1: Create task_plan.md with goal and phases Loop 2: Research → save to notes.md → update task_plan.md Loop 3: Read notes.md → create deliverable → update task_plan.md Loop 4: Deliver final output ``` 看起来像四个阶段，其实不是。Loop 2 和 Loop 3 都以「回写 task_plan.md」结尾，这才是设计重点：**任何一次素材增加或产物生成，都必须同步回状态文件**。计划不是开工时写一次的文档，而是整个任务期间不断被修正的当前真相。 Loop 3 的顺序也值得注意：先 Read notes.md，再 create deliverable，最后 update plan。它强制模型从原始笔记里组织交付物，而不是从上下文记忆里凭印象写。笔记里有什么、出处是什么，写交付物时就能对上；记忆里剩下什么，只有模型自己知道。 再往下，SKILL.md 把三个动作和三个目的绑在一起： ```bash Read task_plan.md # Refresh goals in attention window Edit task_plan.md # Mark [x], update status Write notes.md # Don't stuff context, store in file ``` 用 bash 注释写「为什么」，是这份文件的一个小技巧。模型看到 `Read`、`Edit`、`Write` 就知道该调什么工具，看到注释就知道调用的目的。比起抽象地说「你应该保持计划更新」，这种写法把工具名、对象、意图压进三行里，执行成本低得多。 ## 五、模板逐字段：每个字段都在防一种失败 `task_plan.md` 的模板有六个区块，一个都不是装饰。 **Goal**：`[One sentence describing the end state]`。一句话，描述终态。这个约束逼你把「做一个数据分析系统」改写成「运营能在后台按周导出三类报表」。前者是方向，后者是验收条件。写不出终态，通常说明任务还没想清楚。 **Phases**：四个带 checkbox 的默认阶段——Plan and setup、Research/gather information、Execute/build、Review and deliver。它给了一个通用骨架，但不强制四段。checkbox 的价值不在好看，而在模型每次读文件时都能一眼看到「哪些已经 [x]」。 **Key Questions**：把未知显式列出来。这一栏防的是模型自作主张：遇到没定的问题时，它要么停下来问，要么替你做假设。先写进计划，等于把假设摊在桌面上。 **Decisions Made**：格式是「决策：理由」。它防的是反复摇摆——长任务里模型经常做到一半推翻前面的选择，有了这一栏，推翻之前至少要先读一遍当初为什么这么定。 **Errors Encountered**：格式是「错误：解决方式」。这栏是跨会话的疫苗。同一个报错第二次出现时，模型不用从零开始试。 **Status**：一行「Currently in Phase X - 我正在做什么」。这是给「下一个接手的自己」看的交接班记录。会话被清空、进程崩溃、换了一个模型，读这一行就能接上。 `notes.md` 的模板则只有两层：先 Sources，再 Synthesized Findings。每个来源记名称、URL、要点；综合判断单独成节。顺序不能反。先写综合、后补出处，很容易把推断写成事实；先存原始出处，再写综合，至少每个结论还能往回走一步。 ## 六、五条铁律：覆盖五个时间点 Critical Rules 一共五条： > 1. **ALWAYS Create Plan First** — Never start a complex task without `task_plan.md`. This is non-negotiable. > 2. **Read Before Decide** — Before any major decision, read the plan file. > 3. **Update After Act** — After completing any phase, immediately update the plan file. > 4. **Store, Don't Stuff** — Large outputs go to files, not context. Keep only paths in working memory. > 5. **Log All Errors** — Every error goes in the "Errors Encountered" section. 五条分别对应：开始前、决策前、行动后、存储时、出错时。时间点铺满了一个任务的全生命周期，没有一条是「态度要求」。 语气控制也很克制。「ALWAYS」只出现一次，「non-negotiable」只出现一次。整份文件没有满屏的大写和感叹号。规则的可信度靠稀缺性维持——如果每条都是 MUST，模型会把它们都当成背景噪音。 第四条是上下文工程的核心：**Store, Don't Stuff**。大块内容进文件，工作记忆里只留路径。这和「把上下文塞满」是两种完全不同的策略。前者的瓶颈是磁盘，后者的瓶颈是窗口；长任务里，窗口永远先满。 ## 七、When to Use / Skip for：给触发装刹车 这一节分两半。适用场景是五条：三步以上的任务、研究任务、构建类任务、跨多次工具调用的任务、需要组织的任务。不适用场景是三条： > **Skip for:** > - Simple questions > - Single-file edits > - Quick lookups 这三条是整份文件最被低估的部分。绝大多数 Skill 只写「我适合什么」，巴不得所有请求都触发自己。结果就是模型给一句「今天天气怎么样」也先建三个文件。这里明确列出否定场景，等于给触发词装了刹车。 尤其是 single-file edits。日常开发里大量请求都是改一个函数、修一行配置。这类任务创建计划文件、维护状态、回写进度，开销远大于收益。SKILL.md 自己承认这一点，反而让它在真正复杂的任务上更可信。 一个 Skill 的专业度，往往不看它说自己能干什么，而看它敢说自己不干什么。 ## 八、反模式表：把失败案例写成动作 Anti-Patterns 是两列表格，左边是「不要」，右边是「改成」： | Don't | Do Instead | |-------|------------| | Use TodoWrite for persistence | Create `task_plan.md` file | | State goals once and forget | Re-read plan before each decision | | Hide errors and retry | Log errors to plan file | | Stuff everything in context | Store large content in files | | Start executing immediately | Create plan file FIRST | 左列全是模型真实会犯的错，不是抽象的「不够好」。右列全是可执行动作，不是「要更加注意」。 第一行最见功力：它没有说 TodoWrite 不好，而是说「用 TodoWrite 做持久化」不好。工具本身没错，错在场景。TodoWrite 活在会话里，会话结束就没了；磁盘文件活在工作目录里，换一个会话还在。把这句话写成「不要用 TodoWrite」，会误导读者放弃一个有用的工具；写成「不要用 TodoWrite 做持久化」，边界就清楚了。 这种精确度，比多写十条口号有用。 ## 九、两个链接文件：渐进式披露的边界 SKILL.md 末尾没有把方法论铺完，而是留了两个入口： > See [reference.md](reference.md) for: Attention manipulation techniques / Error recovery patterns / Context optimization from Manus > > See [examples.md](examples.md) for: Real task examples / Complex workflow patterns 这是典型的渐进式披露：主文件只放「能跑通最小闭环」的内容，深水区放到链接里按需加载。好处是触发时 token 成本低，模型不会被一大堆暂时用不上的细节淹没。 代价也很明显：如果模型不点链接，深度内容等于不存在。所以主文件必须自足——读完这 100 多行，你应该能立刻开始用一个任务。reference.md 和 examples.md 是加速器，不是前提。 判断一个 Skill 的拆分是否合理，有个简单标准：把主文件单独拿走，能不能完成一次最小可用流程？这份文件可以。三文件表给了结构，四个 Loop 给了节奏，模板给了字段，铁律给了约束，停用条件给了边界。剩下的都是优化项。 ## 十、五个可以立刻复用的写法 拆完这份文件，真正能迁移到你自己 Skill 里的，是五个模式。 **1. 状态外置。** 凡是跨会话、跨压缩、跨崩溃的任务，都把状态从上下文搬到文件。文件是唯一不会因为窗口满了而消失的东西。 **2. 时间点绑定。** 不写「经常」「及时」「注意」，写 before deciding、after each phase、at completion。模型对事件敏感，对频率副词不敏感。 **3. 契约表格。** 用「对象 / 职责 / 时机」三列定义每个文件、每个工具、每个角色的边界。表格比段落更难含糊。 **4. 负向触发。** 除了「什么时候用我」，一定写「什么时候别用我」。否定条件越具体，触发精度越高。 **5. 反模式对照。** 把观察到的真实失败写在左列，把替代动作写在右列。模型不需要理解原则，照着右列做就行。 如果只记一条，记第二条。同一份方法论，写成「保持计划更新」和写成「每个阶段结束后立刻回写」，效果差一个量级。 ## 十一、边界与短板 这份 Skill 不是没有代价。 **它没有强制力。** SKILL.md 是建议，不是钩子。模型完全可能口头说「已更新计划」，实际没写文件。要硬约束，得在 Agent 外层加校验：检查文件修改时间、检查 Status 行是否变化、检查 checkbox 是否真的被勾选。纯文本协议解决的是「知不知道」，不解决「做不做」。 **小任务会被拖慢。** 三个文件、四轮循环、六段模板，对一次单文件修改来说是重税。SKILL.md 用 Skip for 主动放弃这类场景，是明智的，但使用者仍然要自己判断「复杂」的阈值。 **并发会打架。** 三个文件名是固定的。同一目录下并行跑两个任务，`task_plan.md` 会互相覆盖。实际使用时，应该给每个任务开子目录，把三件套放进去，而不是全部堆在工作区根目录。 **模板不保证判断。** 阶段拆错了，后面的 checkbox 只会把错误执行得更整齐。Goal 写不清楚，一句话终态反而会锁死一个模糊目标。文件是脚手架，不是设计师。 **笔记会无限膨胀。** `notes.md` 没有清理机制。研究型任务跑久了，笔记可能比交付物还大。需要自己加一条规则：每个阶段结束，把已经被计划吸收的素材折叠成结论，原始链接移到附录。 ## 十二、评测对比 把 planning-with-files 和另外两种常见做法放在一起看。评分是使用体验判断，不是基准测试。 | 方案 | 功能完整度 | 设计质量 | 实战效果 | 上手难度 | 社区活跃度 | 加权 | |------|-----------|---------|---------|---------|-----------|------| | planning-with-files | ★★★★☆ | ★★★★★ | ★★★★☆ | ★★★★★ | ★★★★☆ | 4.7 | | 内置 TodoWrite | ★★★☆☆ | ★★★☆☆ | ★★★☆☆ | ★★★★★ | ★★★★★ | 3.7 | | superpowers / writing-plans | ★★★★☆ | ★★★★☆ | ★★★★☆ | ★★★☆☆ | ★★★★★ | 4.2 | 三者的差别不在功能多少，而在状态活多久。TodoWrite 活在会话里，胜在零成本，输在一清空就没。writing-plans 把计划做成更重的流程件，适合需要评审和交接的团队，但学习曲线更陡。planning-with-files 卡在中间：比 TodoWrite 重，比完整流程件轻，靠三个文件和一套读写节奏撑住长任务。 ## 十三、安装与验证 安装有两种方式。用 skills CLI： ```bash npx skills add OthmanAdi/planning-with-files ``` 或者直接克隆到 Skills 目录： ```bash git clone https://github.com/OthmanAdi/planning-with-files \ ~/.claude/skills/planning-with-files ``` 装完不要只看它有没有出现在列表里，做一次真实回归： 1. 给 Agent 一个明确需要三步以上的任务，比如「调研三个竞品、整理对比表、写成一份 800 字简报」。 2. 观察它是否先创建 `task_plan.md`，再开始搜索。 3. 中途执行 `/clear` 或直接开一个新会话，让它「读计划继续」。 4. 检查 `Status` 是否指向当前阶段，`Errors Encountered` 是否有记录，`notes.md` 是否有出处。 第三步是关键。不能跨会话续跑，这个 Skill 的最大价值就没拿到。 ## 十四、工作流一张图 ```mermaid flowchart TD A["提出复杂任务"] --> B["创建 task_plan.md"] B --> C["定义阶段与关键问题"] C --> D["研究并写入 notes.md"] D --> E["回写计划状态"] E --> F["读 notes 生成交付物"] F --> G["更新计划并交付"] G --> H{"会话是否中断"} H -->|是| I["新会话读回计划"] I --> C H -->|否| J["结束"] ``` 这张图里最重要的不是方框，是两条回边：研究之后回写计划，交付之后回写计划。没有这两条回边，三文件就只是一次性的文档模板；有了它们，计划才变成活的。 ## 十五、按场景选 - **长程自治、跨会话任务**：planning-with-files。三文件加读写节奏，是目前最轻的持久化方案。 - **一次性小改、快速问答**：不要用。内置 TodoWrite 足够，甚至什么都不用。 - **需要评审、交接、多人接力的项目**：writing-plans 这类重流程件更合适，计划本身就是交付物。 - **最值得学的写法**：时间点绑定。把「经常更新」改成「每个阶段结束后立刻更新」，一句话就能让执行率上一个台阶。 - **最容易被忽略的写法**：Skip for。敢写自己不干什么，触发才准。 ## 十六、自己写一个的最小骨架 如果你要照着写一个同类 Skill，不必从三文件开始，先把五块写出来： ```markdown # 你的 Skill 名 一句话定位：用什么东西，解决什么失忆问题。 ## 三个时间点 - 开始前：创建什么文件 - 决策前：读什么文件 - 行动后：回写什么字段 ## 文件契约 | 文件 | 职责 | 更新时机 | |------|------|---------| ## 模板 （只放必需字段，每个字段写一句它防什么失败） ## 停用条件 - 什么情况下不要用我 ``` 五块齐了，再考虑要不要加 reference.md。主文件先做到「单独拿走也能跑」，这是渐进式披露的前提。 planning-with-files 真正稀缺的地方，不是它发明了「把计划写进文件」——这件事很多人都想过。它稀缺的是克制：三个文件、五个时间点、三条停用条件，没有一句多余的口号。一个 Skill 写到这个程度，读者不需要相信作者，只需要照着做。 ## 参考来源 1. [OthmanAdi/planning-with-files](https://github.com/OthmanAdi/planning-with-files) — 仓库与 SKILL.md、reference.md、examples.md 原文 2. [Claude Code Skills 文档](https://docs.claude.com/en/docs/claude-code/skills) — Skill 的加载机制与渐进式披露设计 3. [Equipping agents for the real world with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) — Agent Skills 的结构与设计原则 > [!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 等场景全覆盖。