模块 01

这个工具能做什么——从一次项目失控说起

你有没有遇到过这种情况?

第一个 session:你和 AI 讨论了三个技术方案,选了方案 A,觉得理由很充分。
第三个 session:AI 建议换方案 B,你隐约记得之前讨论过,但找不到记录,于是又讨论了一遍。
第五个 session:新来的同事问"为什么不用方案 C?"——没人说得清,因为当初的推理已经丢失了。
1

短期计划,用后即丢

AI 的 plan 功能只管"下一步做什么",不管"为什么这么做"

2

决策推理逐渐蒸发

哪些方案被排除了、为什么选了这条路——全靠记忆

3

重复讨论,方向漂移

没有记录,同样的决策反复推翻,项目越推进越模糊

4

无法恢复上下文

新 session 开始时,没人知道上次停在哪里、下一步该做什么

Plan Tree 登场

Plan Tree 是一个通用的 AI planning skill,把短期 plans 变成结构化的 Markdown 规划树,让项目跨会话、跨 agent 推进时不漂移。

P跨会话持久化
D跨 agent 不漂移
I意图与实现分离

为什么 AI 时代更需要它

过去和现在的工作重心发生了根本性变化:

源文 AI 让这个问题更明显。过去很多项目接近 10% 规划 + 90% 实施: 实现本身很慢,开发者有足够长的反馈周期边做边修正方向。 AI 时代实现速度被大幅压缩,复杂项目更接近 90% 规划 + 10% 实施。
逐句解读
AI 让规划缺失的问题暴露得更彻底。
以前项目大约 10% 时间花在规划上,90% 花在实现上。
因为实现本身很慢,开发者有足够时间边写代码边修正方向。
AI 把实现速度大幅压缩后,复杂项目的重心翻转了——90% 的精力在规划,只有 10% 在实现。
Aha!

这个比例不是精确工时,而是工作重心变化:质量越来越取决于前置方案是否充分、边界是否稳定、验收是否清楚、状态源是否统一。

随堂测验

你的团队用 AI 辅助开发,连续 5 个 session 后,以下哪种情况最需要 plan-tree?
正确!方案选择记忆丢失正是"规划漂移"的典型症状——plan-tree 专门解决这个问题。
不太对。调试、测试、性能优化都属于实现层面的问题,而 plan-tree 解决的是规划和决策层面的漂移。
模块 02

认识这棵树的居民

七个角色,各司其职

Roadmap

进度地图

项目状态分为 Done / In Progress / Next / Deferred 四个区域,一眼看清当前阶段。

Status

实施状态

当前交接、活跃 TODO、blockers——新 session 从这里恢复上下文。

Decisions

稳定决策

为什么这么选、后果是什么——决策一旦记录就不再凭空蒸发。

Open Questions

未决问题

只放真正没解决的问题,已决问题移到 Decisions,绝不混用。

Topics

方案图谱

约束、选项、验收标准——围绕一个主题的完整上下文。

History

历史证据

旧验证、检查点、过期材料——归档但不删除,保留推理轨迹。

Ideas

灵感收件箱

低承诺的想法,不被当作需求——成熟后才 promote 到正式节点。

它们怎么协作

inboxIdeas
stateRoadmap
handoffStatus
contextTopics
stableDecisions
unresolvedQuestions
archiveHistory

代码 ↔ 解读

SKILL.md 原文 - README.md: scope, authority, file map, reading path. - roadmap.md: durable state grouped as Done, In Progress, Next, and Deferred. - implementation-status.md: optional active handoff for current phase. - open-questions.md: unresolved questions only. - topics/: durable context, options, constraints, implementation notes. - decisions/: stable decisions, indexed when the set grows. - history/: accepted checkpoint logs, old reviews, retired snapshots.
逐行解读
README.md:规划入口,定义范围、权威顺序、文件地图和阅读路径。
roadmap.md:持久状态,按 Done / In Progress / Next / Deferred 分组。
implementation-status.md:可选的当前阶段交接文件。
open-questions.md:只放未解决的问题。
topics/:持久上下文——选项、约束、实施笔记。
decisions/:稳定决策,数量多时建立索引。
history/:已接受的检查点日志、旧评审、退役快照。

随堂测验

请将以下角色与职责正确匹配:"记录已接受的检查点日志和旧评审"
正确!History 专门存放已接受的检查点日志、旧评审和退役快照,保留推理轨迹但不污染活跃状态。
不对哦。检查点日志和旧评审属于历史证据,应该归档到 History,而不是放在活跃的 Roadmap 或 Decisions 中。
模块 03

信息怎么流动——从想法到决策到执行

一条想法的生命旅程

从灵感到归档,信息在规划树中的完整流动路径:

1

Idea 出现在收件箱

一个新想法被放入 ideas/inbox.md,此时它没有任何承诺。

2

Idea 被 promote 到 Roadmap

想法成熟后,从 ideas 移到 roadmap.md 的 Next 列,标记为已 promote。

