| name | planning-with-files |
| description | 实现 Manus-style 的持久化 markdown 规划工作流。
**核心原理:**
- Context Window = RAM (volatile, limited)
- Filesystem = Disk (persistent, unlimited)
- 任何重要信息都要写入磁盘，而非塞入 context
**3文件模式:**
- task_plan.md - 跟踪阶段和进度
- findings.md - 存储研究和发现
- progress.md - 会话日志和测试结果
**触发条件:**
- 多步骤任务（3+步骤）
- 研究任务
- 构建/创建项目
- 跨越许多工具调用的复杂任务
**激活方式:**
- 命令: `/planning-with-files`
- 上下文: 检测到复杂任务规划需求时自动激活
|
Planning with Files Skill
Overview
本技能实现 Manus-style 的持久化 markdown 规划工作流，这是价值 $2B 的 AI 公司Manus的核心方法论。
核心原则:
"Markdown 是我在磁盘上的'工作内存'。由于我迭代处理信息且活跃 context 有上限，Markdown 文件作为便签、检查点、构建块服务于笔记、进度追踪和最终交付物。"
The 3-File Pattern
对于每个复杂任务，创建并维护三个核心文件：
1. task_plan.md - 任务规划
# Project: [项目名称]
## 目标
[描述项目要达成的目标]
## 阶段规划
- [ ] Phase 1: [阶段名称]
- [ ] 任务1.1
- [ ] 任务1.2
- [ ] Phase 2: [阶段名称]
- [ ] 任务2.1
- [ ] 任务2.2
- [ ] Phase 3: [阶段名称]
## 约束条件
- 技术约束
- 时间约束
- 资源约束
## 验收标准
- [ ] 标准1
- [ ] 标准2
2. findings.md - 研究发现
# 研究发现 - [主题]
## 背景信息
[收集的相关信息]
## 关键发现
1. 发现1
2. 发现2
3. 发现3
## 决策依据
- 选项A: [优缺点]
- 选项B: [优缺点]
- 最终选择: [理由]
## 待验证事项
- [ ] 事项1
- [ ] 事项2
3. progress.md - 进度日志
# 开发进度 - [日期]
## 会话开始
时间: [timestamp]
上下文摘要: [上次的进度]
## 已完成任务
- [x] 任务1 (时间戳)
- [x] 任务2 (时间戳)
## 当前进行中
- 任务3: [状态]
## 错误记录
### 错误1
- 时间: [timestamp]
- 问题: [描述]
- 解决方案: [如何修复]
- 教训: [避免重复]
## 下一步
- [ ] 任务4
- [ ] 任务5
Key Rules
1. 创建计划首先
永远不要在没有 task_plan.md 的情况下开始复杂任务。
2. 2-Action Rule
每 2 次 view/browser 操作后，将发现保存到 findings.md。
3. 记录所有错误
每次错误都要记录在 progress.md 中，帮助避免重复错误。
4. 永远不重复失败
跟踪尝试，记录什么方法不起作用，改变方法。
工作流程
Phase 1: 启动
当用户描述复杂任务时:
1. 解析任务需求
2. 创建 task_plan.md
3. 创建 findings.md
4. 创建 progress.md
5. 显示计划给用户确认
Phase 2: 执行
在每个工具调用前:
1. 重读 task_plan.md
2. 确认当前任务在计划中
3. 执行工具调用
每2次操作后:
1. 更新 progress.md
2. 保存重要发现到 findings.md
Phase 3: 恢复
当检测到上下文可能丢失时:
1. 检查 progress.md 的最后状态
2. 提取自上次更新后的会话
3. 显示catchup报告
4. 同步计划文件
Phase 4: 完成
当所有任务完成时:
1. 验证所有阶段标记为完成
2. 汇总 findings.md 的关键发现
3. 生成最终报告
4. 清理临时文件
验证清单:
- [ ] 所有阶段完成
- [ ] 测试通过
- [ ] 文档完整
- [ ] 代码审查完成
会话恢复机制
当上下文窗口填满并使用 /clear 后，本技能自动恢复工作：
恢复流程
- 检查
~/.claude/projects/ 中的会话数据
- 查找计划文件最后更新时间
- 提取可能丢失的对话内容
- 显示 catchup 报告供用户同步
最佳实践
- 禁用自动压缩: 在设置中关闭
auto-compact
- 使用完整 context: 最大化 context 利用
- 定期同步: 在 context 满前手动更新计划文件
- 恢复后检查: 运行
/planning-with-files 确认状态
触发条件
自动触发
- 用户开始复杂的多步骤任务
- 检测到研究或探索性工作需求
- 上下文窗口接近满载
- 长时间会话后的第一次操作
手动触发
/planning-with-files - 启动规划会话/planning-with-files:recover - 恢复会话/planning-with-files:status - 查看当前进度/planning-with-files:update - 强制更新计划文件
文件位置
项目根目录/
├── task_plan.md # 任务规划（必需）
├── findings.md # 研究发现（必需）
└── progress.md # 进度日志（必需）
或使用模板目录:
├── .planning/
│ ├── task_plan.md
│ ├── findings.md
│ └── progress.md
最佳实践
1. 命名约定
- 使用描述性文件名
- 在文件中包含项目标识
- 版本号用于重大更新
2. 定期更新
- 每完成一个子任务更新 progress.md
- 每发现关键信息更新 findings.md
- 计划变更时更新 task_plan.md
3. 提交版本控制
- 将计划文件纳入 Git
- 定期提交进度更新
- 使用有意义的提交信息
4. 团队协作
- 共享 task_plan.md
- 定期同步 findings.md
- 公开 progress.md 供团队查看
输出示例
启动新项目
## 规划会话启动
**项目:** Web应用开发
**时间:** 2026-01-21 10:30
### 已创建文件:
- ✅ task_plan.md
- ✅ findings.md
- ✅ progress.md
### 下一步:
请审阅 task_plan.md 并确认或修改计划。
确认后输入 "开始执行" 或 "/planning-with-files:execute"
进度更新
## 进度更新
**当前阶段:** Phase 2 - 后端API开发
**完成率:** 3/8 任务 (37.5%)
### 已完成:
- [x] 数据库设计 (10:15)
- [x] 用户认证模块 (10:42)
- [x] 基础API框架 (11:05)
### 进行中:
- 用户API端点: 75% 完成
### 错误记录:
- 11:02 - 数据库连接池配置错误 → 已修复
- 11:18 - JWT token过期问题 → 已修复
### 下一步:
- 完成用户API端点
- 开始订单模块
与其他 Skills 集成
配合 Superpowers
- 使用
superpowers:brainstorming 进行设计阶段
- 使用
superpowers:writing-plans 分解任务
- 使用
planning-with-files 维护持久状态
配合 Code Review
- 阶段完成后自动触发代码审查
- 审查结果记录到 findings.md
- 问题修复后更新 progress.md
故障排除
问题: 计划文件未自动创建
解决方案: 手动运行 /planning-with-files 或检查文件权限
问题: 会话恢复失败
解决方案:
- 检查 ~/.claude/projects/ 目录存在
- 验证计划文件未损坏
- 手动重建缺失的信息
问题: 上下文仍然溢出
解决方案:
- 增加保存频率
- 减少单次任务规模
- 使用更详细的 findings.md 减少 context 需求
配置选项
{
"planning-with-files": {
"autoCreate": true,
"autoUpdate": true,
"sessionRecovery": true,
"templateDir": ".planning",
"updateFrequency": "2-actions"
}
}
成功指标
- ✅ 任务完成率提升
- ✅ 上下文丢失减少
- ✅ 错误重复率降低
- ✅ 团队协作效率提升
