planning-with-files 快速入门

“文件即计划”理念的标准版实现,AI 写复杂任务时不再”半路失忆”。

这是什么?解决什么问题?

planning-with-files 与 othmanadi-planning-with-files 出自同一份仓库(OthmanAdi/planning-with-files),slug 不同但内容接近。本质都是 Manus Agent 方法论的开源复现:把”AI Agent 处理复杂任务”的核心约束——上下文窗口有限、信息容易丢失、多步任务难以追踪——用文件系统来兜底。

它和 othmanadi-planning-with-files 的区别在于:这个 Skill 更”标准版”,聚焦在通用 Agent 工作流(写 plan → 拆任务 → 执行 → 归档),不和特定工作目录(.plan.md 还是 MASTER_PLAN.md)绑定,适合需要灵活组织 plan 的团队。

加载 Skill 后,AI 在面对多步骤任务时会主动:把任务拆解写入文件、每完成一步更新状态、跨会话时读取 plan 续命、做完把 plan 归档到 history。

适合:从 0 启动的 AI Agent 项目、需要处理 10+ 步骤工作流的工程师、希望建立”AI 任务可追溯”流程的团队。

准备工作

1. Claude Code / Cursor / 任何支持 Skill 的 AI 客户端
2. Git 仓库:用 Git 跟踪 plan 文件变更
3. 可选:docs/plans/ 目录存放进行中的 plan,docs/plans/history/ 归档
4. 可选:Markdown 渲染工具(在 IDE 实时预览)

3 步快速上手

第 1 步:安装 Skill

npx skills add OthmanAdi/planning-with-files --skill planning-with-files

仓库:https://github.com/OthmanAdi/planning-with-files

第 2 步:验证 Skill

向 AI 询问:

用 planning-with-files Skill,给一个 6 步骤的 plan 模板(目标/范围/步骤/风险/回滚/完成标准)

如果 AI 给出了完整模板,说明 Skill 加载成功。

第 3 步:用 Skill 写第一个 plan

我要做"为 Next.js 项目加上 i18n 支持",这是多步骤任务,
请用 planning-with-files Skill 帮我写到 docs/plans/i18n.md

AI 会按模板生成结构化 plan 文件,带 checkbox、依赖标注、回滚方案。

常见踩坑

1. plan 写得太抽象:每步只写”研究方案”而不写”具体要做什么、产出是什么”,AI 做到一半就迷茫。
2. 没设”完成标准”:plan 里写”加测试”,但没写”覆盖率 ≥ 80%“,AI 自评”已经加测试”就勾完。务必在每步加 “Done when …” 段。
3. plan 不迭代:执行中遇到意外,plan 文件没同步更新,后续步骤对不上现实。Skill 强制”做完一步同步 plan”。
4. plan 嵌套太深:plan 里引用 plan,plan 里又有子 plan,形成迷宫。建议每个 plan ≤ 20 步,大任务拆 plan 链。
5. 没有回滚预案:很多 plan 只写”如何做”,不写”失败如何回滚”,一旦线上事故找不到回退点。
6. plan 丢失:在临时目录写 plan,系统重启后文件没了。建议 plan 都进 Git 仓库,永久可追溯。

初级用法

1. 新功能开发:目标 / 范围 / 任务拆解 / 验收标准 / 时间估算,AI 写完后逐项推进。
2. 代码重构:现状 / 目标 / 行为不变性验证 / 步骤 / 回滚,避免重构破坏线上。
3. 学习任务:目标知识点 / 资源 / 笔记位置 / 验证方式,适合”用 AI 学新技术”。

高级玩法

1. 多 Agent 分工:一个 plan 文件,子 Agent 各自认领步骤,完成时更新自己那段。
2. plan + 测试联动:plan 里加”测试用例”段,每步完成后自动跑对应测试,通过才算 Done。
3. 跨项目复用:把通用 plan 模板(新功能、重构、迁移)放在共享仓库,新项目直接 fork。

小技巧

• 用 emoji 标 plan 状态:📝 草稿 / 🚧 进行中 / ✅ 完成 / ❌ 失败,一眼能看出阶段。
• 每步加”预计耗时”和”实际耗时”,复盘时能算 velocity。
• plan 文件用 YYYY-MM-DD-<task>.md 命名,排序清晰,易归档。
• 重要 plan 在 PR 里加 do-not-merge label,强制 review 通过才能 close。
• 归档的 plan 加 frontmatter(plan_id、status、closed_at),方便后续做”项目历史数据库”。
• 用 git diff 看 plan 的演化,和代码 commit 关联,完整看到”决策 → 落地”路径。

常见问题 FAQ

Q1: 这个 Skill 跟 planning-with-files 有什么关系?必须装吗?

