planning-with-files-lite — 文件化规划（精简版）

像 Manus 一样工作 —— 该 AI 智能体公司已被 Meta 以 20 亿美元收购。

本项目是 planning-with-files 技能面向 Claude Code 的精简发行版：通过基于文件的 规划，为模型提供持久化于磁盘的工作记忆，使任务目标、研究发现与执行进度能够在上下文 丢失、/clear 清理及程序崩溃后依然得以保全。本项目为派生改造版本，版本号 v3.0.0， 采用 MIT 许可证。上游仓库： OthmanAdi/planning-with-files。

Manus 渊源

2025 年 12 月 29 日， Meta 以 20 亿美元收购 Manus。 Manus 在八个月内即从产品发布走向逾 1 亿美元的营收，而其真正擅长的核心能力，是 上下文工程（context engineering）——将文件系统而非上下文窗口，视为智能体真正的 记忆载体。

“Markdown 是我留存于磁盘上的‘工作记忆’。由于我以迭代方式处理信息，且活动上下文 存在容量上限，Markdown 文件得以充当笔记的草稿纸、进度的检查点，以及最终交付物的 构建单元。” —— Manus AI

本技能将这一实践方法封装至 Claude Code 之中。其中并无任何全新理论，仅是将 Manus 公开的方法论提炼为一份技能文件与少量 POSIX-sh 钩子脚本：模型在磁盘上维护三份 Markdown 文件并据此推进工作，而技能作用域钩子则确保规划内容始终留存于注意力窗口之内。

核心原则

上下文窗口 = 内存（易失、容量有限）
文件系统   = 磁盘（持久、容量无限）
→ 一切重要内容，皆写入磁盘。

项目根目录下 .planning/ 中的三份文件承载全部状态：

文件	用途
task_plan.md	目标、阶段、状态与决策
findings.md	研究结果与发现（经隔离处理的提示注入承载面）
progress.md	会话日志、操作记录与测试结果

技能文件向模型传授这一实践方法——即三份文件及其工作流程；前置元数据中声明的钩子， 则负责自动完成内容的再注入与提醒，以确保该实践得到切实贯彻。

Manus 原则

原则	本技能的实现方式
以文件系统为记忆	状态存于文件，而非上下文
以复述操控注意力	钩子在模型行动前再次注入规划摘要
保留错误轨迹	错误记录于规划文件的错误表中，绝不隐藏
目标追踪	机器可读的阶段状态驱动完成度检查
完成度校验	Stop 钩子在全部阶段完成时予以报告

完整的六项原则论述——KV 缓存设计、屏蔽优于移除、可还原压缩、复述机制、错误保留与 反少样本固化——载于 reference.md，提炼自 Manus 的 《面向 AI 智能体的上下文工程》。

本派生版本的定位

本项目是上游的一次有意为之的精简取舍。上游项目覆盖 60 余种智能体、五种语言、自主与 受控运行模式，并附有基准测试套件；而本发行版仅保留 Claude Code 用户所必需的部分：

• 仅支持英文，仅面向 Claude Code。
• POSIX-sh 脚本 —— 兼容 Linux、macOS 及 Windows Git Bash。
• 技能作用域的前置元数据钩子 —— 无需安装程序，无需改动 settings.json，亦无需 重启。钩子直接声明于技能的前置元数据中（即 SKILL.md 内的 hooks: 区块，详见 官方钩子文档）；调用 /planning-with-files 即可在当前会话的剩余周期内完成注册。

安装

cp -r skills/planning-with-files ~/.claude/skills/

安装至此即告完成——无需按项目逐一配置，无需改动 settings.json，亦无需重启。钩子 随技能一同分发，并在技能被调用时自动注册。升级方式：重新复制。若由 2.x 版本迁移而来， 请参阅“由 2.x 迁移”一节。

钩子

钩子声明于 SKILL.md 的前置元数据中。技能作用域钩子自技能被调用之时起即行生效，直至 会话结束；它们不会在 /clear、--resume 或新建会话后继续存留（已在 Claude Code 2.1.x 上经实证验证：会话恢复后，技能的钩子不再触发）。重新着手工作时，请重新 调用 /planning-with-files——技能的“首先：恢复上下文”步骤会将规划文件重新读入。

钩子	触发时机	作用
UserPromptSubmit	生效期间每次用户提交	注入规划摘要、近期进度与提交提醒（Manus 复述机制）
PostToolUse	Write/Edit 之后	提示更新 progress.md 并提交已完成的阶段
Stop	智能体完成一轮回应时	面向用户的 systemMessage：报告全部阶段是否完成，以及未提交改动的数量（该计数排除按设计频繁变动的 .planning/）

通道说明（依据官方钩子文档）：仅 SessionStart 与 UserPromptSubmit 两类事件的 正常退出（exit 0）标准输出会抵达模型，其余事件的标准输出均写入调试日志。因此 PostToolUse 采用文档所述的 additionalContext JSON 通道，而 Stop 报告则以面向 用户的 systemMessage 警示呈现。Stop 钩子有意不向模型注入任何内容：在 Stop 上 使用 additionalContext 会迫使智能体继续运行（经实证，曾出现单词提示循环触发至 八段上限的情形）。

