planning-with-files

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<br>
```<br>
仓库:https://github.com/OthmanAdi/planning-with-files<br>
### 第 2 步:验证 Skill<br>
向 AI 询问:<br>
```<br>
用 planning-with-files Skill,给一个 6 步骤的 plan 模板(目标/范围/步骤/风险/回滚/完成标准)<br>
```<br>
如果 AI 给出了完整模板,说明 Skill 加载成功。<br>
### 第 3 步:用 Skill 写第一个 plan<br>
```<br>
我要做"为 Next.js 项目加上 i18n 支持",这是多步骤任务,<br>
请用 planning-with-files Skill 帮我写到 docs/plans/i18n.md<br>
```<br>
AI 会按模板生成结构化 plan 文件,带 checkbox、依赖标注、回滚方案。<br>
## 常见踩坑<br>
1. **plan 写得太抽象**:每步只写"研究方案"而不写"具体要做什么、产出是什么",AI 做到一半就迷茫。<br>
2. **没设"完成标准"**:plan 里写"加测试",但没写"覆盖率 ≥ 80%",AI 自评"已经加测试"就勾完。务必在每步加 "Done when ..." 段。<br>
3. **plan 不迭代**:执行中遇到意外,plan 文件没同步更新,后续步骤对不上现实。Skill 强制"做完一步同步 plan"。<br>
4. **plan 嵌套太深**:plan 里引用 plan,plan 里又有子 plan,形成迷宫。建议每个 plan ≤ 20 步,大任务拆 plan 链。<br>
5. **没有回滚预案**:很多 plan 只写"如何做",不写"失败如何回滚",一旦线上事故找不到回退点。<br>
6. **plan 丢失**:在临时目录写 plan,系统重启后文件没了。建议 plan 都进 Git 仓库,永久可追溯。<br>
## 初级用法<br>
1. **新功能开发**:`目标 / 范围 / 任务拆解 / 验收标准 / 时间估算`,AI 写完后逐项推进。<br>
2. **代码重构**:`现状 / 目标 / 行为不变性验证 / 步骤 / 回滚`,避免重构破坏线上。<br>
3. **学习任务**:`目标知识点 / 资源 / 笔记位置 / 验证方式`,适合"用 AI 学新技术"。<br>
## 高级玩法<br>
1. **多 Agent 分工**:一个 plan 文件,子 Agent 各自认领步骤,完成时更新自己那段。<br>
2. **plan + 测试联动**:plan 里加"测试用例"段,每步完成后自动跑对应测试,通过才算 Done。<br>
3. **跨项目复用**:把通用 plan 模板(新功能、重构、迁移)放在共享仓库,新项目直接 fork。<br>
## 小技巧<br>
- 用 emoji 标 plan 状态:`📝 草稿` / `🚧 进行中` / `✅ 完成` / `❌ 失败`,一眼能看出阶段。<br>
- 每步加"预计耗时"和"实际耗时",复盘时能算 velocity。<br>
- plan 文件用 `YYYY-MM-DD-<task>.md` 命名,排序清晰,易归档。<br>
- 重要 plan 在 PR 里加 `do-not-merge` label,强制 review 通过才能 close。<br>
- 归档的 plan 加 frontmatter(plan_id、status、closed_at),方便后续做"项目历史数据库"。<br>
- 用 `git diff` 看 plan 的演化,和代码 commit 关联,完整看到"决策 → 落地"路径。<br>
## 常见问题 FAQ<br>
**Q1: 这个 Skill 跟 planning-with-files 有什么关系?必须装吗?**<br>
A: Skill 是给 AI Agent 用的"技能包",能告诉 Agent 怎么按特定规范工作。**不是必须装**——如果你的项目规模小、要求不高,不装也能用。但装上能让 Agent 输出的质量更高、更符合最佳实践,推荐装。<br>

**Q2: 这个 Skill 适合哪些 AI Agent?Cursor?Claude Code?其他?**<br>
A: planning-with-files 来自 community,主要面向支持 Skill 机制的 Agent。常见兼容 Agent 包括 Claude Code、Cursor、OpenCode、Windsurf 等。具体兼容性请查 Skill 官方文档。<br>

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

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

**Q5: 这个 Skill 有许可证吗?能商用吗?**<br>
A: 取决于 planning-with-files 的许可证。常见许可证包括 MIT(完全自由)、Apache-2.0(自由但有专利条款)、源可用(可看不能用)、GPL(强开源)。商用前请查仓库 LICENSE 文件。<br>
## 参考链接<br>
- [Skill 仓库](https://github.com/OthmanAdi/planning-with-files)<br>
- [Manus Agent 方法论(原始灵感)](https://manus.im/)<br>
- [Anthropic Claude 长上下文技巧](https://docs.anthropic.com/)<br>
- [agents.md 规范](https://agents.md)<br>
- [任务管理工具(Linear / Jira)与 AI 协作](https://linear.app/)<br>
## 实战经验:用 plan 模板跑一个"老项目 TypeScript 迁移"<br>
下面演示一个真实场景:把 3 年历史的 JavaScript 项目(300+ 文件)逐步迁移到 TypeScript。<br>
### 步骤 1:AI 写 plan 文件<br>
```<br>
用 planning-with-files Skill 帮我写一个 6 步骤迁移 plan,<br>
写到 docs/plans/ts-migration.md,涵盖:<br>
- 阶段 1:配置 TypeScript<br>
- 阶段 2:把工具函数(纯函数)迁移<br>
- 阶段 3:把数据模型(interface)迁移<br>
- 阶段 4:把业务组件迁移<br>
- 阶段 5:把 Controller / Handler 迁移<br>
- 阶段 6:清理 .js 文件 + 强化 strict 模式<br>
每步含"完成标准 / 测试要求 / 回滚方案"<br>
```<br>
AI 输出结构化 plan,含 checkbox、依赖关系、风险点。<br>
### 步骤 2:执行第一步<br>
按 plan 装好 TypeScript,`tsconfig.json` 用最宽松配置(`allowJs: true, strict: false`),先让项目能编译。<br>
### 步骤 3:更新 plan 状态<br>
完成阶段 1 后,在 plan 文件里把 `- [ ] 阶段 1:配置 TypeScript` 改成 `- [x]`,并 commit:<br>
```bash<br>
git add docs/plans/ts-migration.md<br>
git commit -m "docs(plan): mark stage 1 done"<br>
```<br>
### 步骤 4:跨会话续命<br>
第二天重新打开 Claude Code,先说"读 docs/plans/ts-migration.md,继续阶段 2",AI 立即从上次断点接续,不用重新交代背景。<br>
### 步骤 5:阶段 review<br>
每完成 1-2 阶段做一次"自我 review":检查 plan 里"风险评估"是否兑现,如果出现新风险,加进 plan 末尾的"复盘记录"。<br>
## 配合使用的工具链<br>
- **Git**:plan 文件随项目演进进入版本控制,`git log --follow plan.md` 看完整演化。<br>
- **Obsidian / Notion**:在个人知识库同步 plan,跨设备可读。<br>
- **GitHub Projects / Linear**:把 plan 里的"步骤"映射成 issue/卡片,看板视图更直观。<br>
- **markdownlint**:统一 plan 文件格式,Skill 输出的 plan 默认符合规范。<br>
- **`jq` + `yq`**:把 plan 解析成 JSON/YAML,做后续自动化(比如把每步转成 Linear issue)。<br>
## Plan 模板的最佳实践<br>
1. **目标**:用一句话说清"做完这件事的标准"。<br>
2. **范围**:明确"包含什么 / 不包含什么",避免 scope creep。<br>
3. **步骤**:每步带 checkbox,完成时勾选。<br>
4. **依赖**:列出"必须先做完什么才能做这一步"。<br>
5. **风险**:识别可能出问题的地方 + 应对方案。<br>
6. **回滚**:出问题如何回到上一稳定状态。<br>
7. **完成标准**:可量化的判断"这一步真的完成了"。<br>
完整模板可以放在 `docs/plans/TEMPLATE.md`,新 plan 复制修改即可。