planning-with-files 完全指南：从入门到高阶，规范你的 AI 编程智能体

本文面向有一定 AI 编程工具使用经验的开发者，从原理到实战，手把手讲解 planning-with-files 这套工作流的完整用法。

1. 问题的根源：AI 智能体为什么会"遗忘"？

如果你用过 Claude Code、Cursor 或 Gemini CLI 处理超过 10 步的复杂任务，大概率踩过这些坑：

AI 写到一半，忘记了你最初的需求
遇到报错后反复尝试同一种无效修复
上下文窗口被海量搜索结果撑满，关键信息被截断
重启会话后，之前所有的"记忆"灰飞烟灭

这些问题都指向同一个根本原因：大语言模型的工作记忆是易失性的。

可以把上下文窗口理解为电脑的 RAM------速度快、容量有限，断电即清零。当工具调用越来越多，这块"内存"就会被占满，越早写入的目标和发现就越容易被挤出注意力范围。

解决思路也就呼之欲出：把关键信息持久化写入文件，让文件系统充当大模型的外置硬盘。

这正是 planning-with-files 这个项目的核心思想。

2. 核心概念：三文件模式是什么？

planning-with-files 在任何复杂任务启动前，会在项目根目录强制创建三个 Markdown 文件。它们各自承担不同的"认知职责"：

文件名	类比	核心职责
`task_plan.md`	项目总指挥部	存放目标、分阶段清单、错误记录表
`findings.md`	知识蒸馏仓库	存放调研结果、API 参考、技术选型推演
`progress.md`	行动黑匣子	存放操作日志、时间戳、测试输入输出对比

2.1 task_plan.md：宏观蓝图

这是 AI 的"北极星"。它把一个复杂需求拆解为 3~7 个具体阶段，每个阶段用 Markdown 复选框跟踪进度：

markdown 复制代码

# Phase 1: 需求调研
- [ ] 确认用户交互方式
- [ ] 调研现有方案
**Status:** in_progress

# Phase 2: 架构设计
- [ ] 设计数据模型
**Status:** pending

AI 在每次做决策前都要重读这个文件，防止大方向跑偏。

2.2 findings.md：知识隔离仓库

当 AI 浏览文档或搜索资料时，搜索结果会极其消耗上下文。 findings.md 的作用是把这些"海量原始信息"蒸馏为简洁的要点，防止外部内容把工作记忆撑爆，同时也防范潜在的提示词注入风险。

2.3 progress.md：可恢复的审计日志

这是最有价值的"保险"。一旦会话崩溃或你中途离开，通过查阅这份日志可以立刻回答五个关键问题：

我现在在哪个阶段？
我的目标是什么？
我已经发现了什么关键信息？
我做了哪些操作？
有没有尚未解决的错误？

3. 环境配置：多平台安装指南

3.1 Claude Code（推荐，最完整的支持）

需要 Claude Code v2.1.0 或以上版本。在终端执行：

bash 复制代码

/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files

安装成功后，启动新会话会看到 [planning-with-files] Ready。

触发方式有两种：

自动触发：AI 检测到当前指令包含超过 5 个步骤时自动激活
手动触发 ：输入 /plan 或 /planning-with-files:start

3.2 Cursor IDE

将仓库克隆后，把 .cursor 目录复制到项目根目录：

bash 复制代码

git clone https://github.com/OthmanAdi/planning-with-files.git
cp -r planning-with-files/.cursor .cursor

这会导入 hooks.json，其中定义了 preToolUse、postToolUse、stop 三种拦截器（详见第 4 章）。

建议：将 task_plan.md 固定在编辑器的分屏视图中，便于实时查看进度。

3.3 Windows 环境特别说明

Windows 用户需要注意两点差异：

路径差异 ：Windows 使用 \ 分隔符，用户目录为 %USERPROFILE%，而非 Unix 的 ~/.claude/。

换行符问题：如果 Markdown 模板排版错乱，通常是 CRLF 换行符导致，可通过 PowerShell 修复：

powershell 复制代码

(Get-Content template.md) | Set-Content -Encoding UTF8 template.md

钩子兼容 ：将 .cursor/hooks.windows.json 重命名为 hooks.json，以正确调用 .ps1 脚本（而非默认的 Bash 脚本）。

3.4 其他平台

该工具官方支持超过 17 个平台，包括 Mastra Code、Gemini CLI、 GitHub Copilot 等。

Mastra Code 注意 ：不要直接覆盖已有的 ~/.mastracode/hooks.json，需要手动将新钩子的 JSON 节点合并进去，避免破坏已有配置。

4. 黄金守则：重塑 AI 的行为逻辑

光靠文件还不够，真正让 AI 变"靠谱"的是内置于 SKILL.md 的四条行为约束。这些规则通过系统提示词和外部拦截器双重保障执行。