路径说明（经实证验证，官方文档对此未作说明）：在前置元数据钩子命令内部，相对路径 以会话当前工作目录（而非技能目录）为基准解析，且 ${CLAUDE_SKILL_DIR} 并未设置。 唯一指向技能自身目录的变量是 ${CLAUDE_PLUGIN_ROOT}，故钩子命令均采用该变量。此外， 钩子会继承会话当前工作目录，而该目录可能在会话中途发生变动，因此脚本在解析 .planning/ 之前，会先将自身锚定至 ${CLAUDE_PROJECT_DIR}。

已移除的钩子

下列钩子原由 2.x 基于 settings 的安装方式所携带，在前置元数据模型下已属冗余或失效， 故予以移除而非移植：

已移除项	移除缘由
SessionStart 恢复注入（inject-plan.sh --context=sessionstart，匹配 startup/resume/clear/compact）	技能作用域钩子在会话启动时尚未注册，会被 /clear 清除，且无法在恢复后存留（已验证）——因此该钩子在真正需要时根本无从触发。恢复机制现已交由技能正文的“首先：恢复上下文”步骤（在每次重新调用时执行），并辅以生效后的 UserPromptSubmit 注入。
SessionStart 追补（session-catchup.py，匹配 startup/clear）	同样存在无法触发的问题，且其全部用途在于跨会话追补——此项工作需要能够存续于会话之外的钩子，而前置元数据钩子在设计上并不具备此能力。脚本已删除；重新调用技能并运行 git diff --stat 即可弥补该缺口。
PreCompact（已于 2.2 移除，至今未恢复）	PreCompact 的标准输出仅写入调试日志，无法对压缩摘要器下达指令。压缩完成后，Claude Code 会自动重新附加已调用技能的内容，随后的 UserPromptSubmit 注入亦会恢复规划摘要。

脚本

脚本	用途
init-plan.sh	在 .planning/ 中创建三份规划文件（创建该目录，迁移 2.1 版本之前置于根目录的文件，绝不覆盖已有文件；并在检测到 2.x 遗留钩子时予以警示）。
inject-plan.sh	钩子调度器，负责输出规划上下文（由前置元数据中的 UserPromptSubmit 与 PostToolUse 钩子调用）。
check-complete.sh	阶段完成度与未提交改动报告。直接运行时输出可读文本；附加 --hook（即前置元数据中的 Stop 项）时，仅在确有必要时（全部阶段完成，且/或存在 .planning/ 之外的未提交改动）输出面向用户的 JSON systemMessage。

使用方式

• 着手复杂任务时，在 Claude Code 中调用 /planning-with-files；模型将依据技能模板， 在项目根目录下的 .planning/ 中创建 task_plan.md、findings.md 与 progress.md，而前置元数据钩子则在该会话剩余周期内使规划持续留存于注意力窗口之内。 （本技能仅支持显式调用：disable-model-invocation: true。）
• 在 /clear、恢复会话或新建会话之后，请重新调用 /planning-with-files——此举将 重新注册钩子并重新读入规划文件。
• 脚本化初始化（可选）：执行 sh ~/.claude/skills/planning-with-files/scripts/init-plan.sh 即可在 .planning/ 中创建三份文件（并将 2.1 版本之前置于根目录的规划文件迁入其中）。

由 2.x 迁移

2.x 通过项目 settings 配置钩子，并随附脚本副本；其遗留内容会与前置元数据钩子并行触发 旧版脚本钩子。在每一个曾运行 2.x 安装程序的项目中，请执行以下操作：

1. 删除随附的运行时：rm -rf .claude/hooks/planning-with-files
2. 在 .claude/settings.json（若以 --local 安装，则还包括 .claude/settings.local.json）中，移除所有命令引用了 .claude/hooks/planning-with-files/ 的钩子条目。
3. 重启 Claude Code——settings 中的钩子在会话启动时即被固化快照。

权衡之处，可坦言如下：2.x 的 settings 钩子具备持久性（在项目的每个会话中均会触发， 可存续于 /clear 与恢复操作之后，且无需调用技能）；而前置元数据钩子作用于单个会话， 需重新调用 /planning-with-files。作为交换，所获收益为：免除按项目逐一安装、无需改动 settings.json、钩子随技能一并进行版本管理与分发，以及自动清理。

卸载

rm -rf ~/.claude/skills/planning-with-files

此外，对于仍残留旧版 settings 钩子的项目，请一并执行“由 2.x 迁移”中所述的清理步骤。

致谢

• Manus AI —— 感谢其开创了本技能所封装的上下文工程范式。
• Anthropic —— 感谢其提供 Claude Code、Agent Skills 及钩子系统。
• Lance Martin —— 感谢其对 Manus 架构所作的详尽分析。
• OthmanAdi/planning-with-files —— 本项目所派生自的上游技能。
• 来源：Manus，《面向 AI 智能体的上下文工程：构建 Manus 的经验》。

许可证

MIT。