1. 项目概述为什么“文件即规划”是AI编程的范式革命如果你和我一样长期在Claude Code、Cursor这类AI编程助手上工作一定经历过这样的挫败感一个复杂的重构任务进行到一半因为上下文窗口满了不得不/clear清空对话结果AI助手瞬间“失忆”刚刚讨论好的架构设计、已经排查出的几个关键依赖全都烟消云散。你不得不从头开始解释或者更糟——AI开始沿着一个略有偏差的方向继续之前的经验教训完全白费。这就是传统AI编程工作流的根本缺陷它把一切都塞进那个有限的、易失的上下文窗口里就像试图用RAM来运行整个操作系统。2025年底Meta以20亿美元收购Manus AI这家公司在8个月内从零做到超1亿美元营收其核心秘诀被概括为“上下文工程”。而“Planning with Files”这个开源项目正是将Manus这套价值20亿美元的工作流模式封装成了一个可以即插即用的Claude Code技能Skill。简单来说它强制你和AI助手养成一个习惯任何重要的思考、规划、发现和进展都必须立即写入到磁盘的Markdown文件中而不是停留在对话的上下文里。这听起来简单但实践起来它彻底改变了AI辅助编程的协作模式。从“AI作为一次性的问答机”变成了“AI作为与你共享持久化工作记忆的结对编程伙伴”。1.1 核心痛点我们到底在对抗什么在没有这套模式之前我们的工作流存在几个结构性弱点1. 易失性记忆Volatile MemoryClaude Code的TodoWrite工具很好用能帮你列出步骤。但问题是这个“待办列表”只存在于当前对话的上下文中。一旦你执行了/clear或者对话轮数过多导致早期信息被“挤出”上下文这个列表就消失了。你失去了项目的“路线图”。2. 目标漂移Goal Drift一个中等复杂的任务比如“为现有REST API添加GraphQL层并确保向后兼容”可能需要AI执行超过50次工具调用查看文件、运行测试、修改代码。在这个过程中最初的、最核心的目标例如“必须保证现有所有API调用不受影响”很容易在一次次具体的代码修改中被AI遗忘或淡化。没有持久化的记录来反复锚定目标。3. 错误黑洞Hidden ErrorsAI在尝试一个方案时失败了比如某个依赖安装不了或某个API调用方式不对这个失败经验如果没有被记录那么下次遇到类似情况时AI很可能会重蹈覆辙因为它不记得“上次在这里踩过坑”。人类的程序员会从错误中学习但失忆的AI不会。4. 上下文垃圾场Context Stuffing为了不让AI忘记我们倾向于把越来越多的信息塞进提示词或早期的对话中项目背景、架构图、注意事项、API密钥格式……最终上下文窗口被这些“背景板”占满留给当前实际思考和操作的空间所剩无几。“Planning with Files”提供的正是一套对抗这些弱点的系统性方法。它不是某个炫酷的功能而是一种工作纪律的工程化实现。1.2 解决方案的精髓三文件模式项目的核心方法论极其简洁就是为每个复杂任务创建三个Markdown文件task_plan.md作战地图。这里定义任务的宏观阶段、具体步骤和验收标准。每一步都是可勾选的复选框- [ ]。它的核心作用是对抗目标漂移。AI在每个关键决策点前都会被钩子Hook脚本强制重新读取这个文件确保自己的行动始终对齐最终目标。findings.md侦察笔记。所有调研结果、探索性代码的输出、尝试过的命令及其结果、查阅的文档摘要都记录在这里。它的核心作用是对抗上下文垃圾场。所有“可能需要以后参考”的信息从上下文移入这个文件释放宝贵的上下文窗口给当前的逻辑推理。progress.md工程日志。按时间顺序记录每个会话Session中实际执行的操作、生成的代码、测试结果和遇到的错误。它的核心作用是对抗错误黑洞和记忆易失。即使你清空了对话或第二天打开项目通过这份日志也能立刻知道“昨天做到哪一步了哪里出了问题”。这个模式将AI的“脑”上下文/RAM和“笔记本”文件系统/磁盘清晰分离。上下文只用于处理当前的、高密度的思考文件系统用于存储所有需要持久化的知识、计划和历史。这正是Manus价值20亿美元洞察的平民化实现。2. 深度解析钩子Hooks如何实现“纪律”自动化“Planning with Files”的强大不仅仅在于它建议你创建三个文件。更在于它通过一套钩子Hooks系统将这种工作纪律变成了几乎自动化的流程无缝集成到各大主流AI IDE中。这是项目工程化的精髓所在。钩子简单理解就是AI助手在特定生命周期节点如“使用工具前”、“使用工具后”、“会话开始”、“会话结束”会自动触发的脚本。这个项目为支持的IDE预置了这些钩子配置。2.1 核心钩子工作流剖析让我们看看一次典型的任务执行中钩子是如何介入并重塑工作流的第1步会话开始SessionStart Hook当你输入/plan启动任务时钩子脚本init-session.sh或Windows下的.ps1被触发。它会做几件事检查当前目录下是否已存在task_plan.md。如果不存在它会引导AI助手也就是Claude向你提问共同创建这个规划文件。这强制了“规划先行”的纪律。如果存在它会读取文件并将最新状态注入到AI的初始上下文中实现会话恢复。即使你刚执行过/clearAI也能立刻知道之前的进度。第2步工具使用前PreToolUse / BeforeTool Hook这是对抗目标漂移的关键防线。每当AI准备执行一个可能改变项目状态的重要操作如写入文件、运行命令前这个钩子会被触发。钩子脚本会强制AI重新读取task_plan.md文件。AI需要基于最新的计划判断即将执行的操作是否仍然符合当前阶段的目标。这相当于在每次行动前都让AI“复习一遍任务书”。在我实际使用中这个机制无数次地阻止了AI跑偏。例如当AI正准备优化一个与当前阶段无关的模块时重读计划会让它意识到“哦我还在‘阶段一搭建基础框架’优化是‘阶段三性能调优’的事情现在做这个为时过早。”第3步工具使用后PostToolUse / AfterTool Hook这是对抗上下文垃圾场和错误黑洞的关键。在AI执行完一个工具操作尤其是browser查看网页或view查看长文件后钩子被触发。它会提醒AI“你刚刚获得了新的信息是否应该将其总结并保存到findings.md中”这就是**“2-Action规则”**的自动化体现——每两次浏览/查看操作后必须保存发现。如果操作中遇到了错误比如命令执行失败钩子会强烈建议AI将完整的错误信息和排查思路记录到progress.md中。这确保了失败经验被固化。第4步会话结束前Stop / SessionEnd Hook这是完成度验证的守门员。当你或AI试图结束会话时钩子脚本check-complete.sh会被触发。它会扫描task_plan.md中所有的复选框- [ ]。如果还有未勾选的项目钩子会向AI发出警告“任务尚未完成还有X个步骤待进行。你是确定要结束还是继续”这个机制有效防止了因中途打断而导致的“烂尾”任务。2.2 多平台支持的实现智慧项目支持超过16种IDE和AI代理平台从Claude Code、Cursor到GitHub Copilot、Codex、Gemini CLI等。它实现跨平台兼容性的方式非常巧妙遵循开放规范对于支持Agent Skills开放规范的平台如Continue, Pi Agent, OpenClaw等它直接提供符合规范的SKILL.md文件通过npx skills add命令即可安装安装器会自动将技能文件放置到各IDE约定的发现路径如~/.continue/skills/。适配私有钩子系统对于有自己钩子实现的大平台如Cursor的hooks.json、GitHub Copilot的Hooks配置、Codex的Skills系统项目为每个平台单独提供了配置文件位于项目根目录对应的隐藏文件夹如.cursor/,.github/。这些配置文件精确映射了平台特定的钩子事件名和脚本路径。运行时环境检测脚本如init-session.sh内部会检测操作系统Windows通过%OS%或PowerShell的$IsWindowsUnix-like系统通过#!/bin/bash和当前工作目录从而调用正确的路径和命令确保在Windows PowerShell和Unix Bash下都能正常工作。这种架构使得项目的核心逻辑三个文件的工作流保持统一而集成层则针对不同平台做适配最大化了可用性。3. 从安装到实战手把手构建你的第一个“文件规划”项目理论说得再多不如亲手实践。下面我将以最常用的Claude Code为例带你完整走一遍安装、配置和执行一个真实任务的流程。我会穿插大量我自己踩过的坑和总结的技巧。3.1 安装与配置一步到位与高级玩法基础安装推荐绝大多数用户打开你的Claude Code终端执行npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g这个命令会通过npx调用skills命令行工具。从GitHub仓库OthmanAdi/planning-with-files添加名为planning-with-files的技能。-g参数表示全局安装技能会被安装到Claude Code的全局技能目录通常是~/.claude/skills/。安装完成后在Claude Code的聊天框中输入/plan你应该能看到planning-with-files:plan这个命令出现在自动补全列表中。这就成功了。踩坑提示1如果安装后没有出现命令可能是Claude Code的技能缓存没有刷新。尝试完全退出Claude Code再重新打开或者执行/skills reload命令如果Claude Code支持。更彻底的方法是直接去~/.claude/skills/目录下查看是否出现了planning-with-files文件夹。高级安装使用插件模式获取完整功能如果你想要更紧密的集成比如使用更短的命令别名可以使用Claude Code的插件系统安装/plugin marketplace add OthmanAdi/planning-with-files /plugin install planning-with-filesplanning-with-files插件安装方式会将技能作为插件的一部分管理并且有时能获得更深度的UI集成取决于Claude Code的插件API。安装后你可以直接使用/planning-with-files:plan命令。手动安装用于调试或自定义有时你可能想修改技能文件或者安装到特定项目。你可以手动克隆仓库并复制文件# 克隆仓库 git clone https://github.com/OthmanAdi/planning-with-files.git # 进入仓库目录 cd planning-with-files # 将技能文件夹复制到Claude Code的全局技能目录macOS/Linux cp -r skills/planning-with-files ~/.claude/skills/ # Windows (PowerShell) # Copy-Item -Recurse -Path skills\planning-with-files -Destination $env:USERPROFILE\.claude\skills\手动安装的好处是你可以直接查看和修改SKILL.md、钩子脚本等文件进行自定义。3.2 实战演练为一个Express.js API添加用户认证假设我们有一个简单的Express.js项目现在需要为其添加JWTJSON Web Token用户认证功能。这是一个典型的多步骤任务非常适合用“Planning with Files”来管理。第1步启动规划在项目根目录打开Claude Code输入命令/planAIClaude会响应并因为触发了SessionStart钩子它开始引导你创建计划。它可能会问“请描述你想要完成的任务。”你回答“为当前这个Express.js API添加基于JWT的用户认证功能。需要包含用户注册、登录、签发Token、保护路由的中间件。数据库使用现有的MongoDB。要求代码结构清晰有基本的错误处理。”紧接着AI会开始创建task_plan.md文件。这里有一个关键技巧不要完全让AI自由发挥。你应该主动介入规划的制定。当AI生成第一个版本的计划草案后仔细阅读并提出修改意见。例如初始AI草案可能的问题步骤过于笼统“实现用户模型”。缺少关键验证“如何测试保护后的路由”顺序可能不合理先实现“登录逻辑”再“生成Token”实际上Token生成是登录逻辑的一部分。你应该这样引导AI修改计划“这个计划不错但我们需要更具体。请将阶段一‘项目初始化’细分为1. 安装必要的npm包jsonwebtoken, bcryptjs。2. 创建用户模型User schema包含email唯一、hashedPassword字段。3. 创建认证相关的工具函数文件authUtils.js用于密码哈希和验证。另外在阶段三‘测试与验证’中增加一个子步骤使用Postman或curl编写并执行测试用例验证注册、登录、受保护路由访问的全流程。”通过这样具体的引导你们共同产出的task_plan.md才会是一份真正可执行、无歧义的“合同”。这份文件将成为后续所有工作的唯一准绳。第2步执行与动态更新规划完成后AI开始工作。你会观察到钩子在默默起作用AI准备安装jsonwebtoken包前会停顿一下PreToolUse钩子触发重读计划确认这是在“阶段一”该做的事。AI查看完Mongoose的文档后准备写用户模型代码时会主动提示你PostToolUse钩子触发“我刚查阅了Mongoose模式定义的文档要点已保存至findings.md。现在开始编写User模型代码。”在progress.md中AI会记录“尝试使用bcrypt.hash同步方法失败该库推荐异步bcrypt.hash。已调整代码。”这个错误记录至关重要下次如果其他部分需要哈希密码AI或你本人就不会再犯同样的错误。在这个过程中你的角色是“监督者”和“需求澄清者”。当AI对某个业务逻辑不确定时比如“登录成功返回的Token应该放在HTTP响应头还是Body里”它应该去更新findings.md记录下不同的方案和权衡然后向你提问由你做出决策。决策后这个结论也应记录在案。第3步验收与迭代当AI勾选了task_plan.md中“实现登录路由”的复选框后它可能会尝试运行服务器并进行一个简单的curl测试。测试结果成功或失败会记录在progress.md。假设测试失败返回“500内部错误”。AI会去查看日志发现是数据库连接字符串错误。它会在progress.md中详细记录错误信息、排查过程和根本原因。修正错误。回到task_plan.md在“阶段三测试与验证”部分增加一个子任务“- [ ] 确保环境变量MONGODB_URI在测试环境中正确加载。”然后继续执行这个新添加的子任务。这就是“文件即规划”模式的动态性和强大之处计划不是一成不变的圣旨而是一个随着项目推进不断演化的活文档。所有的新发现、新决策、新产生的子任务都实时反映在三个文件中构成项目的完整记忆。3.3 跨会话与恢复永不丢失的上下文最精彩的时刻出现在你需要/clear的时候。假设上述任务进行到一半上下文窗口满了。在传统模式下你会陷入绝望。但现在你只需淡定地输入/clear。清空后开启一个新对话。你甚至不需要主动提及之前的任务。因为SessionStart钩子会自动运行。它会检测到项目目录下存在task_plan.md、findings.md和progress.md文件。AI在初始化时会说“检测到存在进行中的任务规划。正在加载上次会话状态...” 然后它会将task_plan.md的最新进度和progress.md的最后几条记录作为系统提示加载进来。AI瞬间“恢复记忆”它知道我们正在做一个Express.js JWT认证项目。目前处于“阶段二实现核心路由”的中期。刚刚完成了用户注册路由但登录路由的测试失败了原因是环境变量问题。下一步应该是解决环境变量问题然后继续测试登录路由。你可以直接命令“继续我们之前的工作。” AI就能无缝衔接。这种体验上的提升是颠覆性的。它意味着你可以将复杂的、耗时的任务拆分成多个工作会话而不必担心状态丢失。项目进度被固化在文件里而非脆弱的对话记忆中。4. 高级技巧与疑难排查经过大量项目的实战我总结出了一套让“Planning with Files”发挥最大效能的技巧以及常见问题的解决方法。4.1 高效使用技巧1. 规划文件的颗粒度艺术task_plan.md中的任务颗粒度是关键。太粗如“完成后端开发”则无法跟踪太细如“在app.js第23行添加require(‘dotenv’)”则会让计划冗长不堪维护成本高。黄金法则一个任务项应该是AI在一个连贯的上下文窗口内不进行/clear可以独立完成并验证的工作单元。例如“实现POST /api/auth/login路由包括请求体验证、密码核对、JWT生成和返回”这就是一个很好的任务项。使用嵌套列表用- [ ]表示主任务用缩进的-或*表示子步骤或说明。这能保持主计划简洁同时细节可查。2. Findings.md 的组织策略findings.md很容易变成杂乱无章的垃圾场。我建议采用时间线主题标签的方式组织。每个发现条目都以## [YYYY-MM-DD HH:MM]开头记录时间。在内容中用关键词的方式标记主题例如#技术选型 #JWT库对比。定期比如完成一个大阶段后对findings.md进行一次“归档整理”将相关条目合并提炼出最终决策和原因放入一个名为决策记录.md的文件。这样findings.md始终保持为“正在进行的研究笔记”而凝固的知识则被归档。3. 与版本控制系统Git的协同这三个文件本身就是极佳的提交信息Commit Message素材。在完成task_plan.md中的一个主要阶段比如所有复选框都打勾后将相关的代码变更连同更新后的三个Markdown文件一起提交。提交信息可以直接引用task_plan.md中的阶段标题和progress.md中的关键摘要。例如git commit -m “feat(auth): 完成用户注册与登录路由 (阶段一) - 详见progress.md 2024-01-01”重要可以将SessionStart钩子脚本稍作修改在会话恢复时自动执行git diff让AI快速了解自上次会话以来代码库发生了什么变化这能极大提升恢复后的上下文准确性。4. 应对复杂项目多规划文件对于非常庞大的项目比如重构一个单体应用为微服务单个task_plan.md可能仍然会变得臃肿。此时可以采用分层规划在项目根目录保留一个master_plan.md只描述最高层的阶段和子模块。为每个子模块如/service-auth,/service-user创建自己的子目录并在其中运行独立的/plan会话生成各自的task_plan.md,findings.md,progress.md。这样每个子任务都有自己独立的、专注的“记忆空间”互不干扰。主规划只跟踪子模块的完成状态。4.2 常见问题与解决方案下面是一个我遇到过的典型问题速查表问题现象可能原因解决方案输入/plan后无反应或提示“命令未找到”。1. 技能未正确安装。2. Claude Code技能缓存未更新。3. 在错误的目录如非项目根目录执行。1. 检查~/.claude/skills/下是否存在planning-with-files文件夹及其SKILL.md文件。2. 重启Claude Code或尝试在聊天框输入/skills reload如果支持。3. 确保在项目根目录下操作。钩子脚本没有执行AI不主动重读计划或提醒保存发现。1. 使用的IDE不支持或未正确配置钩子。2. 钩子脚本没有执行权限Unix系统。3. 技能是以“基础技能”模式安装而非“插件钩子”模式。1. 确认你的IDE在项目的“增强支持”列表中如Claude Code, Cursor。对于仅支持标准技能的平台钩子功能可能受限。2. 在终端执行chmod x ~/.claude/skills/planning-with-files/scripts/*.sh如果使用手动安装。3. 对于Claude Code尝试用插件模式(/plugin install)重新安装以获得完整的钩子功能。会话恢复Session Recovery失败/clear后AI不记得之前的事。1. AI的会话存储路径可能非默认。2.progress.md文件格式异常导致钩子脚本解析失败。3. 项目路径中包含特殊字符或空格导致脚本路径错误。1. 检查钩子脚本如init-session.sh中关于会话存储路径的查找逻辑看是否与你的Claude Code实际路径匹配。可能需要手动调整脚本。2. 检查progress.md文件确保其是有效的Markdown格式时间戳等解析锚点清晰。3. 尽量避免在项目路径中使用空格和中文。如果必须使用可能需要修改钩子脚本对路径进行引号包裹处理。AI在PreToolUse钩子后变得“迟钝”每次操作前都要停顿很久。钩子脚本尤其是重读task_plan.md可能涉及复杂的文件I/O或网络操作在较慢的机器上会造成感知延迟。1. 这是一个权衡。短暂的停顿1-3秒对于确保方向正确是值得的。2. 如果延迟无法忍受可以考虑修改钩子脚本让其只在检测到“重要工具”如write_file,run_command时触发而不是每次工具调用都触发。但这会降低“纪律”的严格性。在Windows PowerShell下脚本执行报错。项目提供的.ps1脚本可能与环境不兼容或者执行策略限制。1. 以管理员身份打开PowerShell执行Set-ExecutionPolicy RemoteSigned以允许本地脚本运行。2. 仔细检查.ps1脚本中的路径分隔符应使用\或[System.IO.Path]::Combine、环境变量引用方式$env:USERPROFILE。可能需要根据你的具体环境进行微调。4.3 性能调优与自定义对于追求极致效率的用户可以对项目进行深度自定义1. 调整钩子触发频率编辑对应IDE的钩子配置文件如Cursor的.cursor/hooks.json。你可以精确控制哪些“工具类型”会触发PreToolUse和PostToolUse。例如只对write_file,run_command,browser这类“高影响力”工具启用钩子而对view,search等只读工具禁用可以减少干扰。2. 扩展文件模板默认的三个文件模板可能不符合你的团队规范。你可以在技能目录的templates/子文件夹下找到初始模板。你可以修改它们加入你们公司特定的文档头、代码规范链接、检查清单等。这样每次/plan创建的文件都符合你的内部标准。3. 集成外部工具在钩子脚本中你可以加入调用外部工具的逻辑。例如在PostToolUse钩子中如果AI写入了代码文件自动触发一个简单的代码风格检查如prettier --check。在Stop钩子中不仅检查任务完成度还可以自动运行项目的测试套件并将结果摘要追加到progress.md中。在SessionStart钩子中自动从Jira或Linear拉取当前任务单的描述并预填充到task_plan.md的初始草稿中。这些自定义将“Planning with Files”从一个通用技能转变为你个人或团队专属的、高度自动化的AI辅助开发流水线。5. 生态、演进与未来展望“Planning with Files”不仅仅是一个工具它正在成为一个围绕“AI上下文工程”的微型生态系统的核心。观察它的GitHub仓库你能看到这种生命力的迸发。社区衍生项目在项目的README中有一个“社区构建了什么”的板块列出了几个非常有启发性的分支devis: 引入了“面试优先”的工作流AI会先像面试官一样问你一系列问题来澄清需求/devis:intv然后再进入执行模式/devis:impl。这解决了AI在需求模糊时容易跑偏的问题。multi-manus-planning: 支持多项目管理。这对于同时处理多个小需求或Bug修复的开发者来说非常实用可以为每个项目或分支维护独立的规划文件集。plan-cascade: 实现了多级任务编排和并行执行。想象一下AI可以将一个大任务分解后同时进行代码编写、文档撰写和测试用例生成如果平台支持多代理协作。agentfund-skill: 一个脑洞大开的想法将规划与基于里程碑的链上托管支付结合。为AI代理的工作设定里程碑客户将资金托管AI完成一个阶段自动触发支付。这为AI驱动的自由职业或外包提供了可信的执行框架。这些衍生项目表明“文件即规划”这个核心模式具有很强的可扩展性。它定义了一个清晰的接口三个Markdown文件上层可以构建各种复杂的工作流和业务逻辑。多语言与多平台支持从v2.25.0开始项目陆续加入了简体中文、繁体中文、阿拉伯语、德语、西班牙语等技能变体。这不仅仅是简单的翻译而是根据不同语言社区开发者的习惯调整了提示词Prompt的语气和文件模板的结构。这种国际化努力降低了非英语母语开发者的使用门槛。同时其对超过16个平台的支持使其几乎成为了AI辅助编程领域的“事实标准”工作流。无论你偏好哪个AI编程工具这套方法论都能适用。对我个人工作流的根本性改变在使用“Planning with Files”几个月后我发现自己对AI编程的依赖模式发生了根本转变从“问答”到“协作”我不再是把AI当作一个更聪明的搜索引擎问完即走。而是将其视为一个拥有持久化工作记忆的初级程序员伙伴。我会向它同步项目背景通过文件它会向我汇报进度和阻塞通过文件。规划能力的内化即使在不使用AI的时候我也开始习惯为复杂任务先写一个task_plan.md。这种结构化的思考方式本身就能极大提升效率。知识资产的沉淀每个项目留下的findings.md和progress.md成为了我个人的技术知识库。下次遇到类似问题我首先翻看的是自己过去的“侦察笔记”和“工程日志”而不是去谷歌搜索。这些文件记录的是我最贴切上下文的一手经验。未来的想象这个项目的方向也暗示了AI编程工具未来的演进路径规划即代码Plan as Codetask_plan.md可能进化成一种更结构化的领域特定语言DSL可以被AI和构建工具共同解析和执行实现真正的自动化任务编排。跨会话、跨模型的状态同步三个文件构成的项目状态是否可以抽象成一个标准化的“项目上下文包”这个包可以在Claude、GPT、Gemini等不同模型间传递实现真正的“模型无关”的项目延续。与项目管理工具深度集成task_plan.md中的复选框状态是否可以自动同步到GitHub Projects、Linear或Jira的任务看板上让AI的工作进度直接可视化到团队的工作流中。“Planning with Files”的成功本质上是因为它精准地击中了当前AI编程的痛点状态管理。它用最简单、最通用文件系统、最符合程序员直觉Markdown的方式给出了一个优雅的解决方案。它没有试图去改变AI模型本身而是巧妙地改变了我们与AI协作的界面和协议。这或许就是所有伟大工具的共同特质它们不创造新事物而是为新事物扫清障碍。