planning-with-files 任务完成后如何保留和归档 task_plan.md 等规划文件-酒店常州论坛

planning-with-files 任务完成后如何保留和归档 task_plan.md 等规划文件

【免费下载链接】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 的 agent 在任务结束后，task_plan.md、findings.md、progress.md这些规划文件并不会自动进入某种"已归档"状态。如果你的顾虑是：下一个任务会不会把这次任务的计划冲掉、这些文件会不会被 git 忽略掉永远丢失、还是想把有价值的决策和错误记录沉淀下来，这篇内容基于 docs/workflow.md 中"After Completion: What Happens to the Plan Files"一节的实际说明，给出一条从"确认任务完成"到"决定保留方式"的可执行路径。

先搞清楚默认行为：任务完成后系统什么都不做

planning-with-files 的规划文件被定位为单次任务的工作内存，而不是需要长期管理的交付物。文档明确说明（docs/workflow.md）：

task_plan.md、findings.md、progress.md以及.planning/<slug>/目录默认被 gitignore，任务结束时没有任何自动归档动作；
root 模式下（三个文件放在项目根目录），下一个任务会直接覆盖task_plan.md；
slug 模式下（./scripts/init-session.sh <slug>创建的.planning/YYYY-MM-DD-slug/目录），旧目录只是不再被选为活动计划，目录本身留在磁盘上；
不存在自动的 "completed" 或 "archived" 状态；check-complete只报告完成状态，不会移动或提取任何文件。

这是刻意设计的默认行为，不是缺失的功能。所以"保留和归档"这件事，需要你在任务真正完成后、下一个任务开始前，自己按下面的路径完成。

第一步：确认任务确实完成，再处理文件

保留文件的前提是任务真的做完了。按 docs/quickstart.md 的 Step 5，完成判定分两步：

检查task_plan.md：所有阶段都应有**Status:** complete，勾选框为[x]；
运行完成检查（如果你通过 hooks 使用，Stop hook 会自动执行这一步）：

./scripts/check-complete.sh

该脚本按$PLAN_ID→.planning/.active_plan→ 最新 mtime 的 slug 目录 → 根目录task_plan.md的顺序解析目标计划（见 scripts/check-complete.sh 头部注释），并统计各阶段状态。如果还有in_progress阶段，说明任务未完成，此时先继续工作；确认全部完成后，再进入下一步的保留操作。

第二步：选择保留方式（文档给出的三条路径）

docs/workflow.md 明确列出了三种让已完成计划存续的做法，按"内容价值"从高到低说明：

路径一：把值得留的内容提炼进代码或文档（推荐的沉淀方式）

文档原话是：任何想比任务活得更久的东西，应该已经放在持久位置——代码、提交、规格或文档里。具体操作是把计划中你认为重要的部分提炼出来：

把关键决策写入代码注释、commit message、ADR 或仓库docs/下的笔记；
把task_plan.md的 "Errors Encountered" 表和findings.md的 "Technical Decisions" 表中值得复用的条目，整理成文档提交。

这一步是纯手工的内容整理，脚本不提供自动化；好处是沉淀下来的是结论而不是过程记录。

路径二：把整个 slug 目录移出忽略范围

如果你希望完整保留某一任务的三个规划文件，文档给出两个操作：

把.planning/<slug>/目录移动到 git 忽略路径之外（例如仓库内的docs/archive/下，或你自己的其他目录）；
或者在希望跟踪计划的仓库中，从.gitignore里移除对.planning/的忽略项。

两种写法只改你自己的项目配置，不影响 planning-with-files 的运行——hooks 解析的是计划目录位置，而不是 git 状态。移动目录后，该 slug 就不再是活动计划，不会影响后续任务。

路径三：留作个人复用的缓存，用 PLAN_ID 或 .active_plan 固定

对于"这个计划以后还会用"的场景（例如同一重构的后续迭代），文档建议直接把目录留在原处当作缓存，用选择器固定它：

# POSIX shell：在启动 host 之前，用初始化时打印的精确 ID 固定当前终端 export PLAN_ID=the-printed-id # PowerShell 写法 $env:PLAN_ID = 'the-printed-id'

或切换到共享指针：

./scripts/set-active-plan.sh 2026-01-10-backend-refactor

需要注意：PLAN_ID在 v3.15.0 起是绑定性选择器——写错 ID 时解析直接失败，而不会悄悄回退到根目录计划（见 README.md 的 v3.15.0 说明）。另外，set-active-plan.sh修改的是共享指针，适合顺序切换；并发会话应各自用独立的PLAN_ID，在启动 host 前设置，在单个工具子进程里设置不影响已经运行的 host。

验证与限制

做完路径二后，用git status或git check-ignore -v <目录>确认目标目录不再被忽略，即视为保留生效；路径三的验证方式是指定选择器后运行./scripts/check-complete.sh，它报告的应是固定到的那个计划的状态而非根计划。
明确的限制：完成触发的自动归档步骤（把.planning/<slug>/移入归档目录并提取决策/错误表为 git 跟踪记录）目前并未内置，文档将其描述为一个合理的 opt-in 扩展方向，欢迎提 issue 或 PR。在实现之前，不要假设任何自动归档行为会发生。
规划文件是普通 markdown，没有任何其他运行时状态；"归档"的本质只是决定哪些文件继续留在磁盘上、哪些内容被提炼进版本库。

完整生命周期说明见 docs/workflow.md，任务收尾的完整步骤见 docs/quickstart.md 的 Step 5，README 的 FAQ 中"What happens to the plan files after a task is complete?"一节给出了与上面一致的结论。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析