planning-with-files

Planning with Files

像 Manus 一样高效工作：将持久化的 Markdown 文件作为你的“磁盘工作记忆”。

第一步：恢复上下文上下文 (v2.2.0)

在开始处理任何任务之前，首先检查是否存在规划文件并进行读取：

如果 task_plan.md 存在，立即读取 task_plan.md、progress.md 和 findings.md。
然后检查上一会话中是否存在未同步的上下文：

# Linux/macOS — 自动检测 Skill 目录（插件环境变量或默认安装路径）
SKILL_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/skills/planning-with-files}"
$(command -v python3 || command -v python) "${SKILL_DIR}/scripts/session-catchup.py" "$(pwd)"

# Windows PowerShell
& (Get-Command python -ErrorAction SilentlyContinue).Source "$env:USERPROFILE\.claude\skills\planning-with-files\scripts\session-catchup.py" (Get-Location)

如果 Catchup 追赶报告显示存在未同步的上下文：

运行 git diff --stat 查看实际的代码变动
读取当前的规划文件
根据 Catchup 报告和 git diff 更新规划文件
然后继续执行任务

重要说明：文件存放路径

模板文件 位于 ${CLAUDE_PLUGIN_ROOT}/templates/
你的规划文件 必须保存在 你的项目根目录 中

位置	存放内容
Skill 目录 (`${CLAUDE_PLUGIN_ROOT}/`)	模板、脚本、参考文档
你的项目目录	`task_plan.md`、`findings.md`、`progress.md`

快速上手

在开始任何复杂任务之前：

创建 task_plan.md — 参考 templates/task_plan.md
创建 findings.md — 参考 templates/findings.md
创建 progress.md — 参考 templates/progress.md
决策前重新读取规划文件 — 在注意力窗口（Context Window）中刷新目标
每个阶段结束后及时更新 — 标记完成状态，记录遇到的错误

注意： 规划文件必须放在你的项目根目录中，而不是 Skill 的安装目录。

核心模式

上下文窗口 (Context Window) = 内存 RAM（易失、容量有限）
文件系统 (Filesystem) = 硬盘 Disk（持久化、容量无限）

→ 任何重要的信息都要实时落盘保存到磁盘。

各文件用途

文件	用途	何时更新
`task_plan.md`	阶段划分、进度跟踪、重大决策	每个阶段完成后
`findings.md`	调研结果、新发现、技术结论	产生任何新发现后
`progress.md`	会话日志、测试结果、操作记录	贯穿整个会话过程

关键规则

1. 先建规划，再动手

绝不要在没有 task_plan.md 的情况下启动复杂任务。这是硬性原则，绝无例外。

2. “双步执行”落盘规则（2-Action Rule）

“每进行 2 次查看/浏览器操作/搜索后，必须立即将关键发现写入文本文件。”

这可以有效防止视觉及多模态信息因上下文滚动而丢失。

3. 决策前必读

在做出重大决策之前，务必重新读取规划文件。这有助于在注意力窗口中持续聚焦目标。

4. 行动后必更

完成任意阶段后：

标记阶段状态：in_progress → complete
记录过程中遇到的所有错误
记录已创建或修改的文件

5. 记录所有错误

遇到的每一个错误都要记入规划文件。这有助于沉淀经验并避免重复犯错。

## 遇到的错误
| 错误信息 | 尝试次数 | 解决方案 |
|-------|---------|------------|
| FileNotFoundError | 1 | 创建了默认配置文件 |
| API timeout | 2 | 添加了重试逻辑 |

6. 切勿重复失败的尝试

if action_failed:
    next_action != same_action

追踪你已经尝试过的方案。一旦失败，必须改变解决路径。

7. 完成后继续追加任务

当所有阶段均已完成，但用户提出了补充需求时：

在 task_plan.md 中追加新阶段（如 Phase 6、Phase 7）
在 progress.md 中记录新的会话日志
按照正常规划流程继续推进工作

错误处理三板斧协议（3-Strike Error Protocol）

第 1 次尝试：排查诊断与针对性修复
  → 仔细阅读错误信息
  → 找出根本原因
  → 进行针对性修复

第 2 次尝试：换用替代方案
  → 出现相同错误？尝试不同的实现路径
  → 换用其他工具？换用其他第三方库？
  → 绝对不要重复完全相同的失败操作

第 3 次尝试：全面重新审视
  → 质疑先前的假设
  → 搜索相关解决方案
  → 考虑重新调整规划

连续 3 次失败后：升级上报给用户
  → 详细说明已尝试过的方案
  → 附上具体的错误日志
  → 请求用户指导

读写决策矩阵 (Read vs Write Decision Matrix)

场景	对应操作	原因/依据
刚写入某个文件	不要读取	内容依然保存在当前上下文（Context）中
查看了图片/PDF	立即将结论写入文档	避免多模态视觉信息在后续对话中丢失
浏览器返回了数据	保存到文件	截图和动态数据不会自动持久化
准备开启新阶段	读取 plan/findings	上下文可能过期，需要重新对齐目标
发生错误	读取相关文件	需要了解当前精确状态以便修复
中断后重新恢复会话	读取所有规划文件	全面恢复工作状态

上下文重置五问自测 (The 5-Question Reboot Test)

如果你能准确回答以下 5 个问题，说明你的上下文管理非常稳健：

