doc-chain skill：一站式控制 AI 变更边界的文档依赖网络

doc-chain：一站式控制 AI 变更边界的文档依赖网络

让AI写项目文档或代码时，这几个场景你多半都撞见过：

• 术语漂移
  ：PRD里叫“用户”，技术方案里成了“客户”，代码里又写成“member”。

• 改A忘B
  ：PRD加了新状态，技术方案跟上了，测试用例却还在用老状态值。

• 越界发挥
  ：让AI补个接口字段，它顺手改了响应结构、换了错误码格式。

• 代码走样
  ：技术方案写得清清楚楚，代码实现却漏了权限校验、多了未定义字段。

说穿了，问题只有一个：

。它不清楚自己的修改会影响哪些下游文档，也不清楚代码实现不能超出文档定义的范围。

doc-chain 的解法很直接：

。文档是项目的唯一事实来源，代码是文档的镜像实现。从文档生成到代码落地，边界控制贯穿全程。

1. 核心机制（1 分钟看懂）

doc-chain 只做两件事：

文档之间的依赖关系长这样：

PRD-顶层定义│┌─────────────────┼─────────────────┐↓ ↓ ↓ 交互-顶层定义UI-顶层定义技术-顶层定义│ │ │└─────────────────┼─────────────────┘↓PRD-订单模块│┌─────────────────┼─────────────────┐↓ ↓ ↓ 交互-订单流程UI-订单页面技术-订单服务│ │ │└─────────────────┘ ↓ 测试-订单模块 ↑ │ 代码实现 & 审计

三条边界控制规则，简单粗暴：

规则	场景	AI 必须做的事
下游不得超出上游	写技术方案时想新增接口	先确认该功能在 PRD 里有定义，没有就停。
上游变更必须同步下游	PRD 改了状态机定义	扫描所有下游文档，列出影响范围，询问是否同步。
代码不得偏离文档	按技术方案写完代码	逐项审计：接口路径、字段名、类型、错误码、权限规则。

任何一条被触发，AI 必须暂停并询问你，而不是擅自继续。

2. 实战用法（直接抄作业）

doc-chain 是一个 Kimi Code CLI Skill。装好后，核心就三种用法：

用法 A：从 0 到 1，文档+代码一站式落地

直接复制：

AI 的执行路径：

1. 生成 PRD-顶层定义.md，头部写入 upstream-document 依赖表。
2. 按依赖顺序产出模块文档：PRD-订单模块 → 交互-订单流程 → UI-订单页面 → 技术-订单服务。
3. 每份文档头部声明实际加载的上游来源。
4. 按技术方案实现代码。
5. 启动只读 subagent，执行代码-文档一致性审计，产出审计报告。

用法 B：文档已有，一站式补代码并校验

直接复制：

AI 的执行路径：

1. 读取技术方案文档和上游 PRD 文档。
2. 按文档实现代码。
3. 代码变更触发阶段 5 审计。
4. 产出《文档-代码一致性审计报告》，标注差异项和修正建议。

用法 C：需求变更，一站式同步文档+代码

直接复制：

AI 的执行路径：

1. 暂停上游修改，先分层扫描下游。
2. 列出影响清单（交互状态机、UI 语义色、技术表结构、测试用例、代码枚举）。
3. 询问确认。
4. 级联更新所有下游文档。
5. 同步修改代码。
6. 重新执行审计。

3. 为什么不会拖慢 AI？

你可能担心一个实际的问题：“每次改文档都要扫描上下游，Token 会不会爆炸？”

实际上不会。doc-chain 的触发策略很克制：

1. 非文档场景不触发
   ：你问“写个排序算法”、“解释这段代码”，doc-chain 完全不加载。

2. 增量审计
   ：修改模式下只加载变更 diff + 受影响章节，不读全文。

3. 脚本兜底
   ：编号连续性、引用有效性、格式一致性等机械检查由 doc-audit.py 执行，不走模型。

4. 代码审计独立
   ：由只读 subagent 执行，主会话不自己审自己。

边界控制是轻量的——只在越界时出声，平时不碍事。

4. 命名体系：模板和产出必须分开

doc-chain 对 skill 内部文件和项目产出做了严格的命名隔离：

层级	Skill 内部（模板）	项目产出（事实来源）
顶层定义	references/top-level/prd-top-level-template.md	PRD-顶层定义.md
模块文档	references/steps/prd-step.md	PRD-v1-订单模块.md

关键区别在这里：

• 带 -template 后缀的：Skill 内部参考文件，只供 AI 阅读，禁止复制到项目。
• 项目产出的：填充了实际内容的文档，是下游文档和代码的唯一合法来源。

5. 避坑指南

1. 不要跳过顶层定义
   
   错误示范：“直接写订单模块的 PRD”。
   正确做法：“先检查 PRD-顶层定义 是否存在，没有就先生成”。
   没有顶层定义约束，模块文档的编号、术语、状态值会在不同模块间打架。

2. 不要脑补需求
   
   用户说“加个功能”但没说清楚边界 → AI 必须先列 gap 分析清单 → 用户确认后再输出。doc-chain 强制这个流程。

3. 不要绕过上游缺陷
   
   写技术方案时发现 PRD 状态机有矛盾 → 停下来，先回改 PRD → 同步下游 → 再继续。禁止在下游私自“适配”。

4. 代码必须审计
   
   技术方案再完美，代码也可能走样。阶段 5 的代码落地验证不是可选项。字段命名风格差异（snake_case vs camelCase）不算不一致，但业务含义必须一致。

5. 编号不回收
   
   删除 F005 后编号留空，后续从 F006 继续。复用编号会导致上下游引用错乱。

总结

doc-chain 不增加文档工作量，它做的是在关键节点设置边界检查点，一站式覆盖从文档到代码的完整链路：

PRD 顶层定义 ──→ 模块 PRD ──→ 交互 ──→ UI ──→ 技术方案 ──→ 代码实现 ↑│ └──────────── 变更时回溯上游、同步下游 ─────────────────────────┘

项目越大、AI 会话越多、文档链路越长，这个一站式边界控制的价值就越明显。