守则一：强制优先规划

在没有创建并填写 task_plan.md 之前，AI 绝对不能写一行代码。

这条守则对抗的是大模型的"即时服从"本能------它们往往接到指令就冲动地开始写代码，却跳过了最关键的逻辑拆解和风险评估环节。

守则二：读而后决

在做任何架构决策或技术选型之前，必须先重读 task_plan.md。

Transformer 的注意力机制会随上下文增长而衰减。在漫长的调试过程中， AI 可能已经忘记了半小时前你提出的初始需求。这条守则相当于给注意力强制刷新了一次。

守则三：双重行动法则

每执行两次查看、搜索或浏览操作后，必须立刻将关键发现写入 findings.md。

为什么是"两次"？因为每次网页浏览都会消耗大量 Token。如果放任不管，第三次、第四次搜索的结果会把第一次搜索的关键信息直接顶出上下文。

这条法则强制 AI 在信息过载之前完成"知识蒸馏"。

守则四：三击错误防范协议

任何错误都必须被显式记录，且下一次尝试必须采用本质上不同的解决路径。

普通 AI 遇到 Bug 的反应：盲目修改一行代码 → 重试 → 还是失败 → 继续盲目修改。

这条协议强制要求：

在 progress.md 的错误日志中打时间戳记录异常
在 task_plan.md 的错误表中登记根本原因
下次必须变异解决方案（从根本上换一种思路），而非小修小补

5. 生命周期钩子：自动化的"行为警察"

如果仅靠提示词约束，AI 依然可能在深度重构中"越狱"。真正的强制执行来自与 IDE 深度耦合的生命周期钩子。

5.1 会话启动钩子（SessionStart）

每次启动环境时，自动将当前活跃计划文件的内容注入为系统背景，确保 AI 一上来就知道"我在做什么项目"。

5.2 提示词提交钩子（UserPromptSubmit）

每次用户提交新指令时，静默地重新注入计划和进度摘要，防止多轮对话中的状态感知断层。

5.3 工具调用前置钩子（PreToolUse）⭐ 最精妙的设计

触发时机 ：AI 尝试调用 Write、Edit、Bash、Read、Glob、Grep 等任何可能改变系统状态的工具之前。

执行逻辑 ：截取 task_plan.md 的前 30 行（通常包含目标和当前阶段），通过标准错误流（stderr）以非阻塞方式"耳语"给模型：

"在你敲下这行代码前，记住我们当前的终极目标是什么。"

关键点：它不阻止工具调用（决策始终为 allow），只是在执行前强制刷新一次目标记忆。这是对抗"目标漂移"的最有效手段。

5.4 工具调用后置钩子（PostToolUse）

AI 完成文件修改后，自动弹出提醒：

"如果你刚完成了一个阶段的核心工作，请更新 progress.md 并勾选计划复选框。"

这填补了模型在长时间执行后规划能力下降的缺口。

5.5 终止审查钩子（Stop）⭐ 最后一道关卡

当 AI 认为任务完成并想"交差"时，Stop 钩子会拦截并运行 check-complete.sh 脚本，对 task_plan.md 进行正则扫描：

检查所有 ## Phase 区块下方是否包含 **Status:** complete 或 [x]
发现任何未完成项目 → 阻断退出，强制返回继续处理
安全保险 ：最多阻断 3 次（loop_limit），避免陷入死循环

6. 新手实战演练：构建一个命令行 Todo 应用

理论讲完，来看一个完整的工作流案例。

Step 1：启动并生成蓝图

在终端输入 /plan，提出需求：

复制代码

用 Python 构建一个命令行的 Todo 待办事项应用，支持增删改查

AI 立即生成三个文件，并在 task_plan.md 中自动拆解为五个阶段：

markdown 复制代码

# Phase 1: 需求调研
- [ ] 确定 CLI 参数结构
- [ ] 调研存储方案
**Status:** in_progress

# Phase 2: 架构设计
- [ ] 设计数据模型
**Status:** pending

# Phase 3: 核心实现
**Status:** pending

# Phase 4: 测试验证
**Status:** pending

# Phase 5: 交付打包
**Status:** pending

Step 2：调研阶段（双重行动法则生效）

AI 查阅了 Python 的 argparse 和 sys.argv 文档，完成两次浏览后，立即在 findings.md 中蒸馏关键发现：

markdown 复制代码

# 技术决策

## CLI 框架
- 放弃 `sys.argv`，采用 `argparse`
- 原因：支持子命令（如 `python todo.py add "Buy milk"`），自动生成帮助文档

## 数据存储
- 采用 JSON 文件持久化（`data.json`）
- 理由：零依赖、易调试、满足当前规模需求

随后将 Phase 1 标记为 [x]，并在 progress.md 记录： 完成架构调研，确定使用 argparse + JSON

Step 3：编码与错误处理（三击协议生效）