A: Skill 是给 AI Agent 用的”技能包”,能告诉 Agent 怎么按特定规范工作。不是必须装——如果你的项目规模小、要求不高,不装也能用。但装上能让 Agent 输出的质量更高、更符合最佳实践,推荐装。

Q2: 这个 Skill 适合哪些 AI Agent?Cursor?Claude Code?其他?

A: planning-with-files 来自 community,主要面向支持 Skill 机制的 Agent。常见兼容 Agent 包括 Claude Code、Cursor、OpenCode、Windsurf 等。具体兼容性请查 Skill 官方文档。

Q3: 装了这个 Skill 后,会拖慢 Agent 响应吗?

A: 会的——Skill 通常会增加 prompt 长度,导致响应变慢、token 消耗增加。但质量提升明显。建议:1) 只装项目必需的 Skill;2) 用 Skill 启动/加载/卸载机制按需加载;3) 定期清理不用的 Skill。

Q4: 怎么验证 Skill 装对了?

A: 在 Agent 中输入”列出已加载的 Skill”或类似命令。如果 Skill 出现在列表里,说明装对了。然后用 Skill 跑一个相关任务,看输出是否符合 Skill 规范。

Q5: 这个 Skill 有许可证吗?能商用吗?

A: 取决于 planning-with-files 的许可证。常见许可证包括 MIT(完全自由)、Apache-2.0(自由但有专利条款)、源可用(可看不能用)、GPL(强开源)。商用前请查仓库 LICENSE 文件。

参考链接

• Skill 仓库:https://github.com/OthmanAdi/planning-with-files
• Manus Agent 方法论(原始灵感):https://manus.im/
• Anthropic Claude 长上下文技巧:https://docs.anthropic.com/
• agents.md 规范:https://agents.md
• 任务管理工具(Linear / Jira)与 AI 协作:https://linear.app/

实战经验:用 plan 模板跑一个”老项目 TypeScript 迁移”

下面演示一个真实场景:把 3 年历史的 JavaScript 项目(300+ 文件)逐步迁移到 TypeScript。

步骤 1:AI 写 plan 文件

用 planning-with-files Skill 帮我写一个 6 步骤迁移 plan,
写到 docs/plans/ts-migration.md,涵盖:
- 阶段 1:配置 TypeScript
- 阶段 2:把工具函数(纯函数)迁移
- 阶段 3:把数据模型(interface)迁移
- 阶段 4:把业务组件迁移
- 阶段 5:把 Controller / Handler 迁移
- 阶段 6:清理 .js 文件 + 强化 strict 模式
每步含"完成标准 / 测试要求 / 回滚方案"

AI 输出结构化 plan,含 checkbox、依赖关系、风险点。

步骤 2:执行第一步

按 plan 装好 TypeScript,tsconfig.json 用最宽松配置(allowJs: true, strict: false),先让项目能编译。

步骤 3:更新 plan 状态

完成阶段 1 后,在 plan 文件里把 - [ ] 阶段 1:配置 TypeScript 改成 - [x],并 commit:

git add docs/plans/ts-migration.md
git commit -m "docs(plan): mark stage 1 done"

步骤 4:跨会话续命

第二天重新打开 Claude Code,先说”读 docs/plans/ts-migration.md,继续阶段 2”,AI 立即从上次断点接续,不用重新交代背景。

步骤 5:阶段 review

每完成 1-2 阶段做一次”自我 review”:检查 plan 里”风险评估”是否兑现,如果出现新风险,加进 plan 末尾的”复盘记录”。

配合使用的工具链

• Git:plan 文件随项目演进进入版本控制,git log --follow plan.md 看完整演化。
• Obsidian / Notion:在个人知识库同步 plan,跨设备可读。
• GitHub Projects / Linear:把 plan 里的”步骤”映射成 issue/卡片,看板视图更直观。
• markdownlint:统一 plan 文件格式,Skill 输出的 plan 默认符合规范。
• jq + yq:把 plan 解析成 JSON/YAML,做后续自动化(比如把每步转成 Linear issue)。

Plan 模板的最佳实践

1. 目标:用一句话说清”做完这件事的标准”。
2. 范围:明确”包含什么 / 不包含什么”,避免 scope creep。
3. 步骤:每步带 checkbox,完成时勾选。
4. 依赖:列出”必须先做完什么才能做这一步”。
5. 风险:识别可能出问题的地方 + 应对方案。
6. 回滚:出问题如何回到上一稳定状态。
7. 完成标准:可量化的判断”这一步真的完成了”。

完整模板可以放在 docs/plans/TEMPLATE.md,新 plan 复制修改即可。

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。如有错误或过时信息，请通过 contact@magicnetworld.com 反馈。