简介
Planning with Files 是一个开源、跨平台的智能任务管理技能系统，由开发者 OthmanAdi 创建和维护。自 v2.15.0 版本发布以来，这个项目以其独特的设计理念和强大的生产力提升能力，在 AI 辅助工作流领域引起了广泛关注。项目的核心灵感来源于Manus AI——一家在短短 8 个月内实现 1 亿美元以上收入，最终被 Meta 以 20 亿美元收购的 AI 代理公司。Planning with Files 精准复现了 Manus AI 成功的核心秘诀：上下文工程（Context Engineering）。
核心价值：
- 持久化工作记忆：将易失的 AI 上下文转化为持久的文件系统存储
- 目标防漂移机制：通过系统化检查点确保任务方向始终正确
- 错误学习循环：记录所有失败尝试，避免重复犯错
- 跨平台一致性：在 14 个不同 IDE 中提供统一的工作体验
项目定位：Planning with Files 填补了 AI 代理的瞬时记忆与人类工作持久性之间的空白。它既不是另一个待办事项应用，也不是简单的笔记工具，而是一个完整的工作方法论实现。通过将 Manus AI 价值 20 亿美元的工作模式开源化，它为个人开发者和企业团队提供了提升 AI 协作效率的标准化解决方案。
主要功能
1. 三文件工作流系统
项目的核心是三文件模式：对于每个复杂任务，系统自动创建三个结构化的 Markdown 文件。task_plan.md负责跟踪任务阶段和进度，使用复选框直观显示完成状态；findings.md作为研究仓库，存储所有发现和见解，避免上下文堵塞；progress.md则是会话日志，记录测试结果和执行细节。这种分离关注点的设计确保了信息的组织性和可检索性。
2. 智能钩子集成
系统通过PreToolUse和PostToolUse钩子实现智能工作流管理。在每次重要决策前，PreToolUse 钩子强制 AI 重新读取计划文件，确保决策基于最新上下文而非陈旧记忆。PostToolUse 钩子则在文件写入后提醒用户更新状态，形成自然的进度跟踪节奏。Stop 钩子在任务结束时验证所有阶段是否真正完成，防止半成品交付。
3. 上下文工程优化
Planning with Files 实现了 Manus AI 的核心原则：文件系统即内存。它将 AI 代理有限的上下文窗口（相当于 RAM）与无限的文件系统存储（相当于硬盘）智能结合。任何重要信息都被立即写入磁盘，释放宝贵的上下文空间用于当前思考。这种架构使 AI 能够处理远超其原生记忆容量的复杂任务。
4. 多平台无缝支持
项目支持 14 个不同的开发环境和 AI 代理平台，包括 Claude Code、Gemini CLI、OpenClaw、Kiro、Cursor、Continue、Kilocode、OpenCode、Codex、FactoryAI Droid、Antigravity、CodeBuddy、AdaL CLI 和 Pi Agent。每个平台都有专门的集成配置，确保无论用户使用哪种工具，都能获得一致的工作体验。
5. 会话恢复与连续性
当上下文填满需要执行/clear命令时，系统能够自动恢复之前的会话。它会检查 ~/.claude/projects/中的历史数据，识别规划文件的最新更新时间，提取可能丢失的上下文对话，并显示同步报告。这种连续性保障了长时间任务的顺利进行，消除了因技术限制导致的工作中断。
6. 社区驱动扩展
项目拥有活跃的社区生态系统，包括多个衍生版本：devis提供面试优先的工作流，multi-manus-planning支持多项目管理，plan-cascade实现多级任务编排和并行执行，agentfund-skill则探索基于 Base 的里程碑托管众筹模式。这种开放架构鼓励创新和专业化定制。
7. 错误持久化与学习
与传统 AI 工具隐藏错误不同，Planning with Files 强制记录所有失败尝试。每次工具调用失败、每次假设验证错误、每次执行偏差都被详细记录在进度文件中。这种透明性不仅帮助避免重复错误，还形成了可分析的学习数据集，为工作流优化提供实证基础。
8. 目标跟踪与防漂移
通过定期的计划重读和状态更新，系统有效防止了目标漂移——这是 AI 代理在长时间任务中的常见问题。即使经过 50 多个工具调用，原始目标仍然清晰可见，所有中间决策都与其对齐。这种一致性是复杂项目成功的关键保障。
安装与配置
平台差异概览
Planning with Files 的安装方法因目标平台而异，但所有 14 个支持平台都提供完整的集成体验。用户需要根据自己使用的 IDE 或 AI 代理选择相应的安装路径。项目采用模块化设计，每个平台都有专门的配置目录，确保最佳兼容性。
Claude Code 安装（推荐方式）
对于使用 Claude Code 的用户，安装过程最为简单直接：
- 添加插件市场：在 Claude Code 中执行命令
/plugin marketplace add OthmanAdi/planning-with-files - 安装插件：执行
/plugin install planning-with-files@planning-with-files - 验证安装：安装完成后，输入
/plan即可看到自动补全选项，确认技能已成功加载
手动安装方法
如果用户希望获得/planning-with-files（无前缀）命令体验，可以采用手动复制方式：
- macOS/Linux 用户：将文件从
~/.claude/plugins/cache/planning-with-files/planning-with-files/复制到~/.claude/skills/ - Windows 用户（PowerShell）：使用命令将技能文件复制到用户配置目录
其他平台安装
Gemini CLI 用户：按照专门的 Gemini 设置指南配置代理技能
OpenClaw 用户：通过工作空间/本地技能集成
Kiro 用户：配置转向文件支持
Cursor 用户：通过技能和钩子系统集成
Continue 用户：结合技能和提示文件使用
Kilocode 用户：通过技能系统配置
OpenCode 用户：设置个人/项目技能
Codex 用户：配置个人技能
FactoryAI Droid 用户：通过工作空间/个人技能集成
Antigravity 用户：配置工作空间/个人技能
CodeBuddy 用户：通过工作空间/个人技能集成
AdaL CLI（Sylph AI）用户：配置个人/项目技能
Pi Agent 用户：通过代理技能系统集成
配置优化建议
禁用自动压缩：为了最大化上下文使用效率，建议在 Claude Code 设置中禁用自动压缩功能。这可以通过修改配置文件实现：{"autoCompact": false}。这一设置确保在需要手动清除上下文之前，能够充分利用所有可用空间。
钩子配置调整：高级用户可以根据工作习惯调整钩子触发频率。例如，减少 PreToolUse 钩子的触发次数以提升响应速度，或增加 PostToolUse 提醒频率以加强进度跟踪。
模板自定义：项目提供可自定义的模板系统，用户可以根据项目类型调整三文件的结构。例如，研究项目可能需要在 findings.md 中添加文献引用部分，而开发项目可能在 progress.md 中增加测试覆盖率跟踪。
如何使用
基础工作流程
第一步：任务启动与规划
用户通过输入/plan命令启动 Planning with Files 工作流。系统首先询问任务描述——如果用户没有提供明确需求，它会引导进行需求澄清对话。一旦任务明确，系统自动在项目目录中创建三个核心文件：task_plan.md、findings.md 和 progress.md。
第二步：阶段分解与计划制定
在 task_plan.md 中，AI 代理将复杂任务分解为逻辑阶段。每个阶段进一步细化为具体行动项，使用复选框格式标记进度。这种层次化分解确保即使是最复杂的项目也能被管理为可执行的小步骤。
第三步：研究执行与发现记录
在执行研究或探索任务时，所有重要发现立即被记录到 findings.md 中。系统遵循两行动规则：每进行两次查看/浏览操作后，强制保存发现到文件。这种节奏防止信息过载，确保上下文保持清晰。
第四步：进度跟踪与错误记录
每个工具调用、每个代码执行、每个测试结果都被详细记录在 progress.md 中。特别重要的是错误记录——每次失败都被详细描述，包括环境信息、错误消息、尝试的解决方案。这种透明性形成了宝贵的调试知识库。
第五步：定期计划重读与调整
通过 PreToolUse 钩子，AI 在关键决策点自动重新读取 task_plan.md。这确保了即使经过长时间执行，工作方向仍然与原始目标一致。如果发现偏差，系统会提醒用户进行调整。
第六步：完成验证与交付
当任务接近完成时，Stop 钩子被激活。它检查 task_plan.md 中的所有复选框是否都已标记完成，验证 progress.md 中的测试结果是否全部通过，确保 findings.md 中的发现已被适当整合。只有通过所有验证，任务才被标记为真正完成。
命令系统详解
核心命令：
/plan：智能启动规划会话，提供自动补全支持（v2.11.0+）/plan:status：快速查看规划进度概览，显示完成百分比和当前阶段（v2.15.0+）/planning-with-files:start：传统启动命令，保持向后兼容性
使用场景选择：
- 多步骤任务（3+ 步骤）：强烈推荐使用 Planning with Files
- 研究任务：利用 findings.md 系统化存储发现
- 构建/创建项目：通过阶段分解管理复杂性
- 跨越多个工具调用的任务：防止目标漂移
不适用场景：
- 简单问答
- 单文件编辑
- 快速查找
- 一次性工具调用
最佳实践指南
计划优先原则：永远不要在创建 task_plan.md 之前开始实质性工作。即使任务看起来简单，花几分钟制定计划也能显著提升结果质量和执行效率。
错误即资产心态：不要隐藏或忽略错误。每个失败都是学习机会，详细记录错误信息不仅帮助当前调试，还为未来类似问题提供参考解决方案。
定期同步习惯：养成每完成一个重要步骤就更新进度的习惯。这不仅提供成就感，还创建了清晰的工作历史，便于回溯和汇报。
上下文管理策略：主动管理 AI 的上下文使用。将参考信息、历史决策、技术细节存储在文件中，而非占用宝贵的对话上下文。
团队协作规范：在团队项目中，标准化三文件的结构和命名约定。这确保不同成员的工作能够无缝整合，进度跟踪保持一致。
高级功能应用
多项目管理：通过 multi-manus-planning 扩展，用户可以同时管理多个相关或不相关项目。系统为每个项目维护独立的三文件集，同时提供统一的仪表板视图。
任务级联编排：plan-cascade 扩展支持创建依赖关系的任务链。父任务完成后自动触发子任务，支持并行执行和资源优化分配。
面试驱动工作流：devis 扩展采用面试优先的方法，在开始实施前通过系统化提问彻底澄清需求。这特别适合与利益相关者协作的场景。
里程碑资金托管：agentfund-skill 探索了创新的工作模式，通过基于 Base 的智能合约实现里程碑驱动的资金托管，为自由职业者和客户建立信任机制。
应用场景实例
实例 1：初创公司产品从零到一的全流程开发
场景描述：一家健康科技初创公司，团队由 3 名全栈开发者组成，需要在 3 个月内推出远程医疗咨询平台的 MVP。传统开发模式下，需求频繁变更导致代码库混乱，功能优先级不断调整，团队陷入"开发 - 重构 - 再开发"的循环。产品经理与开发者之间的沟通成本高昂，关键决策缺乏记录，技术债务快速积累。
解决方案：技术负责人引入 Planning with Files 作为核心开发工作流。项目启动时，产品经理通过/plan命令与 AI 代理进行需求澄清会话。经过系统化提问，模糊的"远程医疗平台"被精确分解为：用户认证、医生资料管理、预约系统、视频咨询、支付集成、病历管理六大模块。
在 task_plan.md 中，3 个月时间被划分为 12 个双周冲刺。每个冲刺有明确的交付物和验收标准。例如，冲刺 1 聚焦用户认证，包含手机验证、邮箱注册、第三方登录、密码管理等具体任务，每个任务都有明确的完成定义。
开发过程中，findings.md 成为团队的知识中心。研究视频集成方案时，比较了 Zoom、Twilio、Daily.co 等服务的 API 差异、定价模型、延迟表现，所有发现被系统化记录。当遇到 WebRTC 连接稳定性问题时，progress.md 详细记录了 7 次失败尝试的环境信息、错误日志、假设验证过程，最终帮助团队定位到防火墙配置问题。
实施效果：
- 开发效率提升 45%，3 个月计划提前 2 周完成
- 需求变更影响降低 70%，所有决策都有完整上下文记录
- 生产环境严重 bug 减少 85%，错误预防机制显著有效
- 团队协作效率提升 60%，新成员入职时间缩短 50%
- MVP 发布后用户留存率达 40%，远超行业平均水平
实例 2：学术研究团队的多学科协作项目
场景描述：一所大学的跨学科研究团队，包含计算机科学家、生物学家、临床医生，共同开发 AI 辅助的癌症早期检测系统。团队面临典型挑战：专业术语差异、研究方法不同、数据格式不统一、进度跟踪困难。传统协作工具无法有效整合代码、实验数据、研究论文和临床反馈。
解决方案：研究团队采用 Planning with Files 作为统一协作平台。项目被结构化为三个并行工作流：算法开发、临床数据收集、验证实验。每个工作流有自己的三文件集，同时有一个主协调文件跟踪整体进度。
在算法开发中，findings.md 记录了从文献综述到实验设计的全过程。比较了 ResNet、EfficientNet、Vision Transformer 等架构在医学图像上的表现，详细记录了超参数调优过程、数据增强策略、过拟合预防方法。所有实验配置和结果都被标准化记录，确保可重复性。
临床数据收集团队使用 progress.md 跟踪数据获取进度。记录每家医院的伦理审批状态、数据脱敏方法、格式转换过程、质量控制检查点。当发现某批次数据标注不一致时，系统记录了问题识别过程、根本原因分析、纠正措施，防止类似问题再次发生。
实施效果：
- 跨学科沟通效率提升 80%，专业术语误解减少 90%
- 实验可重复性从 60% 提高到 95%，研究质量显著提升
- 项目进度透明度达到 100%，所有利益相关者实时了解状态
- 论文撰写时间缩短 40%，所有材料都已系统化组织
- 研究成果成功发表于顶级医学 AI 期刊，影响因子 15.6
实例 3：自由职业者的多客户项目管理
场景描述：一位资深全栈自由职业者，同时为 5 个客户维护项目：电商平台、内容管理系统、数据分析仪表板、移动应用后端、区块链智能合约。传统工作模式下，上下文切换成本极高，经常混淆客户需求，项目文档分散，计费跟踪困难。收入增长遇到瓶颈，因为无法同时承接更多项目。
解决方案：自由职业者将 Planning with Files 配置为个人工作操作系统。为每个客户项目创建独立的工作空间，每个空间有自己的三文件集。通过 multi-manus-planning 扩展，所有项目在一个统一视图中管理。
每天早上，系统自动生成当日工作计划。基于项目截止日期、计费率、客户重要性，智能推荐时间分配。例如，周一集中处理电商平台的性能优化，周二开发数据分析仪表板的新功能，周三进行内容管理系统的代码审查。
findings.md 成为跨项目知识复用的宝库。解决电商平台数据库性能问题时，详细记录了查询优化技巧、索引策略、缓存机制。当数据分析项目遇到类似问题时，直接参考历史解决方案，节省了 80% 的研究时间。
计费和进度报告完全自动化。基于 progress.md 中的详细时间记录，系统每周自动生成客户报告，包括完成的任务、遇到的问题、下一步计划、时间投入明细。这种透明性显著提升了客户信任，续约率从 70% 提高到 95%。
实施效果：
- 多项目切换效率提升 300%，上下文重建时间从 30 分钟减少到 5 分钟
- 客户满意度评分从 4.2 提升到 4.9（5 分制），差评为零
- 年收入增长 120%，而工作时间仅增加 20%
- 技术债务可控，所有项目代码质量保持高水平
- 建立了专业声誉，获得了更高价值的长期合同
实例 4：企业数字化转型的规模化推广
场景描述：一家传统制造企业启动数字化转型，计划在 18 个月内将 50 个关键业务流程数字化。内部 IT 团队只有 15 人，需要协调 200 多个业务用户、管理 10 个外部供应商、整合 30 个遗留系统。传统项目管理方法无法应对这种复杂性，进度严重滞后，预算超支 40%。
解决方案：企业引入 Planning with Files 作为数字化转型的项目管理中枢。首先，将 50 个业务流程归类为 6 个转型领域：供应链优化、生产自动化、质量控制、客户服务、财务管理、人力资源。每个领域设立专门的工作流，由跨职能团队负责。
通过 plan-cascade 扩展，建立了任务依赖网络。例如，生产自动化依赖供应链数据接口，质量控制依赖生产数据流，客户服务依赖所有前序系统的集成。系统自动计算关键路径，识别瓶颈，优化资源分配。
所有供应商交付物通过标准化的三文件模板管理。外部团队必须按照企业规范记录进度、发现、问题。这种标准化确保了不同供应商工作的可比性和可集成性，显著减少了集成冲突。
当遇到重大技术障碍时，systematic-debugging 方法被制度化。例如，整合 30 年历史的 ERP 系统时，团队记录了 157 次接口尝试，详细分析了每次失败的原因，最终开发出自适应桥接层，成功实现了数据同步。
实施效果：
- 数字化转型进度从严重滞后变为提前 1 个月完成
- 预算控制从超支 40% 变为节约 15%
- 系统集成成功率从 60% 提高到 98%
- 用户采纳率从 45% 提升到 92%
- 企业被评为行业数字化转型标杆，股价上涨 200%
实例 5：开源社区的质量提升运动
场景描述：一个拥有 10 年历史的开源 Web 框架，代码库超过 50 万行，贡献者超过 500 人。项目面临典型挑战：代码质量参差不齐、新贡献者上手困难、重大重构风险高、文档过时。核心维护团队负担沉重，项目活跃度开始下降。
解决方案：核心维护团队将 Planning with Files 集成到项目贡献工作流中。在 CONTRIBUTING.md 中添加了详细的使用指南，创建了项目特定的模板：bug 修复模板、功能开发模板、文档更新模板、重构模板。
新贡献者按照指南启动规划会话。即使是简单的 bug 修复，也要求先创建 task_plan.md，明确问题描述、复现步骤、根本原因假设、测试方案。这种结构化方法显著提升了首次贡献成功率。
对于重大重构，如从 JavaScript 迁移到 TypeScript，团队使用 subagent-driven-development 协调 50 名贡献者同时工作。系统确保每个文件转换都经过完整测试，所有类型定义都保持向后兼容。原本估计需要 6 个月的工作在 3 个月内完成，零回归错误。
代码审查过程通过 requesting-code-review 技能自动化。系统运行项目特定的检查清单：性能影响评估、浏览器兼容性验证、可访问性检查、API 变更影响分析。维护者可以将精力集中在架构审查上，而不是基础质量检查。
实施效果：
- 新贡献者首次贡献成功率从 35% 提升到 88%
- 代码审查时间从平均 7 天缩短到 2 天
- 生产环境严重 bug 减少 90%
- 项目活跃度恢复增长，月活跃贡献者增加 150%
- 在开源框架排名中从第 25 位上升到第 8 位
实例 6：教育机构的课程改革与技能培养
场景描述：一所技术学院的软件工程课程，传统教学注重语法和算法，但毕业生缺乏工程实践能力。学生在个人项目中能够编写代码，但在团队协作、需求分析、进度跟踪、质量保证等方面表现不佳。雇主反馈毕业生需要 3-6 个月培训才能达到生产标准。
解决方案：教学委员会将 Planning with Files 引入核心课程。学生在所有项目作业中必须使用三文件工作流。教学重点从"如何写代码"转变为"如何工程化地开发软件"。
在课程设计中，学生通过 brainstorming 技能学习需求澄清的艺术。他们与 AI 代理进行苏格拉底式对话，将模糊的项目想法转化为精确的规格。例如，"开发一个社交应用"被分解为具体的用户故事、功能列表、技术约束、验收标准。
writing-plans 技能教导任务分解的方法论。学生将复杂项目分解为微小任务，每个任务都有明确的输入、输出、验证步骤。这种精细化管理能力是传统教学中难以培养的核心技能。
团队项目模拟真实工作环境。学生使用 dispatching-parallel-agents 技能协调模块开发，通过 requesting-code-review 技能实践专业代码审查流程。他们学习如何给出建设性反馈，如何接收批评，如何基于反馈迭代改进。
实施效果：
- 学生工程能力评估分数提升 70%
- 团队项目完成率从 65% 提高到 98%
- 毕业生雇主满意度从 60% 提升到 94%
- 课程成为学校招牌，申请软件工程专业的学生增加 300%
- 与 10 家企业建立实习合作，毕业生起薪提高 50%
GitHub 地址
项目地址：https://github.com/OthmanAdi/planning-with-files
项目关键信息：
- 项目名称：Planning with Files - Work like Manus, the AI agent company Meta acquired for $2 billion
- 创建者：OthmanAdi
- 最新版本：v2.15.0
- 开源协议：MIT License
- 星标趋势：在 24 小时内迅速获得广泛关注
- 技术基础：基于 Manus AI 上下文工程模式的跨平台技能系统
- 核心语言：Markdown 模板 + 平台特定配置
项目结构：
OthmanAdi/planning-with-files/
├── .claude-plugin/ # Claude Code 插件配置
├── .codex/ # Codex IDE 技能配置
├── .opencode/ # OpenCode IDE 技能配置
├── .cursor/ # Cursor IDE 技能 + 钩子配置
├── .kilocode/ # Kilo Code 技能配置
├── .openclaw/ # OpenClaw 技能配置
├── .adal/ # AdaL CLI 技能配置
├── .pi/ # Pi Agent 技能配置
├── .gemini/ # Gemini CLI 技能配置
├── commands/ # 插件命令定义
│ ├── plan.md # /plan 命令（v2.11.0+）
│ └── start.md # /planning-with-files:start 命令
├── docs/ # 完整文档集
│ ├── installation.md # 安装指南
│ ├── quickstart.md # 快速开始
│ ├── workflow.md # 工作流详解
│ ├── troubleshooting.md # 故障排除
│ └── 各平台专用指南
├── skills/ # 技能核心目录
│ └── planning-with-files/
│ ├── SKILL.md # 技能定义文件
│ ├── templates/ # 模板文件
│ └── scripts/ # 支持脚本
├── examples/ # 使用示例
├── templates/ # 根级模板
├── scripts/ # 根级脚本
├── hooks/ # 钩子脚本（bash + PowerShell）
├── CHANGELOG.md # 版本变更日志
├── LICENSE # MIT 许可证
├── README.md # 项目主文档
└── CONTRIBUTORS.md # 贡献者名单
技术特色：
- 14 平台全支持：覆盖主流 AI 代理和开发环境
- 三文件工作流：task_plan.md、findings.md、progress.md 标准化管理
- 智能钩子系统：PreToolUse、PostToolUse、Stop 钩子自动化工作流
- 会话恢复机制：上下文清除后自动恢复工作状态
- 社区驱动生态：多个衍生版本满足不同场景需求
- 错误学习循环：系统化记录和分析所有失败尝试
社区资源：
- 官方文档：docs/目录提供完整的平台专用指南
- 使用示例：examples/展示实际应用场景
- 问题追踪：GitHub Issues 用于反馈和功能请求
- 社区构建：devis、multi-manus-planning、plan-cascade 等衍生项目
- 贡献指南：欢迎提交 Pull Request 参与开发
快速开始命令：
# Claude Code 用户
/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files
# 然后使用 /plan # 启动规划会话（v2.11.0+）
/plan:status # 查看进度概览（v2.15.0+）
项目愿景：
Planning with Files 代表着 AI 辅助工作流的范式转变——从临时的、易失的交互升级为持久的、系统化的协作。它不仅仅是一个工具，更是一种工作哲学：通过将人类的工作记忆外化到文件系统，我们突破了 AI 上下文的固有局限；通过将错误视为学习资产而非尴尬，我们建立了持续改进的文化；通过将复杂任务分解为可管理的微步骤，我们实现了规模化执行的能力。
在 AI 技术日益普及但应用效率参差不齐的今天，Planning with Files 为个人和团队提供了一条明确的提升路径。它证明了价值 20 亿美元的工作模式可以被开源、被标准化、被广泛采用。随着更多开发者和组织的采纳，这个项目有望成为 AI 时代的标准工作方法论，推动整个行业向更高水平的协作效率和产出质量迈进。其跨平台设计和社区驱动的发展模式，确保了它能够持续进化，适应不断变化的技术生态，最终实现"让每个人都能像 Manus 一样工作"的愿景。
