planning-with-files

planning-with-files 技能概览

planning-with-files 实际能做什么

planning-with-files skill 为 AI agent 提供了一套简单、可持续的规划机制：它不是依赖短暂的聊天上下文记忆，而是把工作过程落到 markdown 文件里。它的核心模式是 3 个文件协同：task_plan.md 用来记录阶段和状态，notes.md 用来沉淀研究过程与发现，最后再产出一个交付文件，比如 output.md。如果你需要在多步骤任务中稳定追踪进展，并且希望这个过程可重复、可恢复，这就是安装 planning-with-files 的真正理由。

谁适合使用 planning-with-files

planning-with-files 最适合处理会跨多个步骤、甚至跨多个会话展开的工作，比如研究、迁移、审计、分析、内容策划，以及一般性的项目组织。尤其当你希望 agent 能记住它已经学到的内容，而不是每次都把上下文重新贴一遍时，这个技能会非常有用。

最适合解决的任务类型

当你的真实需求不是“写一个答案”，而是“持续维护一个计划、收集证据，并在不中断思路的情况下产出结果”时，就应该使用 planning-with-files skill。因此，planning-with-files for Project Management 很适合做轻量级的执行跟踪，但并不适合替代重型 PM 框架。

相比普通 prompt，它的关键差异是什么

普通 prompt 也可以让 agent 给你一个计划，但 planning-with-files 改变的是工作方式本身。它会推动 agent 把计划、笔记和输出外化到文件里，这样即使上下文被重置、或者经历很长的工具调用过程，工作状态也不会丢失。这个价值比任何单条 prompt 的措辞都更重要。

哪些场景不适合用 planning-with-files

如果只是非常小的一次性问题、纯聊天式头脑风暴，或者 PRD 专用工作流，就不建议用 planning-with-files。仓库里已经明确说明，PRD 相关任务应交给 prd-planner。另外，如果你不希望 agent 在工作区里创建文件，这个技能会明显比通用 prompt 更“重”。

如何使用 planning-with-files skill

planning-with-files 的安装上下文

这个仓库在 SKILL.md 里没有提供专门的安装命令，因此用户通常会从 skill collection 仓库中添加它：

npx skills add https://github.com/zhaono1/agent-playbook --skill planning-with-files

这个技能默认运行在 agent 可以创建并更新 markdown 文件的环境中。它声明依赖的工具包括 Read、Write、Edit、Bash、Grep 和 Glob。

planning-with-files 预期会创建哪些文件

实际使用中的默认模式通常是：

• task_plan.md — 目标、阶段、状态、下一步
• notes.md — 研究记录、发现、决策、参考资料
• [deliverable].md — 最终交付物，例如 output.md

如果你准备在现有仓库里采用 planning-with-files usage，除非本地已有明确命名规范，否则尽量保留这些文件名。文件名保持一致，能显著减少 agent 的理解偏差和混乱。

正式采用前，建议先读什么

建议按这个顺序阅读：

1. skills/planning-with-files/SKILL.md
2. skills/planning-with-files/README.md

SKILL.md 负责定义这套技能的运行方式。README.md 更短，适合先快速判断是否匹配你的需求。这个路径下没有额外的规则文件、资源文件或辅助脚本，所以它的价值主要不在“隐藏自动化”，而在于你是否真正理解这套工作流模式。

用户通常怎么触发 planning-with-files

在实际使用中，大家通常会用类似这样的请求来触发这个技能：

• “Plan a multi-step migration and track progress in files.”
• “Create a research plan and save notes and deliverables.”
• “Organize this project with persistent task files.”

这些用法之所以有效，是因为它们天然暗示了任务有多个阶段，而不是只需要一次性输出一个回复。

如何把模糊目标改写成高质量 prompt

弱 prompt：

• “Help me migrate this app.”

更适合 planning-with-files 的 prompt：

• “Use planning-with-files to create task_plan.md, notes.md, and migration-output.md for a React to Next.js migration. Break the work into phases, track open risks, save findings in notes.md, and keep task_plan.md updated as you go.”

为什么后者更好：

• 明确点出了基于文件的工作流
• 指定了具体交付物
• 表明笔记需要持续保留
• 要求 agent 持续更新计划，而不只是先列一个初始提纲

哪些输入会明显提升输出质量

如果可以，最好一开始就提供这些信息：

• 目标是什么
• 约束条件是什么
• 当前仓库或源材料有哪些
• 截止时间或优先级顺序
• 希望使用的交付文件名
• 什么算“完成”

例如：

• Goal: audit onboarding flow and suggest fixes
• Constraints: no code changes, only analysis
• Inputs: /docs, /src/onboarding, analytics summary
• Deliverable: onboarding-audit.md
• Done means: findings, ranked issues, recommended actions

如果没有这些信息，agent 依然能创建文件，但计划内容往往会停留在比较泛的层面。

推荐的 workflow 循环

一份高质量的 planning-with-files guide，通常会遵循这样的节奏：

1. 创建 task_plan.md，写清目标和阶段。
2. 研究或检查源材料。
3. 将发现写入 notes.md。
4. 更新 task_plan.md，记录进度、阻塞项和下一步行动。
5. 基于 notes.md 起草最终交付物。
6. 在定稿前标记剩余缺口。

真正重要的是这个循环本身，而不只是最开始把文件创建出来。

planning-with-files for Project Management 的适用场景

对于 planning-with-files for Project Management，更适合把它理解为轻量级协同工具，而不是企业级 PM 系统。典型适用场景包括：