3

Roadmap 项变为 In Progress

开始实施时,更新 roadmap 状态,创建 implementation-status.md。

4

实施产生证据

代码提交、测试通过、验证完成——这些都是"证据"。

5

证据更新状态 → Done

只有当 artifact 存在时,才在 roadmap 标记为 Done。

6

旧证据移入 History

归档而非删除——保留推理轨迹,保持活跃文件短小。

意图路由:请求去哪儿

用户的每一个请求都会被分类到对应的意图路由:

意图含义
idea添加低承诺想法到 ideas/inbox.md
promote把想法提升为 roadmap 项、topic 或 decision
status更新 roadmap 或实施/交接状态
question添加、缩小或解决一个未决问题
decision创建或更新稳定决策记录
archive把过期证据移出活跃文件
audit一致性、检索和漂移检查
resume恢复上下文:当前阶段、TODO、blockers
migrate评估或迁移旧规划树

看看各组件如何"对话":

我想加一个新功能
Plan Tree
这是一个 idea,先放进 ideas/inbox.md
这个想法成熟了,可以开始做了
Plan Tree
执行 promote:从 ideas 移到 roadmap.md 的 Next 列
Roadmap
收到,已加入 Next 列表
开始实施了
Plan Tree
更新 roadmap 为 In Progress,创建 implementation-status.md
Status
记录活跃 TODO 和 blockers
做完了
Plan Tree
验证 artifact 存在后标记 Done,旧证据移入 history/

代码 ↔ 解读

SKILL.md 核心工作流 1. Identify the plantree root, target plan root, and user intent before editing. 2. Read the root index plus only the relevant files. 3. Classify the request as idea, promotion, status, question, decision, archive, audit, resume, migrate, restructure, or consistency repair. 4. Preserve existing entrypoints, document style, and authority order. 5. Keep active roadmap and handoff files small. 6. Update indexes, retrieval headers, and links. 7. Run final checks before replying. 8. Report changed files, unresolved questions, and next useful action.
逐行解读
1 先定位规划树根目录、目标 plan 和用户意图,再动手编辑。
2 只读根索引和相关文件,不要一股脑全读。
3 把请求分类到对应的意图路由(idea、promote、status 等)。
4 保留现有的入口点、文档风格和权威顺序。
5 保持活跃的 roadmap 和交接文件短小精悍。
6 更新索引、检索头和链接。
7 回复前跑一遍最终检查。
8 报告变更的文件、未决问题和下一步建议。

随堂测验

用户说"我们之前讨论过用 Redis 还是 Memcached,但我不记得结论了",这应该走哪条意图路由?
正确!"讨论过"说明决策可能已经做出,只是没被记录或找不到。应该走 decision 路由——查找或创建决策记录。
不太对。关键词是"讨论过"——这不是新想法,也不是未决问题(可能已经有结论了),更不是实施状态。应该走 decision 路由。
模块 04

文件系统:这棵树长什么样

默认目录结构

plan-tree 的默认文件布局——每个文件都有明确的角色:

docs/plantree/ README.md ← 注册表、权威顺序、活跃 plans 表 baseline/ README.md ← 基线上下文入口 module-map.md ← 模块地图 runtime-flows.md ← 运行时流程 storage-and-state.md ← 存储与状态边界 test-and-release-gates.md ← 测试与发布门禁 risk-hotspots.md ← 风险热点 plans/<plan-name>/ README.md ← plan 范围与阅读路径 roadmap.md ← 进度地图 implementation-status.md ← 实施交接 open-questions.md ← 未决问题 topics/ ← 方案图谱 decisions/ ← 稳定决策 history/ ← 历史证据 ideas/ inbox.md ← 灵感收件箱

发现顺序:从哪里开始读

plan-tree 按以下优先级寻找规划树入口:

1

用户明确指定路径

用那个路径,最高优先级。

2

docs/plantree/README.md 存在

使用它作为入口——这是默认位置。

3

项目有其他活跃规划树

保留它,评估是否需要迁移——不要强行替换。

4

都没有

引导创建 docs/plantree/,从零开始建立规划树。

代码 ↔ 解读

SKILL.md 默认文件系统 - docs/plantree/README.md: registry, authority order, baseline link, active plans table, and how to read the tree. - docs/plantree/baseline/: project-wide context such as module map, runtime flows, state/storage boundaries, test/release gates, and risk hotspots. - docs/plantree/plans/<plan-name>/: specific plan roots with roadmap/status, topics, decisions, open questions, and optional history. - docs/plantree/ideas/inbox.md: low-commitment idea inbox.
逐行解读
docs/plantree/README.md:注册表——权威顺序、基线链接、活跃 plans 表、阅读方法。
docs/plantree/baseline/:项目级上下文——模块地图、运行时流程、状态/存储边界、测试/发布门禁、风险热点。
docs/plantree/plans/<plan-name>/:具体 plan 根目录——包含 roadmap/status、topics、decisions、open questions 和可选的 history。
docs/plantree/ideas/inbox.md:低承诺的灵感收件箱。

