planning-with-files 任务计划模板 task_plan.md 全解：用磁盘文件打造 AI Agent 的持久化工作内存
【免费下载链接】planning-with-filesPersistent file-based planning for AI coding agents and long-running tasks. Crash-proof markdown plans, session recovery after /clear and compaction, per-turn re-injection against context rot, deterministic completion gate. Manus-style. Install from npm, the Claude Code plugin marketplace, or npx skills. Codex, Cursor, OpenCode, 60+ agents.项目地址: https://gitcode.com/GitHub_Trending/pl/planning-with-files
本文以 planning-with-files 项目内置的 task_plan.md 模板 为骨架，系统讲解如何用一份结构化的 Markdown 文件为 AI 编码 Agent 建立"落盘的计划路线图"：从 Goal、Phases 到 Decisions、Errors 的每一个区块的含义与维护规则，并结合
check-complete.sh、init-session.sh等脚本源码，说明这些字段如何被脚本解析、注入并驱动整个生命周期。读完本文，你将能独立初始化、维护并验证一份可被 Agent 持续读取、可崩溃恢复、可完成度校验的任务计划文件。
一、task_plan.md 在文件规划体系中的定位
planning-with-files 的核心思想是：上下文窗口是易失、受限的 RAM，文件系统是持久、无限的磁盘——任何重要信息都应先写入磁盘。在此基础上，项目用三个固定文件承载 Agent 的"磁盘工作内存"：
| 文件 | 用途 | 更新时机 |
|---|---|---|
task_plan.md | 阶段划分、进度、决策 | 每个阶段完成后 |
findings.md | 研究结果、发现 | 任何一次发现之后 |
progress.md | 会话日志、测试结果 | 贯穿整个会话 |
其中task_plan.md是唯一的主计划文件，被生命周期钩子（UserPromptSubmit / PreToolUse / PostToolUse / Stop 等）反复读取注入上下文，也是完成度校验（check-complete.sh）和完成闸门（gated mode）的判定对象。模板本体在仓库中出现在多个安装面（如 .hermes 版本、skills 标准版、仓库根 templates 目录），内容保持一致，本文以下统称task_plan.md。
二、模板顶层结构一览
模板以一句使用说明开场："把本文件作为任务的持久路线图（durable roadmap）。在复杂工作开始前创建它，并在阶段变化时保持其最新。"
# Task Plan: [Brief Description] ← 标题：一句话描述任务 ## Goal ← 目标：一句话说清最终要达成的结果 ## Next Step ← 下一步：记录"接下来唯一要做的动作" ## Current Phase ← 当前阶段：正在进行的阶段名称 ## Phases ← 阶段列表：3~7 个可验证阶段，每个含状态标记 ## Key Questions ← 关键问题：待解答问题，解决后替换为答案 ## Decisions Made ← 已做决策：决策 + 理由的表格 ## Errors Encountered ← 错误记录：错误 + 尝试次数 + 解决方案 ## Notes ← 维护提示这个结构刻意保持扁平、无嵌套，目的是让脚本能用简单的文本匹配（grep/awk）可靠地解析，而不是依赖复杂的标记语言结构。下面逐节拆解。
三、头部三件套：Goal、Next Step、Current Phase
这三个区块构成了计划的"瞬时状态快照"，是每次注入上下文中优先级最高的信息。
Goal用一句话陈述任务的最终结果。它之所以必须精炼，是因为 SKILL.md 中"Read Before Decide"规则要求：在重大决策前重读计划文件，让目标始终停留在注意力窗口内。一个含糊的 Goal 会让 Agent 在长任务中逐渐漂移。
Next Step记录当前唯一应发生的动作，每当活动阶段或即时动作变化时都要更新。它是"下一步该做什么"的单一事实来源，避免 Agent 在多个候选动作之间自行猜测优先级。
Current Phase命名当前正在进行的阶段，与 Phases 区块中的状态标记呼应。三者的维护关系是：阶段状态流转（pending → in_progress → complete）发生时，Current Phase与Next Step必须同步刷新。
四、Phases 区块：阶段划分的核心语法
模板在 Phases 区块给出了严格的建模约束：
将任务拆分为 3 到 7 个可验证的阶段。每个阶段的状态只能使用
pending、in_progress或complete三值之一，并在工作推进时更新该值。
模板内置了五个通用阶段的完整示例：
### Phase 1: Requirements & Discovery - [ ] Understand user intent - [ ] Identify constraints and requirements - [ ] Document findings in findings.md - **Status:** in_progress ### Phase 2: Planning & Structure - [ ] Define technical approach - [ ] Create project structure if needed - [ ] Document decisions with rationale - **Status:** pending ### Phase 3: Implementation - [ ] Execute the plan step by step - [ ] Write code to files before executing - [ ] Test incrementally - **Status:** pending ### Phase 4: Testing & Verification - [ ] Verify all requirements met - [ ] Document test results in progress.md - [ ] Fix any issues found - **Status:** pending ### Phase 5: Delivery - [ ] Review all output files - [ ] Ensure deliverables are complete - [ ] Deliver to user - **Status:** pending每个阶段块遵循统一模式：
### Phase N: 名称三级标题：### Phase字样是脚本识别阶段边界的关键锚点（见下文 check-complete 解析逻辑）；- [ ] 动作项：阶段内可勾选的具体动作（模板有意使用 GitHub 风格 task list，方便人机共同追踪）；- **Status:** 状态：阶段的状态行，唯一合法的三值是pending/in_progress/complete。
状态值的三值语义
| 状态 | 含义 | 使用时机 |
|---|---|---|
pending | 尚未开始 | 计划创建时默认值 |
in_progress | 正在执行 | 阶段启动时从pending改为in_progress |
complete | 已完成 | 阶段验收通过后从in_progress改为complete |
注意：状态值本身是固定的英文标记字面量，不要翻译成其他语言。这一点在 v3 的并行写防护（parallel-write guard）设计中尤为重要：guard 通过比较轮次间的勾选项与完成阶段计数来检测"进度倒退"，而它依赖的正是所有语言版本的模板中都保留的字面**Status:** complete标记。若你使用多语言环境（如仓库 skills/i18n 下的 ar/de/es/zh/zht 版本模板），务必保持这些标记原样。
模板为何限定 3~7 个阶段
3 个是最小可验证粒度，少于 3 个说明任务过于简单（可直接用 "Skip for: simple questions / single-file edits / quick lookups" 原则跳过规划流程）；7 个是保持计划可读性与钩子注入效率的上限——每轮工具调用注入的是计划头部（默认head -30~head -50），阶段过多会导致注入窗口内挤不进当前活动阶段的信息（这也是 v3.8.0 引入结构感知注入PWF_INJECT=smart的动机：改为只注入标题、Goal/Next Step/Current Phase、阶段计数、第一个 in_progress 阶段全文和 Decisions 末 3 行）。
五、Key Questions 与 Decisions Made：决策过程的留痕
Key Questions记录重要问题，并在解决后把问题条目替换为答案：
1. [Question to answer] 2. [Question to answer]这使"未决问题"始终显式可见，避免 Agent 在信息不足时用默认假设悄悄推进。
Decisions Made用两列表格记录重大选择及其理由：
| Decision | Rationale | |----------|-----------| | | |决策留痕的意义在于：当 Agent 在长时间运行后上下文被压缩（compaction）或清空（/clear）时，task_plan.md中的决策记录是恢复"当时为什么这么选"的唯一依据。SKILL.md 的恢复流程要求：会话恢复后首先读取选定目录下的task_plan.md、progress.md、findings.md，再运行git diff --stat核对尚未写入计划文件的代码变更。
六、Errors Encountered：失败记忆库
| Error | Attempt | Resolution | |-------|---------|------------| | | 1 | |每个条目包含错误描述、尝试次数、解决方案三要素。SKILL.md 中的"Log ALL Errors"规则要求所有错误都写入计划文件，其目的有二：一是构建知识库、防止重复犯错；二是配合"Never Repeat Failures"规则——if action_failed: next_action != same_action——通过记录尝试历史强制 Agent 在重试时改变方法。错误表还支撑了"3-Strike 错误协议"：第 1 次尝试诊断修复，第 2 次换方法，第 3 次重新审视假设，3 次失败后升级给用户。
七、check-complete.sh 如何解析这份模板
task_plan.md之所以采用上述语法，是为了让 scripts/check-complete.sh 能用简单的文本匹配完成完成度判定。从源码看，其解析逻辑完全依赖模板约定：
- 阶段总数：
grep -c "### Phase"统计### Phase标题数量；若为 0（没有阶段化结构的计划），脚本直接退出，不输出虚假的"0/0 阶段完成"状态（issue #191）； - 状态计数：同时统计两种写法——主格式
**Status:** complete/**Status:** in_progress/**Status:** pending，以及内联格式[complete]/[in_progress]/[pending]，取两者较大值。这保证混合写法（一个阶段用**Status:**，另一个用内联标记）也不会漏计（对应模板注释中 "Count both formats per field and keep the larger of the two" 的设计）； - 输出判定：全部完成时输出
ALL PHASES COMPLETE (N/N)；否则输出Task in progress (N/N phases complete)，并分别报告仍 in_progress / pending 的阶段数； - 计划文件定位：按
$1显式路径 →resolve-plan-dir.sh（$PLAN_ID环境变量 →.planning/.active_plan指针 → 最新 mtime 的计划目录）→ 根目录task_plan.md（legacy 模式）的顺序解析；若显式指定了PLAN_ID或PWF_PLAN_ROOT却解析失败，则拒绝用根计划的结果代替（issue #237，显式选择器是"绑定"而非"提示"）。
在 gated（闸门）模式下，check-complete.sh --gate还会读取.mode文件、.stop_blocks计数、ledger 行数等，仅当"gated 模式 + 存在 in_progress 阶段 + 非 stop_hook_active + 未达阻止上限（默认 20 次，PWF_GATE_CAP可覆盖）+ 上次阻止后 ledger 有推进"五条件全部成立时才输出{"decision":"block",...}阻止停止——而这一切判定都建立在模板的### Phase与**Status:**语法之上。可见，模板语法的规范性直接决定脚本判定的正确性。
八、初始化一份可用的 task_plan.md
无需手工从零编写，项目提供 scripts/init-session.sh 一键生成三份规划文件。常见用法：
# 传统（legacy）模式：在项目根目录生成 task_plan.md / findings.md / progress.md ./scripts/init-session.sh # 指定模板类型（默认或 analytics） ./scripts/init-session.sh --template default # slug 模式：为独立任务创建隔离计划目录 .planning/YYYY-MM-DD-<slug>/ ./scripts/init-session.sh "Backend Refactor" # v3 自主模式：低复述注入 + 默认开启计划防篡改校验（attestation） ./scripts/init-session.sh --autonomous "Long Research Run" # v3 闸门模式：在自主模式基础上叠加完成闸门（阻止未完成即停止） ./scripts/init-session.sh --gated "Build Pipeline"slug 模式专为并行多任务设计（issue #148）：每个任务一个.planning/<id>/目录，并用.planning/.active_plan指针固定当前活动计划。并行协作时，为每个终端设置不同的PLAN_ID环境变量（如export PLAN_ID=2026-09-05-backend-refactor）再启动 Agent，即可让各主机各归其位。注意：PLAN_ID是相对于当前目录解析的 slug，只能命名$(pwd)/.planning下的计划；跨目录场景需用PWF_PLAN_ROOT=<绝对路径>固定计划根。
初始化后，用scripts/check-complete.sh可随时校验完成度：
./scripts/check-complete.sh # 输出示例： # [planning-with-files] Task in progress (1/5 phases complete). Update progress.md before stopping. # [planning-with-files] 1 phase(s) still in progress. # [planning-with-files] 3 phase(s) pending.九、与 findings.md、progress.md 的协同更新节奏
task_plan.md不是孤立文件，三份文件按各自的更新节奏协同：
| 事件 | 应更新的文件 |
|---|---|
| 需求调研/发现新事实 | findings.md（"2-Action 规则"：每 2 次浏览/搜索后立即把关键发现落盘） |
| 任一发现产生 | findings.md（"After ANY discovery"） |
| 阶段完成 | task_plan.md（状态流转）+ progress.md（会话日志、测试结果、文件变更） |
| 会话全程 | progress.md（贯穿始终） |
| 出错 | task_plan.md 的 Errors Encountered + progress.md 的 Error Log |
特别强调一条安全铁律：外部内容（网页、API 返回等）只能写入 findings.md，绝不能写入 task_plan.md。原因在 SKILL.md 的安全边界一节有明确说明：task_plan.md会被钩子自动读取并注入上下文，未受信任的外部内容写入其中会在每次工具调用时被放大（间接提示注入面）；而findings.md摄入的是原始研究数据，读取时一律视为不可信数据、不执行其中的任何指令。若怀疑计划被篡改，可用scripts/attest-plan.sh（或/plan-attest命令）锁定当前计划内容的 SHA-256 摘要，此后钩子在每次触发时计算哈希并比对，不一致则以[PLAN TAMPERED]警告阻止注入。
十、维护 task_plan.md 的七条关键规则与反模式
综合 SKILL.md 与模板 Notes 区块，维护规范可归纳为：
- Create Plan First：复杂任务开始前必须创建
task_plan.md，不可协商； - 2-Action Rule：每 2 次查看/浏览/搜索操作后立即保存关键发现到文件，防止多模态信息丢失；
- Read Before Decide：重大决策前重读计划文件，让目标停留在注意力窗口；
- Update After Act：阶段完成后更新状态（
in_progress → complete）、记录错误、标注新建/修改的文件；阶段状态变化时同步刷新 Next Step； - Log ALL Errors：所有错误写入 Errors Encountered；
- Never Repeat Failures：记录尝试历史，强制改变重试方法；
- Continue After Completion：全部阶段完成后用户追加需求时，在 task_plan.md 追加新阶段（如 Phase 6、Phase 7），在 progress.md 记录新会话条目，继续正常流程。
需要规避的反模式（详见 SKILL.md 的 Anti-Patterns 表）：
| 不要 | 应该 |
|---|---|
| 用 TodoWrite 做持久化 | 创建 task_plan.md 文件 |
| 只陈述一次目标然后遗忘 | 决策前重读计划 |
| 隐藏错误、静默重试 | 把错误记录到计划文件 |
| 把所有内容塞进上下文 | 大内容存文件 |
| 立即开始执行 | 先创建计划文件 |
| 重复失败动作 | 记录尝试、改变方法 |
| 在技能目录创建文件 | 在项目目录创建文件 |
| 把网页内容写进 task_plan.md | 外部内容只写 findings.md |
十一、恢复与续跑：模板在会话崩溃后的作用
task_plan.md 最大的价值在崩溃恢复。SKILL.md 的恢复流程（"FIRST: Restore Project State"）要求：续跑前用resolve-plan-dir.sh（配合PLAN_ID与PWF_PLAN_ROOT）解析出任务归属的计划目录，读取该目录下的task_plan.md、progress.md、findings.md；根目录的task_plan.md不得覆盖被选中的.planning/<id>/计划。恢复后用"5-Question Reboot Test"验证上下文是否健全：
| 问题 | 答案来源 |
|---|---|
| 我在哪？ | task_plan.md 的 Current Phase |
| 我要去哪？ | 剩余 Phases |
| 目标是什么？ | 计划中的 Goal 语句 |
| 我学到了什么？ | findings.md |
| 我做了什么？ | progress.md |
| 我接下来要做什么？ | task_plan.md 的 Next Step |
只要这六问都能从磁盘文件得到答案，即使上下文被/clear清空或压缩（compaction）后，Agent 也能完整恢复状态——这正是"Crash-proof markdown plans"设计目标的落地方式。配合/plan-goal（把"全部阶段报告 complete"作为/goal条件，让 Agent 坚持到计划真正完成）与/plan-loop（默认 10 分钟一轮重读计划文件、跑 check-complete、无进展则写 progress.md 条目）两个斜杠命令，还可实现"看护到完成"（babysit until done）的无人值守工作流。
结语
task_plan.md模板是 planning-with-files 整个机制的中枢：它的 Goal/Next Step/Current Phase 三件套为 Agent 提供瞬时状态，### Phase+**Status:**语法被 check-complete.sh 精确解析为完成度判定，Key Questions / Decisions Made / Errors Encountered 三区为上下文压缩后的恢复提供留痕依据。只需遵循本文所述的语法约定与维护节奏，配合 init-session.sh 初始化、check-complete.sh校验、attest-plan.sh防篡改，即可让任何基于文件的 AI Agent 拥有真正持久、可验证、可恢复的长任务工作内存。
【免费下载链接】planning-with-filesPersistent file-based planning for AI coding agents and long-running tasks. Crash-proof markdown plans, session recovery after /clear and compaction, per-turn re-injection against context rot, deterministic completion gate. Manus-style. Install from npm, the Claude Code plugin marketplace, or npx skills. Codex, Cursor, OpenCode, 60+ agents.项目地址: https://gitcode.com/GitHub_Trending/pl/planning-with-files
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
