PDLC 1.1：v1.0 在产物形态上犯的两个错误

几个月的 PDLC 工作实践过后，我在一个项目的 docs/ 目录中发现了这些文件：

docs/├── architecture-2025-10-03.md├── architecture-2025-11-14.md├── architecture-2025-12-01.md├── architecture-2026-01-08.md└── architecture-2026-02-19.md

五份架构文档，每份都带日期。我不知道哪份是现在的架构。

问题并非源于用户操作，而是 PDLC v1.0 的设计错误。v1.0 将每个阶段的产物统一视为 append-only 历史记录；这种逻辑适用于 PRD，却让架构总览堆积成了垃圾。

v1.1 修正了两个此类设计错误。

错误一：未区分两种本质不同的产物

着手之前，我先明确了一种分类方式：从时间维度看，产物呈现什么形状？

第一类产物记录"发生过什么"，包括 PRD、设计决策和会议纪要。每一份都是不可篡改、只能追加的历史证据。没人会修改三个月前的 PRD，让它变成"最新的"，因为这会破坏决策链。这类产物称为 ledger 型（账本）。

架构总览、团队编码规范、API 契约属于另一类产物：它们表达的是"现在是什么状态"，且"现在有效的版本"永远只有一份。维护时不另存带日期的副本，而是在原处更新。这就是 surface 型（当前状态面）产物。

由于 v1.0 未作这种区分，AI 默认会为全部产物追加日期戳。于是 /pdlc-arch 每次执行都会生成 architecture-YYYY-MM-DD.md，经过三个月便形成了上面五份文件并存的局面。

规范文档的情况更加糟糕。团队原本有一份 coding-style.md，修改一次以后变成 coding-style-v2.md，随后又出现 coding-style-v3.md。结果是所有人都放弃查看，因为该 follow 哪份无人知晓。

v1.1 采用了直接的修法：生成产物前，类型先由 AI 判断。需要在固定路径就地维护一个文件的是 surface 型；ledger 型仍为 append-only，既要加日期戳，也不允许就地修改——/pdlc-arch 仅维护 docs/ARCHITECTURE.md 这一份文件，每次都就地更新，遗留的日期文件则自动归档至 docs/archive/。

新指令：/pdlc-standard

规范文档是最典型的 surface 型产物，因此 v1.1 专门为此增加了一条指令。

/pdlc-standard 管理 docs/00_standards/ 目录中的规范文档，可执行以下操作：

add：创建新规范，并强制采用语义路径命名（coding/style、api/versioning），版本号与日期均不得出现。archive：当一份规范完全废弃时将其归档，已有引用仍保持有效。edit：文件名保持不变，就地修改现有规范，并自动记录修改时间。index：为 onboarding 或 review 输出所有当前有效规范的索引。

最关键的一条约束在提示词里是硬写的：如果 AI 在生成 coding-style-v2.md 这样带版本号的规范文件，必须中止并提示用户用 edit 子命令替代。

这项约束从源头阻止了版本号不断蔓延。

错误二：feature 彼此互不相识

PRD → 设计 → TDD → 实现 → 评审 → 发布，是 v1.0 状态机为每个 feature 设置的独立闭环。就纵向流程而言，这套设计是正确的。

然而在现实中，feature从来都不是孤立存在的。

我在 aitm 项目中遇到过一个典型场景：feature/安全层 被 feature/工具调用 依赖。改安全层的黑名单规则，实际上会影响工具调用的确认逻辑。但 PDLC 的状态机只看单个 feature 的进度，没有任何地方告诉我这两个 feature 之间有关系。

因此，每次修改安全层时，我都只能依靠记忆判断"这会不会影响工具调用那边"。本应由系统保存的信息被塞进人脑，这显然不合理。

新指令：/pdlc-relate

v1.1 新增了 /pdlc-relate，feature 之间的关系由它统一管理。

关系共分为六种类型：

建立关系十分简单：

/pdlc-relate set feature/工具调用 depends_on feature/安全层

真正关键的是另一个子命令：

/pdlc-relate impact feature/安全层

该命令会列出直接依赖此 feature 的项目、通过传递关系受到间接影响的项目，以及历史上由它替代或解决的项目。只需一个命令，就能完整展开改动的影响范围。

实现这个功能时，我做了一个不太符合直觉的选择：关系数据保存在 docs/.pdlc/ 下面的结构化文件中，而非某种专有数据库格式。原因是这些关系属于"团队的知识"，理应跟随代码共同提交、review 和合并；若保存在黑盒中，更换机器或人员后就会丢失。

两个功能共同遇到的问题

我原以为 surface 型产物迁移并不复杂，实际却更麻烦：已有项目保存了多份带日期的旧架构文件，哪份才是"最新的"，PDLC 无从判断。处理原则是不猜——/pdlc-arch 发现遗留文件时，系统会暂停并询问："我看到 architecture-2026-02-19.md，是否要将这份内容作为 ARCHITECTURE.md 的初始内容？"通过一次确认，避免自动迁移发生错误。

设计关系类型时，我也经历了一些曲折。初稿只设依赖、扩展和冲突三种关系；用真实项目试跑后发现，许多 feature 之间的联系无法表达，例如"这个 feature 修了那个 feature 的遗留问题"就不属于三类中的任何一种。最终关系扩展为六种，这已经是够用的边界，再增加就会沦为分类游戏。

当前状态

三个已经采用 v1.1 的项目分别是：aitm、一个SaaS 项目、pdlc-skills 自身。

最让人抓狂的问题，最终由 ledger/surface 分离解决——docs/ 不再是一条时间轴，而成为能够检索信息的地方。/pdlc-relate impact 每次进行跨 feature 修改时都会使用，省去了大量"这会不会影响那边"的回溯检查。

由33 个标准化阶段组成的核心结构并未变化，v1.1 只修正了产物形状和关系建模。已经使用 v1.0 的用户基本可以无感升级——除了 /pdlc-arch 下次执行时会询问是否迁移旧文件。

安装 / 升级

首次安装（需要 Claude Code）：

/claude install kanfu-panda/pdlc-skills

升级现有安装：

bash <(curl -fsSL https://raw.githubusercontent.com/kanfu-panda/pdlc-skills/main/install.sh) --upgrade

源码在 GitHub，MIT 开源。用了遇到问题，Issues 开着，我在看。

下一篇

"直接让 AI 写"会少耗一些 token；PDLC 的代价则是更吃 token，因为它细分流程，并要求步步留下产物。相应的好处，是整个过程既不跳步也不跑偏。今天有人就此问我："文档一多，token 不就烧得更凶？"

这个问题值得另写一篇讨论：究竟应该如何计算这笔 token 账（我没有精确测量过，但其中有些地方违反直觉），以及采用这套重流程时，我如何把花销降下来。归根结底，节省 token 就是省钱，却又不只是省钱。