PDLC产品形状设计两大致命错误避坑指南
用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 → 实现 → 评审 → 发布。流程设计本身没有问题。
但现实情况中，feature从来不是孤立存在的。
我在aitm项目里遇到了经典场景：feature/安全层 被 feature/工具调用 依赖。修改安全层的黑名单规则，实际上会影响到工具调用的确认逻辑。然而PDLC的状态机只关注单个feature的进度，没有任何地方告诉你这两个feature之间存在关联。
结果就是我每次修改安全层，都得靠大脑硬记“这会不会影响工具调用那边”——把本该由系统记住的事情塞进人脑，这种设计不合理。
新指令：/pdlc-relate
v1.1增加了 /pdlc-relate，专门管理feature之间的关联关系。
关系类型有六种：
| 类型 | 含义 |
|---|---|
extends | 该feature是另一个的扩展 |
depends_on | 该feature依赖另一个的实现 |
supersedes | 该feature替代了另一个（另一个应归档） |
resolves | 该feature修复了另一个引入的问题 |
conflicts_with | 两个feature有已知冲突，无法同时激活 |
relates_to | 宽泛关联，不属于以上类型 |
建立关系很简单：
/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说到底就是省钱，但也不只是省钱。