• 迁移规划
• 研究跟踪
• 实施清单
• 内容生产流程
• 技术审计
• 依赖调查

当 agent 既需要发现信息，又需要把这些信息整理成最终输出时，它的效果最好。

常见采用障碍

大家在上手时遇到的障碍，通常是实践层面的，而不是理念层面的：

• 用户希望在非常小的任务上立刻看到价值
• 没有给 agent 一个明确的交付物
• 从来没有要求 agent 持续更新 task_plan.md
• 团队已经有严格的项目文件结构，不希望新增顶层文件

如果你符合其中任何一种情况，建议在安装前先判断：你到底需要的是这种固定模式，还是只是一次性的规划 prompt。

文件放置的实用建议

仓库示例使用的是简单的根目录文件名，这对独立任务完全没问题。但在繁忙项目中，把这些文件放到一个任务目录里，例如 /workstreams/migration/，通常会更清晰。如果你这么做，记得在 prompt 里明确写出完整路径，避免 agent 把文件分散到不同位置。

planning-with-files skill 常见问题

planning-with-files 比在聊天里直接要一个计划更好吗？

对于多步骤任务，通常是的。它的优势在于可持续性和可追溯性。planning-with-files 会把不断演进的计划和发现保存到文件中，因此 agent 重新接手任务时更不容易跑偏。如果你只是一次性要个提纲，普通 prompt 反而更简单。

planning-with-files skill 对新手友好吗？

友好，因为模式本身很简单：一个计划文件、一个笔记文件、一个输出文件。新手最常见的错误，是把它用在太小的任务上，导致文件管理的成本高于收益。

planning-with-files 是否要求特定项目类型？

不要求。这套模式本来就是刻意设计成通用型的。只要 agent 能够读写文件，它就可以支持工程、研究、运营、写作或分析类任务。

什么情况下不该使用 planning-with-files？

以下场景不建议使用 planning-with-files：

• 只需要一轮回答的问题
• 纯对话式的创意发散
• 无法写入文件的任务环境
• 更适合由 prd-planner 处理的 PRD 专用工作流

它和任务追踪器或 TodoWrite 有什么不同？

这个 skill 解决的是另一类问题：可持续的工作记忆。任务追踪器可以列出待办事项，但 planning-with-files 会把计划、证据和最终输出，用普通 markdown 文件串联起来，方便 agent 之后重新打开并继续扩展。

planning-with-files 是否自带自动化或脚本？

在这个 repo 路径下，没有。它的核心价值就是工作流模式本身，而不是打包好的工具链。这让它很容易理解，但也意味着输出质量会很大程度上取决于你是否把任务定义得足够清楚。

如何改进 planning-with-files skill 的使用效果

用更清晰的任务框架启动 planning-with-files

想让 planning-with-files 更快产出高质量结果，最有效的方法就是在一开始提供清晰的任务框架：范围、约束条件，以及明确命名的交付物。“Research this” 太弱；“Investigate auth failures, save findings in notes.md, and produce auth-failure-analysis.md with root causes and fixes” 就强得多。

不只让它建文件，还要要求持续更新文件

一个常见失败模式是：agent 只在一开始创建了三个文件，后面大部分工作又回到了聊天里。你应该明确要求它在每个主要步骤后更新 task_plan.md，并把有实质内容的发现写进 notes.md。这样这套 workflow 才会真正持续运转。

长任务要明确拆成阶段

如果任务比较复杂，最好要求 agent 在 task_plan.md 中按阶段组织内容，例如 discovery、analysis、execution、validation 和 handoff。相比一张没有层次的 checklist，这样的结构能让 skill 更容易发挥作用。

通过证据要求提升 notes 质量

当你明确要求 notes.md 包含以下内容时，它会变得更有价值：

• source paths 或 references
• assumptions
• open questions
• decisions made
• rejected options

这样一来，笔记就不再只是临时草稿，而会变成可复用的工作记忆。

用交付物规格减少泛泛输出

如果最终文件应该是一份决策 memo、迁移 checklist、审计报告，或者实施计划，就直接说清楚。planning-with-files skill 能具体到什么程度，很大程度上取决于你定义的目标输出有多具体。

第一轮效果弱时，如何补救

如果第一次跑出来的结果比较浅，不要立刻从零重来。可以让 agent：

1. 检查 task_plan.md 是否缺少关键阶段
2. 用更多证据和未解决问题来充实 notes.md
3. 基于更新后的笔记重写交付物

相比重新从头 prompt，这种方式通常能更快提升质量。

有意识地让文件模式适配你的工作区

默认的 3 文件模式之所以好用，就在于它足够简洁。除非你的团队已经有很值得对齐的结构，否则建议先保持这一模式不变。如果你要重命名文件，或者把它们移到子目录里，一定要明确写出准确路径，这样 planning-with-files usage 才能在跨会话时保持一致。

将 planning-with-files 和源材料检查结合起来

当 agent 手头有真实材料可供检查时，这个 skill 会更强，比如仓库目录、文档、日志、issue 列表或需求说明。如果你给它的只有一个抽象目标，workflow 仍然可以运转，但产出的文件更可能像占位内容，而不是有依据的实际工作成果。

注意最明显的不匹配信号

判断 planning-with-files 是否不适合当前任务，最明显的信号就是：这些计划文件开始变成官僚负担，而不是实际帮助。如果这个任务用一次专注的直接回答就能很好解决，那就别引入额外开销，直接用普通 prompt 更合适。