AI 编写核心逻辑后执行测试：

bash 复制代码

python todo.py list

终端抛出错误：

vbnet 复制代码

FileNotFoundError: [Errno 2] No such file or directory: 'data.json'

没有规划约束的 AI 行为：随机加几行 try-except，继续重试。

有协议约束的 AI 行为：

在 progress.md 错误日志打上时间戳，记录完整异常
在 task_plan.md 错误表中分析根本原因： 程序尝试读取不存在的 data.json
变异解决方案 ：不修改 list 命令本身，而是重构底层数据加载函数，加入前置判断：若文件不存在则自动初始化空 JSON 数组

Step 4：测试记录与会话恢复

测试完成后，progress.md 会自动积累一张对比表：

测试场景	输入命令	预期结果	实际结果	状态
初始列表	`python todo.py list`	提示"列表为空"	FileNotFoundError	❌ 失败
修复后重试	`python todo.py list`	提示"列表为空"	正确输出	✅ 通过
添加任务	`python todo.py add "Buy milk"`	写入 JSON	成功	✅ 通过

如果此时执行 /clear 清空会话，AI 重启后会自动执行 "5 问重启检查"：

我在哪个阶段？→ 读 task_plan.md
我的目标是什么？→ 读任务描述
我发现了什么？→ 读 findings.md
我做了什么？→ 读 progress.md
有未解决的问题吗？→ 检查错误日志

5 秒内无缝恢复状态，继续工作。

7. 进阶：并行规划与多智能体编排

当你需要同时开发多个模块（如前端 + 后端 + 数据库），让所有任务共享同一个 task_plan.md 会引发状态冲突。

planning-with-files 通过 .planning/ 隔离目录解决这个问题。

优先级级联解析

系统按以下优先级决定当前活跃的项目上下文：

bash 复制代码

1. 环境变量 $MANUS_PROJECT（最高优先级，适合 CI/CD）
         ↓
2. .planning/.active.override.$SESSION_ID（会话级隔离）
         ↓
3. .planning/index.md 中的 active: 字段（工作区默认）

最妙的设计是第 2 级：系统提取当前终端的唯一会话 ID，使得两个终端窗口的 AI 实例天然映射到独立的规划沙箱，彻底消除状态碰撞。

在自然语言层面，你可以直接说：

arduino 复制代码

switch to backend-api

或者：

arduino 复制代码

set default frontend

AI 会自动在任务编排网络中切换上下文。

会话恢复与超长项目

对于超大型项目，上下文耗尽后执行 /clear， session-catchup.py 会自动唤醒执行以下操作：

深层扫描：定位会话缓存文件（路径因平台而异，此处略去具体系统路径）
智能截断 ：提取自上次 task_plan.md 变动之后产生的新对话
精华注入：以不超过 100 行的摘要形式重新注入到新会话中

这一机制在大幅降低 Token 消耗的同时，显著提升了 KV-Cache 的命中率。

8. 生产级安全：沙箱与回滚机制

当 AI 被授权执行 Bash 脚本或直接修改文件时，安全不可忽视。

沙箱隔离

对于高危重构场景，可结合 ClaudeBox 将工作流移入轻量级虚拟机。技能文件和钩子脚本通过 Skill API 映射注入到沙箱内部，在完全隔离环境中依然保持完整的生命周期管控。

检查点快照与秒级回滚

当 task_plan.md 标记即将进入破坏性重构阶段时，外部调度脚本可预先创建虚拟机快照：

python 复制代码

# 重构前创建检查点
await box.snapshot("pre-refactor")

# 执行重构...

# 如果出现错误，秒级回滚
if "error" in result:
    await box.restore("pre-refactor")

这让 Markdown 文件不再只是规划文本，而是升华为底层计算状态的版本控制锚点。

9. 总结：文件系统就是最好的 AI 外脑

梳理全文，planning-with-files 的价值可以浓缩为一句话：

用持久化的文件系统，弥补大语言模型易失性上下文的先天缺陷。

三文件模式解决了三个核心问题：

问题	解决方案
目标漂移	`task_plan.md` + PreToolUse 钩子强制注意力刷新
知识遗失	`findings.md` 双重行动法则蒸馏关键信息
状态不可恢复	`progress.md` + 会话恢复脚本实现断点续传

给新手的建议：从一个简单项目开始（比如本文的 Todo 案例），完整跑一遍工作流，亲身感受"有计划"和"无计划"的 AI 执行差异。这比读一百遍文档都有效。

给进阶用户的建议 ：研究 check-complete.sh 的正则逻辑和优先级级联解析机制，这是构建自定义多智能体编排系统的最佳切入点。

不要再让你的 AI 在漫无边际的上下文中迷失方向了。 建立计划，严格规范，在 Markdown 的字符之间，重塑代码生产的秩序。