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 的设计上——它把各个阶段产出的内容一视同仁，全部当作只允许追加的历史记录。这套逻辑在 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。到最后没人知道该遵循哪一份，干脆都不看了。

v1.1 的修复方案很直接：让 AI 在生成产物前先判断类型。ledger 型继续采取只追加策略，加日期戳、不允许就地修改；surface 型则强制就地维护一个固定路径的文件——/pdlc-arch 只维护 docs/ARCHITECTURE.md 这一份，每次更新直接修改原文件，遗留的带日期文件自动归档到 docs/archive/。

新指令：/pdlc-standard

规范文档是 surface 型里最具代表性的一类，因此 v1.1 为它单独增加了一条指令。

/pdlc-standard 专门管理 docs/00_standards/ 下的规范文件。职责非常明确：

• add：新建规范时，强制使用语义化路径命名（例如 coding/style、api/versioning），禁止包含版本号或日期。
• edit：就地修改现有规范，系统自动记录修改时间，但保持文件名不变。
• archive：当规范彻底废弃时可以归档，但已有引用不会中断。
• index：输出当前所有有效规范的索引，方便新成员加入或定期审查。

最关键的一条约束直接写死在提示词中：如果 AI 要生成像 coding-style-v2.md 这种带版本号的规范文件，必须立即中止操作，并提示用户改用 edit 子命令。这条约束从根本上杜绝了版本号泛滥的问题。

错误二：feature 之间互不相识

v1.0 的状态机里，每个 feature 是一个独立的闭环：PRD → 设计 → TDD → 实现 → 评审 → 发布。这个流程设计本身没有问题。

但现实是，功能模块从来不是孤立存在的。

我在 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/ 下的结构化文件里，而不是某种专用数据库。理由在于——这些关系属于“团队的知识”，应该随代码一起提交、审查、合并。如果存在黑盒里，换一台机器或换一个同事就丢失了。

两个功能一起踩的坑

surface 型产物的迁移，比预想中麻烦不少。已有项目里那些带日期的架构文件，PDLC 怎么知道哪份是“最新的”？答案是不猜测——/pdlc-arch 检测到遗留文件时会停下来询问你：“我看到 architecture-2026-02-19.md，要用这份作为 ARCHITECTURE.md 的初始内容吗？”一个确认步骤，避免了自动迁移可能引发的混乱。

关系类型的设计也走过一些弯路。最初的草稿里只有三种关系：依赖、扩展、冲突。用真实项目跑了一遍，发现很多联系根本描述不了——比如“这个 feature 修复了那个 feature 的遗留问题”，归类不进现有的三种。最后扩展到了六种。六种是刚好够用的边界，再多就容易变成纯粹的分类游戏了。

当前状态

v1.1 已经在三个项目上投入使用：aitm、pdlc-skills 自身、以及一个 SaaS 项目。

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 中提出，我会持续关注。

下一篇

PDLC 把流程拆解细致、步步留下产物——好处是避免跳步、防止跑偏，代价是它比“直接让 AI 写”更消耗 token。今天就有人跟我说：“文档一多，token 不就烧得更厉害？”

这个问题值得单独聊一篇文章：这笔 token 账到底该怎么算（我没有精确测量过，但有些反直觉的地方），以及在这套重流程的同时，我是如何控制花销的。节省 token 说到底就是节省成本，但它的意义远不止于此。