让 AI 编程不再"失忆"：planning-with-files 插件完全指南
GitHub 暴涨 11.7k Star！ 复刻 Manus 核心秘诀的开源插件，让你的 AI 编程助手拥有持久化记忆能力
前言：AI 编程的"失忆"困境
你是否遇到过这样的场景：
你: "帮我构建一个 Next.js 博客系统，支持 Markdown 和暗黑模式"
AI: "好的！让我开始..." [进行 50+ 次工具调用]
你: "等一下，我们的目标是支持 Markdown 吗？"
AI: "对不起，我有点迷失了...你能再提醒我一下要做什么吗？"
这就是 AI 编程助手的核心问题：
| 问题 | 症状 | 影响 |
|---|---|---|
| 易失记忆 | TodoWrite 工具在上下文重置后消失 | 下次会话从头开始 |
| 目标漂移 | 50+ 次工具调用后忘记原始目标 | 偏离用户需求 |
| 隐藏错误 | 失败没有被记录，反复踩坑 | 浪费时间和 tokens |
| 上下文堆砌 | 所有信息塞进上下文 | 达到 token 上限 |
解决方案：Manus AI 的 20 亿美元秘密
2025 年 12 月 29 日，Meta 以 20 亿美元收购了 Manus AI。这家公司在短短 8 个月内从启动到 1 亿美元营收，他们的秘密是什么？
"Markdown 是我的'工作记忆'磁盘。由于我迭代式处理信息且活跃上下文有限，Markdown 文件作为笔记的草稿纸、进度的检查点、最终交付物的构建块。" — Manus AI
核心原理：
┌─────────────────────────────────────────────────────────────┐
│ 传统模式 vs 3-File 模式 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 传统模式: 3-File 模式: │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ 上下文窗口 │ ← 堆满 → │ 上下文窗口 │ ← 只放当前需要│
│ │ (RAM) │ │ (RAM) │ │
│ └─────────────┘ └─────────────┘ │
│ ↓ ↓ │
│ ❌ 易失 (volatile) ✅ 持久 (persistent) │
│ ❌ 有限 (limited) ✅ 无限 (unlimited) │
│ │
│ ↓ │
│ ┌─────────────┐ │
│ │ 文件系统 │ │
│ │ (Disk) │ │
│ │ task_plan │ │
│ │ findings │ │
│ │ progress │ │
│ └─────────────┘ │
└─────────────────────────────────────────────────────────────┘
核心公式：
Context Window = RAM (易失、有限)
Filesystem = Disk (持久、无限)
→ 任何重要信息都写入磁盘
什么是 planning-with-files？
planning-with-files 是一个开源 Claude Code 插件，实现了 Manus AI 的三文件持久化规划模式。
核心机制：3-File 模式
your-project/
├── task_plan.md ← 阶段划分 + 进度追踪 (checkbox)
├── findings.md ← 研究发现 + 技术决策 (知识库)
└── progress.md ← 会话日志 + 测试结果 (时间线)
三大文件详解
| 文件 | 作用 | 更新时机 | 示例内容 |
|---|---|---|---|
| task_plan.md | 任务分解和进度追踪 | 创建时 + 每次决策前 | Phase 1: 初始化 - [x] 创建项目 - [ ] 配置 TS |
| findings.md | 研究发现和技术决策 | 每两次查看操作后 | ## 技术选型 - 选择 @mdx-js/loader - 原因：需要自定义插件 |
| progress.md | 会话日志和测试结果 | 会话结束时 | ### 2024-02-10 - ✅ Phase 1 完成 - ⚠️ 遇到 TS 配置问题 |
快速上手
安装（三种方式）
方式一：Claude Code 插件市场（推荐）
# 添加插件
/plugin marketplace add OthmanAdi/planning-with-files
# 安装
/plugin install planning-with-files@planning-with-files
# 完成！现在可以使用：
/plan # 开始规划
/plan:status # 查看进度
方式二：手动安装到本地 skills
# macOS/Linux
cp -r ~/.claude/plugins/cache/planning-with-files/planning-with-files/*/skills/planning-with-files ~/.claude/skills/
# Windows (PowerShell)
Copy-Item -Recurse -Path "$env:USERPROFILE\.claude\plugins\cache\planning-with-files\planning-with-files\*\skills\planning-with-files" -Destination "$env:USERPROFILE\.claude\skills\"
方式三：其他 IDE
| IDE | 支持状态 | 安装方式 |
|---|---|---|
| Gemini CLI | ✅ 完整支持 | Agent Skills |
| Cursor | ✅ 完整支持 | Skills + Hooks |
| OpenClaw | ✅ 完整支持 | Workspace Skills |
| Kiro | ✅ 完整支持 | Steering Files |
| Continue | ✅ 完整支持 | Skills + Prompts |
| Codex | ✅ 完整支持 | Personal Skill |
使用方法深度解析
1. 三种启动命令
命令一：/plan - 开始新规划（推荐）
你: /plan
Claude: 太好了！让我们开始规划会话。
请描述您想要完成的任务，我会帮您：
1. 创建结构化的任务计划
2. 跟踪研究发现和中间结果
3. 记录进度和测试结果
您的任务是什么？
你: 我想用 Next.js 构建一个博客系统，需要支持 Markdown、暗黑模式和评论功能
Claude: 明白了！我将帮您构建 Next.js 博客系统。
正在创建规划文件...
✅ task_plan.md - 任务分解和进度追踪
✅ findings.md - 研究发现和技术决策
✅ progress.md - 会话日志和测试结果
现在让我们从 Phase 1 开始...
命令二：/plan:status - 查看当前进度
你: /plan:status
Claude:
┌─────────────────────────────────────────┐
│ 📋 当前规划状态 │
├─────────────────────────────────────────┤
│ 任务: Next.js 博客系统 │
│ 进度: ████████░░░░░░░░ 40% │
│ │
│ ✅ Phase 1: 项目初始化 │
│ ✅ Phase 2: 基础页面 │
│ 🔄 Phase 3: Markdown 支持 (进行中) │
│ ⏳ Phase 4: 暗黑模式 │
│ ⏳ Phase 5: 评论系统 │
└─────────────────────────────────────────┘
命令三：/planning-with-files:start - 传统启动
# 兼容旧版本的启动方式
/planning-with-files:start
# 或简写
/planning
2. 首次使用完整流程
Step 1: 命令触发
你: /plan
Claude: 让我们设置您的规划会话！
请描述您想要完成的任务...
Step 2: AI 分析并创建文件
Claude: 正在创建规划文件...
✅ task_plan.md - 任务分解和进度追踪
✅ findings.md - 研究发现和技术决策
✅ progress.md - 会话日志和测试结果
Step 3: 文件结构预览
your-project/
├── task_plan.md
│ ├── Phase 1: 项目初始化
│ │ ├── [ ] 创建 Next.js 项目
│ │ ├── [ ] 配置 TypeScript
│ │ └── [ ] 设置 ESLint/Prettier
│ ├── Phase 2: 基础页面
│ ├── Phase 3: Markdown 支持
│ └── ...
├── findings.md
│ └── ## 技术选型
│ - 使用 next-mdx-renderer
│ - 使用 rehype 插件
└── progress.md
└── ### 2024-02-10 14:30
- ✅ 创建项目骨架
- 🔄 配置 TypeScript 中...
3. Hooks 自动化工作流（核心机制）
planning-with-files 的魔力来自三个自动触发的 Hooks：
PreToolUse Hook - 决策前重读计划
┌─────────────────────────────────────────────────────────────┐
│ PreToolUse Hook │
├─────────────────────────────────────────────────────────────┤
│ │
│ 用户操作 → Hook 触发 → 读取 task_plan.md → AI 了解进度 → 执行 │
│ │
│ 示例场景: │
│ ───────────────────────────────────────────────────────── │
│ 用户: "添加评论功能" │
│ │
│ Hook: 📋 读取 task_plan.md... │
│ Phase 3 还在进行中，Phase 5 是评论功能 │
│ 建议先完成 Phase 3 │
│ │
│ AI: "我注意到 Phase 3 (Markdown 支持) 还未完成。 │
│ 建议先完成 Markdown 渲染，再添加评论功能。 │
│ 要继续 Phase 3 还是直接跳到 Phase 5？" │
│ │
└─────────────────────────────────────────────────────────────┘
PostToolUse Hook - 操作后提醒保存
┌─────────────────────────────────────────────────────────────┐
│ PostToolUse Hook │
├─────────────────────────────────────────────────────────────┤
│ │
│ AI 操作完成 → Hook 检查计数 → 提醒保存 findings │
│ │
│ 示例场景: │
│ ───────────────────────────────────────────────────────── │
│ AI: [读取了 2 个文件] │
│ │
│ Hook: 📝 检测到连续 2 次查看操作 │
│ 建议将发现保存到 findings.md │
│ │
│ AI: "我查看了两个文档配置文件。 │
│ 我发现 next.config.js 需要 experimental 特性。 │
│ 让我将这个发现记录到 findings.md..." │
│ │
└─────────────────────────────────────────────────────────────┘
Stop Hook - 完成前验证
┌─────────────────────────────────────────────────────────────┐
│ Stop Hook │
├─────────────────────────────────────────────────────────────┤
│ │
│ 用户退出 → Hook 触发 → 检查所有 Phase → 生成报告 │
│ │
│ 示例输出: │
│ ───────────────────────────────────────────────────────── │
│ 📊 会话完成报告 │
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
│ │
│ 任务完成度: 60% │
│ │
│ ✅ 已完成: │
│ - Phase 1: 项目初始化 (3/3) │
│ - Phase 2: 基础页面 (2/2) │
│ │
│ 🔄 进行中: │
│ - Phase 3: Markdown 支持 (2/4) │
│ ✓ 已安装 next-mdx-renderer │
│ ✓ 已配置 rehype 插件 │
│ ✗ 待处理: 代码高亮 │
│ ✗ 待处理: 图片优化 │
│ │
│ ⏳ 未开始: │
│ - Phase 4: 暗黑模式 │
│ - Phase 5: 评论系统 │
│ │
│ 下次继续时使用: /plan:status │
│ │
└─────────────────────────────────────────────────────────────┘
最佳实践深度指南
实践 1: 任务拆分的艺术
❌ 错误拆分 - 太粗糙
## Phase 1: 开发博客
- [ ] 完成所有功能
✅ 正确拆分 - 粒度适中
## Phase 1: 项目初始化
- [ ] 创建 Next.js 项目 (使用 `npx create-next-app@latest`)
- [ ] 配置 TypeScript (启用严格模式)
- [ ] 设置 ESLint 和 Prettier
- [ ] 配置 Git (.gitignore, husky)
## Phase 2: 核心布局
- [ ] 创建 Layout 组件
- [ ] 实现响应式导航栏
- [ ] 添加暗黑模式切换
- [ ] 配置全局样式
## Phase 3: Markdown 系统
- [ ] 选择 MDX 处理器
- [ ] 实现代码高亮
- [ ] 添加图片优化
- [ ] 配置 frontmatter 解析
拆分原则:
- 每个 Phase 2-6 个任务
- 每个任务 30 分钟 - 2 小时可完成
- 按逻辑依赖顺序排列
- 使用动词开头（创建、配置、实现）
实践 2: Findings 的黄金结构
标准 findings.md 模板:
# Research Findings
## 技术选型
### MDX 处理器对比
| 方案 | 优点 | 缺点 | 结论 |
|------|------|------|------|
| next-mdx | 官方支持 | 功能有限 | ❌ 不够灵活 |
| next-mdx-enhanced | 功能丰富 | 维护较少 | ⚠️ 备选 |
| @mdx-js/loader | 生态成熟 | 配置复杂 | ✅ 选择此方案 |
**决策原因:** 需要自定义 rehype/recaka 插件
## 关键发现
### Next.js 15 Breaking Changes
- `next/image` 现在需要配置 domains
- `getStaticPaths` 改名为 `generateStaticParams`
- `next/link` 不再需要 `<a>` 包裹
### 性能优化点
- 使用 `dynamic` import 减少初始 bundle
- 图片使用 `next/image` 自动优化
- 启用 ISR 增量静态再生
## 遇到的问题
### 问题 1: MDX 代码高亮不工作
**错误:** SyntaxHighlighter 无法解析 TSX
**原因:** rehype-highlight 与 shiki 冲突
**解决:** 移除 rehype-highlight，只使用 shiki
**命令:** `npm uninstall rehype-highlight`
## 待研究事项
- [ ] 评论系统集成 (Giscus vs Utterances)
- [ ] RSS 订阅生成方案
- [ ] 搜索功能实现
Findings 书写原则:
- ✅ 使用表格对比，一目了然
- ✅ 记录失败原因和解决方案
- ✅ 标注决策原因
- ✅ 保留待办事项
实践 3: 进度记录的最佳节奏
什么时候更新 progress.md?
| 触发条件 | 动作 | 示例 |
|---|---|---|
| 完成 Phase 任务 | 打勾并记录 | ✅ 完成首页布局，耗时 45 分钟 |
| 遇到阻塞问题 | 详细记录问题 | ⚠️ ESLint 配置与 Prettier 冲突，需要解决 |
| 产生新想法 | 记录到 findings | 💡 考虑使用 contentlayer 替代 MDX |
| 发现 Bug | 记录复现步骤 | 🐛 暗黑模式切换时页面闪烁 |
| 测试通过 | 记录测试覆盖 | ✅ 单元测试覆盖率达到 80% |
进度记录模板:
### 2024-02-10 14:30 - Session 1
**目标:** 完成项目初始化
**完成事项:**
- ✅ 创建 Next.js 项目 (TypeScript 模板)
- ✅ 配置 Tailwind CSS
- ✅ 设置 Git 仓库
**遇到的问题:**
- ⚠️ TypeScript 严格模式下 props 类型报错
- 解决: 添加 `interface Props` 定义
**时间消耗:** 1.5 小时
**下次继续:** Phase 2 - 核心布局开发
实践 4: 会话恢复的正确姿势
场景：上下文满了，执行 /clear
自动恢复流程:
Claude: 检测到之前的规划会话！
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 会话恢复报告
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
上次活动: 2024-02-10 16:45 (2小时前)
任务进度: ████████░░░░░░░ 40%
✅ 已完成阶段:
• Phase 1: 项目初始化 (4/4)
• Phase 2: 核心布局 (3/3)
🔄 进行中阶段:
• Phase 3: Markdown 支持 (2/4)
✓ MDX 处理器配置
✓ 代码高亮设置
✗ 图片优化 (待处理)
✗ Frontmatter 解析 (待处理)
💡 最近发现:
• next-mdx-enhanced 已停止维护
• 考虑迁移到 @mdx-js/loader
🚧 未解决问题:
• rehype 插件与 Next.js 冲突
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
是否继续 Phase 3 的工作？
恢复后的智能建议:
Claude: 根据进度记录，我建议：
1. 优先处理 rehype 插件冲突
2. 然后完成图片优化
3. 最后实现 frontmatter 解析
要继续吗？还是想先看看 findings.md 了解之前的发现？
实践 5: 多项目并行管理
目录结构:
├── project-a/
│ ├── task_plan.md
│ ├── findings.md
│ └── progress.md
├── project-b/
│ ├── task_plan.md
│ ├── findings.md
│ └── progress.md
└── project-c/
├── task_plan.md
├── findings.md
└── progress.md
切换项目时:
# 项目 A 工作中...
你: 切换到项目 B
Claude: 明白，切换到 project-b。
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📂 Project-B 状态
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
上次活动: 昨天 10:30
任务进度: ████████████████░ 80%
🔄 进行中: Phase 4 - API 集成
要继续吗？先快速看一下 plan 还是 findings？
实践 6: 团队协作模式
共享 findings.md:
# Team Findings
## @Alice - 2024-02-10
发现 Vercel 部署时环境变量问题...
[详细记录]
## @Bob - 2024-02-11
修复了 Alice 的问题，需要添加 `.env.production`...
## @Charlie - 2024-02-12
基于 Alice 和 Bob 的发现，创建了部署脚本...
Git 集成最佳实践:
# .gitignore
task_plan.md.local # 个人任务顺序
progress.md.local # 个人进度
# Git commit 前检查
git diff task_plan.md # 查看计划变更
git diff findings.md # 查看新增发现
实践 7: 性能优化技巧
减少不必要的文件读取:
// Hook 优化示例
if (action === 'write_file' && file.endsWith('.md')) {
// 只在写入 Markdown 时提醒
remindToUpdateFindings();
}
if (action === 'run_command' && command.includes('test')) {
// 测试命令后记录结果
remindToLogTestResults();
}
智能缓存策略:
┌─────────────────────────────────────────────────────────────┐
│ 文件读取策略 │
├─────────────────────────────────────────────────────────────┤
│ │
│ task_plan.md → 每次决策前读取 (PreToolUse Hook) │
│ findings.md → 每 2 次操作后读取 (PostToolUse Counter) │
│ progress.md → 会话结束时读取 (Stop Hook) │
│ │
│ 避免过度读取 → 节省 tokens │
│ 关键时刻读取 → 确保一致性 │
│ │
└─────────────────────────────────────────────────────────────┘
实践 8: 常见陷阱与避坑指南
| 陷阱 | 症状 | 解决方案 |
|---|---|---|
| 过度规划 | 花 1 小时写 plan，代码没写几行 | 10-15 分钟快速规划，边做边调整 |
| 忽视 findings | 重复搜索相同问题 | 每次查资料后立即记录 |
| checkbox 恐惧 | 不敢开始因为任务太多 | 先拆成 3 个大 Phase，细化再说 |
| 完美主义 | findings 写得像博客 | 关键信息优先，格式可以粗糙 |
| 不检查 status | 忘记进度 | 每 30 分钟 /plan:status 一次 |
实战对照表：传统方式 vs 3-File 模式
| 场景 | 传统方式 | 3-File 模式 |
|---|---|---|
| 中途退出 | ❌ 下次从头解释 | ✅ /plan:status 快速恢复 |
| 遇到错误 | ❌ 重复犯相同错误 | ✅ findings.md 记录解决方案 |
| 多步任务 | ❌ AI 忘记原始目标 | ✅ task_plan.md 持续追踪 |
| 研究发现 | ❌ 散落在上下文中 | ✅ findings.md 结构化存储 |
| 进度可视化 | ❌ 无法直观看到 | ✅ checkbox 进度条 |
| 团队交接 | ❌ 口头解释很累 | ✅ 共享 findings 文档 |
使用场景决策树
开始任务
│
▼
┌────────────────┐
│ 任务是否复杂？ │
└────────────────┘
│ │
否 是
│ │
▼ ▼
┌──────────┐ ┌─────────────────┐
│ 直接执行 │ │ 是否 >3 步骤？ │
│ 不用 plan │ └─────────────────┘
└──────────┘ │ │
否 是
│ │
▼ ▼
┌──────────┐ ┌─────────────┐
│ 简单记录 │ │ 启动 /plan │
│ todo list │ │ 3-File 模式 │
└──────────┘ └─────────────┘
示例判断:
• "修复一个 bug" → 直接执行
• "添加一个按钮" → 直接执行
• "重构一个组件" → 简单记录
• "构建完整功能模块" → /plan
• "研究新技术并实现" → /plan
• "多步骤系统集成" → /plan
社区生态与扩展
planning-with-files 已催生多个社区 Fork 项目：
| 项目 | 作者 | 特色功能 |
|---|---|---|
| devis | @st01cs | 面试优先工作流，/devis:intv 和 /devis:impl 命令 |
| multi-manus-planning | @kmichels | 多项目支持，SessionStart git 同步 |
| plan-cascade | @Taoidle | 多级任务编排，并行执行，多代理协作 |
常见问题解答
Q: 和内置 /plan 命令有什么区别？
A: 内置命令进入 plan mode 后退出，本插件持久化到文件，支持会话恢复和进度追踪。
Q: 支持 Windows 吗？
A: 完全支持！v2.2.0 开始提供 PowerShell 脚本。
Q: 会增加很多 token 消耗吗？
A: 不会。Hooks 只在关键时刻（决策前、写文件后、退出时）读取文件，相比传统模式反而更节省 tokens。
Q: 可以自定义模板吗？
A: 可以！修改
~/.claude/plugins/.../templates/下的模板文件即可。
Q: 如何查看当前进度？
A: 使用
/plan:status命令快速查看进度报告。
快速参考卡片
╔═══════════════════════════════════════════════════════════════╗
║ planning-with-files 快速参考 ║
╠═══════════════════════════════════════════════════════════════╣
║ ║
║ 🚀 启动命令 ║
║ /plan 开始新规划 ║
║ /plan:status 查看当前进度 ║
║ ║
║ 📁 三个文件 ║
║ task_plan.md ← 任务分解 + checkbox 进度 ║
║ findings.md ← 研究发现 + 技术决策 ║
║ progress.md ← 会话日志 + 时间记录 ║
║ ║
║ 🔄 Hooks 自动化 ║
║ PreToolUse → 决策前重读 plan ║
║ PostToolUse → 操作后提醒保存 ║
║ Stop → 退出前验证完成度 ║
║ ║
║ ⚡ 关键规则 ║
║ 1. 先创建 Plan，再开始执行 ║
║ 2. 每两次查看操作保存 findings ║
║ 3. 所有错误必须记录原因 ║
║ 4. 失败后改变方法，不要重复 ║
║ ║
║ ✅ 适合场景 ║
║ ✓ 多步骤任务 (3+) ║
║ ✓ 研究性任务 ║
║ ✓ 长周期项目 ║
║ ✓ 多次会话完成 ║
║ ║
║ ❌ 不适合场景 ║
║ ✗ 简单问答 ║
║ ✗ 单文件编辑 ║
║ ✗ 快速查找 ║
║ ║
╚═══════════════════════════════════════════════════════════════╝
总结
planning-with-files 通过 Manus AI 的三文件模式，解决了 AI 编程助手的核心痛点：
- 持久化记忆 - 用文件系统作为 AI 的外部记忆
- 进度可视化 - checkbox 进度条清晰展示任务状态
- 自动恢复 - 上下文重置后无缝接续工作
- 知识沉淀 - findings.md 积累技术决策和经验
- ** Hooks 自动化** - 无需手动干预，智能追踪进度
核心理念：
Context Window = RAM (易失、有限)
Filesystem = Disk (持久、无限)
→ 任何重要信息都写入磁盘
立即开始：
# 一键安装
/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files
# 开始你的第一个规划会话
/plan
相关链接：
- 📦 GitHub: OthmanAdi/planning-with-files
- 📖 文档: 完整文档
- 💬 社区: 提交 Issue 分享使用经验
文章标签： #ClaudeCode #AI编程 #开发工具 #效率提升 #Manus #上下文工程 #开源项目
如果这篇文章对你有帮助，欢迎点赞收藏，也欢迎在评论区分享你的使用经验！
作者简介： 全栈开发者，专注于 AI 辅助编程工具的研究与实践。
版权声明： 本文原创，转载请注明出处。