随堂测验

以下内容应该放在哪个文件?"团队决定使用 PostgreSQL 而不是 MySQL,因为需要 JSON 查询能力"
正确!"决定使用 X 而不是 Y,因为 Z"是典型的稳定决策,应该记录在 decisions/ 目录下,并包含上下文和后果。
不对。这不是进度项、不是未决问题、也不是想法——这是一个已经做出的稳定决策,应该放在 decisions/ 目录。
模块 05

精巧的设计模式

意图空间 vs 实现空间

plan-tree 是代码演化的意图空间控制平面。代码库是实现空间;规划树是意图、约束、评价和投影空间。

Aha!

大部分实现变化都应该能投影回 plan:Done、Blocked、Risk reduced、Decision changed 或 Question opened。长期没有投影回 plan 的变化,就会变成不可见的漂移。

四条铁律

铁律 1

只有 artifact 存在时才标 Done

不靠感觉,靠证据。代码提交了?测试通过了?验证完成了?没有证据就不能标 Done。

铁律 2

归档而非删除

保留推理轨迹——把旧证据移到 history/,而不是删掉。未来的你可能需要知道"当初为什么这么做"。

铁律 3

先桥接再迁移

bridge before move——不要一步到位。先注册、桥接旧规划树,再逐步迁移。

铁律 4

Open Questions ≠ 任务列表

只放未解决问题。已决问题移到 Decisions,待办事项放在 Status——不要混用。

代码 ↔ 解读

SKILL.md 编辑规则 - Inventory before editing; touch the minimum files needed. - Preserve headings, language, naming style, and chronological order. - Link active tasks to roadmap items, topics, decisions, or evidence. - Mark work Done only when the artifact exists. - Move resolved questions out of open-questions.md. - Treat ideas as non-commitments until promoted. - Archive evidence by moving stable detail behind links.
逐行解读
编辑前先盘点,只动必要的文件。
保留标题、语言、命名风格和时间顺序。
把活跃任务链接到 roadmap、topic、decision 或证据。
只有 artifact 存在时才标 Done——不靠感觉。
已解决的问题从 open-questions.md 移走。
Ideas 在被 promote 之前没有任何承诺。
归档证据——把稳定细节移到链接后面,不删推理轨迹。

随堂测验

找违规:roadmap.md 里有 30 个 Done 事项,每个都标注了完成日期但没有链接到任何 artifact。open-questions.md 里有 15 个条目,其中 8 个已经通过决策解决。违反了什么?
正确!30 个 Done 没有链接到 artifact,违反了铁律 1;8 个已决问题还在 open-questions.md 里,违反了铁律 4。两个问题同时存在。
注意,这里有两个违规:Done 事项没有 artifact 证据,以及 open-questions.md 里有已决问题。不是只违反了一条。
模块 06

当项目漂移时——维护与诊断

漂移的信号

Aha!

Plan 的漂移更容易看见——这正是 plan-tree 的价值:让不可见的东西变得可见。程序还能跑、测试还能过,但模块职责变宽、抽象不再贴合——代码漂移更隐蔽。

恢复工作流

新 session 开始时,按以下顺序恢复上下文:

1

读 docs/plantree/README.md

找到规划树入口和注册的 plan roots。

2

读相关 baseline 文件

了解项目级上下文:模块地图、运行时流程、风险热点。

3

读目标 plan root README.md

明确当前 plan 的范围和阅读路径。

4

读 implementation-status.md

获取活跃 TODO、blockers、上次验证。

5

读 roadmap.md 了解阶段上下文

当前处于哪个阶段、下一步是什么。

6

只读活跃的 topic/decision/question/history

不要全读,只读与当前任务相关的。

7

总结当前状态

当前阶段、活跃 TODO、blockers、下一步、上次验证。

最终检查清单

每次编辑或审计后,确认以下各项:

入口点、注册根、baseline 链接是否正确
新增/移动/归档的文件是否可被发现
活跃 roadmap 是否吸收了已完成的历史
Open questions 是否只包含未解决问题
链接是否仍然有效
决策和 roadmap 是否矛盾

随堂测验

你接手一个项目,打开 docs/plantree/ 发现:roadmap.md 有 200 行,其中 150 行是已完成的旧细节;implementation-status.md 最后更新是 3 周前;open-questions.md 里有条目写着"TODO: 实现用户登录"。你应该先做什么?
正确!这同时解决了三个违规:roadmap 吸收了已完成历史(归档到 history/)、open-questions 混入了任务(清理掉)、status 过期(更新)。而且遵循了"归档而非删除"和"先桥接再迁移"的原则。
注意几个原则:A 说"删掉"违反了"归档而非删除";B 不是最紧急的问题;D 违反了"先桥接再迁移"——不要一步到位重建。正确做法是归档、清理、更新,逐步修复。