问题	答案来源
我目前处于哪个阶段？	`task_plan.md` 中的当前阶段
后续还要做什么？	`task_plan.md` 中的剩余阶段
最终目标是什么？	`task_plan.md` 中的目标声明
目前沉淀了哪些结论？	`findings.md`
目前已经完成了哪些工作？	`progress.md`

适用场景与跳过条件

适用于：

多步骤复杂任务（3 个步骤以上）
深度调研与分析任务
从零构建/新建项目
涉及大量工具调用的任务
任何需要结构化组织的复杂工作

无需使用：

简单问答
单文件微调/小修改
快速检索/查找信息

模板参考

复制以下模板即可开始：

templates/task_plan.md — 阶段与进度跟踪
templates/findings.md — 调研结论存储
templates/progress.md — 会话日志记录

辅助脚本

用于自动化流程的辅助脚本：

scripts/init-session.sh — 初始化规划文件。传入名称参数时，会在 .planning/YYYY-MM-DD-<slug>/ 下创建隔离的规划目录以支持并行任务工作流；不传参数时，直接在项目根目录生成 task_plan.md（传统模式，向后兼容）。
scripts/set-active-plan.sh — 切换当前激活的规划指针（.planning/.active_plan）。传入 Plan ID 进行切换；无参数运行则显示当前激活的规划。
scripts/resolve-plan-dir.sh — 解析当前激活的规划目录。优先检查 $PLAN_ID 环境变量，其次检查 .planning/.active_plan，再次寻找修改时间最新的规划目录，最后兜底回退到项目根目录（传统模式）。由 Hook 内部调用。
scripts/check-complete.sh — 检查当前激活的规划中所有阶段是否均已完成。
scripts/session-catchup.py — 在 /clear 后恢复上一会话的上下文 (v2.2.0)。
scripts/attest-plan.sh (以及 .ps1) — 使用 SHA-256 签名校验锁定当前 task_plan.md 内容 (v2.37.0)。若文件内容与签名哈希不一致，Hook 将拒绝注入规划内容。使用 --show 打印已保存的哈希值，使用 --clear 移除签名认证。参阅 /plan-attest 命令。

并行任务工作流

当在同一个仓库中同时处理多个任务时：

# 启动任务 A
./scripts/init-session.sh "Backend Refactor"
# → .planning/2026-01-10-backend-refactor/task_plan.md

# 在第二个终端中启动任务 B
./scripts/init-session.sh "Incident Investigation"
# → .planning/2026-01-10-incident-investigation/task_plan.md

# 切换当前激活的规划
./scripts/set-active-plan.sh 2026-01-10-backend-refactor

# 或将当前终端固定绑定到特定规划
export PLAN_ID=2026-01-10-backend-refactor

每一个会话都会从各自独立的规划目录读取数据。Hook 会自动解析对应的规划目录。

scripts/session-catchup.py — 恢复上一会话的上下文 (v2.2.0)。对于 OpenCode (v2.38.0+)，将读取新版 SQLite 存储（位于 ${XDG_DATA_HOME:-~/.local/share}/opencode/opencode.db），而非旧版 JSON 树。

Claude Code Turn-Loop 循环集成 (v2.38.0+)

Claude Code 于 2026 年 5 月推出了三个全新的 Turn-Loop 原生特性：/loop (v2.1.72)、/goal (v2.1.139) 以及 PreCompact Hook 事件。v2.38.0 版本将文件规划工作流深度无缝接入了这三项功能。

安装作用域：插件模式 vs 仅 Skill 模式 (v2.42.0 补充说明)

并非所有安装路径都会包含本节所述的所有功能界面。目前存在两条独立的安装途径：

安装途径	包含内容	是否支持 `/plan-goal` 与 `/plan-loop`？
执行 `/plugin marketplace add OthmanAdi/planning-with-files` 后执行 `/plugin install`	SKILL.md、脚本、模板，以及 `commands/` 目录	支持，可直接使用 `/plan-goal` 和 `/plan-loop`
执行 `npx skills add OthmanAdi/planning-with-files`（或通过 ClawHub）	仅包含 SKILL.md、脚本与模板	不支持，请参考下方的手动替代方案

PreCompact Hook 注册在 SKILL.md 的 Frontmatter 中，对两种安装途径均生效。而 /plan-goal 与 /plan-loop 斜杠命令存放在仓库根目录的 commands/ 中，仅插件安装途径会将其复制到 ~/.claude/plugins/marketplaces/。仅 Skill 模式安装则保存在 ~/.claude/skills/planning-with-files/，无法读取 commands/ 目录。

这两条斜杠命令均设置了 disable-model-invocation: true，这意味着模型不会自动触发它们，需要由用户手动输入。根据 Claude Code 的已知行为（参见 anthropics/claude-code issues #26251, #41417），部分会话在解析 `disable-model-invocat

你可能还喜欢

mcp-builder

69Kresearch-knowledge

用于构建高质量 MCP（模型上下文协议）服务器的指南，使 LLM 能够通过精心设计的工具与外部服务交互。在构建 MCP 服务器以集成外部 API 或服务时使用，无论是使用 Python（FastMCP）还是 Node/TypeScript（MCP SDK）。

composiohq

获取

agent-reviewer

71Kresearch-knowledge

Agent skill for reviewer - invoke with $agent-reviewer

ruvnet

获取

planning-with-files

47Kresearch-knowledge

Work like Manus: Use persistent markdown files as your \"working memory on disk.\"

sickn33

获取

继续探索

浏览 research-knowledge 热门 Skills 最近更新