Living Docs

将文档视为一个与代码保持同步的活系统，而不是一次性书写后便腐化的静态产物。该技能有一条主线——每一条知识都有且仅有一个归宿，该归宿已被索引，并且任何结构性变更都必须附带文档——以及挂靠在主线上的若干文档类型：宪法、ADR、BDR、PRD、问题、研究、架构图和语义上下文索引。

本技能与具体技术栈无关。它只控制文档的组织和维护方式，而从不规定项目使用何种技术。

核心不变式（主线）

这些不变式适用于所有文档类型，其余皆为细节。

文档优先。 在将内容发布到任何外部平台（如追踪器、Wiki）之前，先在仓库中（docs/…）编写文档主体。仓库文件是唯一事实来源；外部副本只是镜像。
一条事实一个归宿。 每个概念、决策或需求都精确地存放在一个文件中。禁止重复——通过交叉引用而非复制来共享信息。复制的文本就是等待发生的漂移。
未被索引即不存在。 每个文档都必须能从索引中访问到（在其目录中有一个 index.md 列表，并且通过项目指南链接到捆绑包根目录 docs/index.md）。不允许有孤立文件。
替代，而不是重写历史。 决策和需求是只追加的记录。当某事物发生变化时，将旧记录标记为已替代，并编写一条新记录——切勿悄无声息地修改过去。
没有文档就没有结构性变更。 新模块、文件移动、模式更改、新数据流 → 在同一项变更中更新相关文档及其图表。不允许说“我以后再补文档”。

如有疑问，请从这五条不变式中重新推导出正确的操作。下面的规则文件仅仅是这些不变式在每种文档类型上的具体应用。

格式：符合 OKF 标准

五条不变式控制着组织和生命周期；开放知识格式 (OKF) 则控制着文件格式，以确保文档库保持可移植且能被 AI 代理解析。系统中的每个文档同时也是 OKF 概念。在创作或检查格式时，请加载 okf-knowledge-format 技能（它包含了规范）。

OKF 是一个薄且可替换的依赖项——而非基础组件（存在版本风险）。 OKF 目前为 v0.1，来自单一供应商；存在向后不兼容的 v0.2 版本的可能性。上述不变式不依赖于 OKF——它们仅依赖于一小部分的前置元数据字段，因此 OKF 的断裂不会连带破坏治理层。请保持边界清晰：

Living Docs 要求（scripts/lint-docs.sh 强制执行的事实契约）：非空的 type，以及在已替代记录上的 status 和 superseded_by。这些是我们自己的；无论 OKF 如何变化，它们都存在。

继承自 OKF（格式约定）：保留的 index.md/log.md、捆绑包根目录的 okf_version、捆绑包相对链接、# References 标题（第 8 节）。如果 OKF 发生变化，只有这一行需要变动——在 okf-knowledge-format 技能中重新锁定版本即可。

以下两条规则适用于每个概念文件：

包含必需 type 字段的前置元数据。 每个非保留的 .md 文档都以一个 YAML 前置元数据块开头，其 type 字段指明了文档类型（Constitution、PRD、ADR、BDR、Issue、Context、Architecture View、Research、Reference）。建议包含 title、description、tags、timestamp 字段。Living Docs 增加了生产者键：status、supersedes、superseded_by。状态移入前置元数据——不再使用 **Status:** 作为正文行。
保留文件 + 捆绑包相对链接。 捆绑包根目录是 docs/。目录列表文件是 index.md（OKF §6，无前置元数据——但捆绑包根目录的 docs/index.md 除外，它包含 okf_version: "0.1"）。可选的文件 log.md 记录目录历史（第 7 节）。使用以 / 开头的捆绑包相对路径进行交叉链接（/adr/0007-slug.md）；在 # References 标题下列出来源（第 8 节），每个条目按照 rules/citation-conventions.md 的格式——ABNT NBR 6023 结构，始终包含链接，连接性标签使用项目文档语言（默认为英文：Available at: <URL>. Accessed on: <date>），具体参考 rules/doc-language.md。

文档链

每次变更都遵循此链条，从基础事实来源一直延伸到代码：

flowchart LR
  C[constitution] --> P[PRD]
  P --> A[ADR]
  P --> B[BDR]
  A --> I[issues]
  B --> I
  I --> K[code]

工件	作用
constitution	基础事实来源：产品是什么、核心数据模型、不可协商的事项。所有其他文档都位于其下。
PRD	系统必须做什么以及为什么——功能/产品需求规格说明。
ADR	系统的结构如何——架构/实现决策及其理由。
BDR	系统必须可观察地做什么——输入、输出、副作用、Given/When/Then 场景——以及每个场景如何测试（测试设计矩阵；“如何测试”的唯一归宿，一个执行问题链接到它）。
issues	执行切片——可追溯到 ADR/BDR 的离散工作单元。
code	实现——上述所有行为、结构和接口的具体实现。

何时调用

为项目搭建文档体系（创建 docs/ 结构、文档索引、ADR/issue/BDR/constitution 目录）。
Living docs 首次在项目中运行（项目指南中没有 ## Living Docs 块）→ 询问强制模式问题并持久化答案 → 参见强制模式。
在现有/老项目（棕地项目）中采用 living-docs（决策已做出但未记录）→ 遵循过程 → 在现有项目中采用 living docs：盘存决策，在记录任何 ADR 之前与用户确认每一条，绝不单独通过推理回填。
编写或编辑 ADR（架构/实现决策）→ 加载 rules/adr-conventions.md + templates/adr.md。
编写或编辑 PRD（产品/功能需求规格说明）→ 加载 rules/prd-conventions.md + templates/prd.md。
编写或编辑 BDR（可观察行为——输入、输出、Given/When/Then 场景，以及测试设计矩阵）→ 加载 rules/bdr-conventions.md + templates/bdr.md。测试策略决策（非默认级别/技术、基准偏差）是带有 tags: [testing] 的 ADR，而不是新的记录类型（没有“TDR”）。
指定非功能需求（性能、可用性、安全性、规模）→ 绑定到 PRD 中工具的质量属性场景（rules/prd-conventions.md 规则 9 + templates/prd.md）；决策和适应度函数放在 ADR 中。不是新的文档类型。
建立或修改宪法（基础范围、数据模型、不可协商事项）→ 加载 rules/constitution-conventions.md + templates/constitution.md。
创建或编辑 issue/票证 → 加载 rules/issue-workflow.md + templates/issue.md。
记录研究（技术评估、外部权衡）→ 加载 research-artifacts 技能。该技能拥有 OKF 研究笔记格式（每个笔记一个文件，无需按研究创建子文件夹）、来源纪律，以及研究→决策→问题的可追溯链，并在此处链接回 ADR/BDR/issue 工件。与 deep-research 技能配合使用。
绘制或更新架构图、数据流图或工具调用图 → 加载 rules/architecture-diagrams.md + templates/architecture-index.md。
定义文档中使用的术语或缩写 → 将其添加到词汇表（docs/context/glossary.md），每个术语一个归宿 → 加载 rules/glossary-conventions.md + templates/glossary.md。
文档过大或关注点混杂 → 拆分为语义索引 → 加载 rules/semantic-index.md + templates/context-index.md。
在任何结构性变更后强制执行无漂移维护规则 → 加载 rules/maintenance-invariant.md。
创作或检查任何文档的 OKF 格式（前置元数据 type、保留的 index.md/log.md、捆绑包相对链接、# References）→ 加载 okf-knowledge-format 技能。
决定文档使用的语言（默认为英文；用户可以在会话开始覆盖并锁定）→ 加载 rules/doc-language.md。

文档映射

类型	存放位置	用途	可变性
项目指南	`CLAUDE.md` / `README.md` (根目录)	入口点：范围、技术栈、文档索引、强制工作流	活跃——自由编辑
宪法	`docs/constitution.md`	基础事实来源：产品范围、数据模型、不可协商事项	批准后仅追加（修订日志）
上下文索引	`docs/context/index.md` + 分组文件	领域和模块词汇，按语义分组	活跃——自由编辑
词汇表	`docs/context/glossary.md`	术语和缩写定义一次，使用文档语言（缩写原样保留）	活跃——自由编辑
架构	`docs/architecture.md` 或 `docs/architecture/` + 索引	动态 Mermaid 图：结构、数据模型、流程、工具调用	活跃——必须与代码匹配
ADR	`docs/adr/NNNN-slug.md`	一个架构/实现决策	仅追加（替代）
BDR	`docs/bdr/NNNN-slug.md`	一个可观察行为决策	仅追加（替代或修改）
PRD	`docs/prd/NNNN-slug.md`	一个功能/产品需求规格说明	接受后仅追加
Issue	`docs/issues/NNNN-slug.md`	追踪器镜像（正文），每张票证一个	正文可编辑；发布的副本跟随
研究	`docs/research/NNNN-<slug>.md`（单文件，无子文件夹；序号开头，日期在 `timestamp` 前置元数据中；以 `# References` 结尾）	带有来源的外部证据	仅追加（证据带有日期）

每个目录携带自己的 index.md 列表（OKF §6，无前置元数据）。项目指南中的“文档索引”链接到捆绑包根目录 docs/index.md。有关索引契约，请参见 rules/semantic-index.md。

过程

在新项目中设置 living docs

询问强制模式问题（参见强制模式 → 首次运行问题），优先于其他一切，因为尚未持久化任何偏好。将答案记录到项目指南的 ## Living Docs 块中；如果用户没有偏好，默认为 strict。
创建项目指南（CLAUDE.md 或等效文件），包含文档索引部分和维护规则部分（复制 rules/maintenance-invariant.md 的措辞）。使用 templates/claude-hard-rules.md 作为项目指南硬规则部分的起点——它已经包含 ## Living Docs 强制块；在提交前填写占位符。
创建 docs/ 以及项目所需的目录（adr/、bdr/、issues/、prd/、research/、context/）。根据 templates/constitution.md 植入 docs/constitution.md。添加捆绑包根目录 docs/index.md（包含 okf_version: "0.1"），并从第一天起为每个目录提供自己的 index.md 列表——即使近乎为空。
使用已有的领域词汇植入上下文索引（docs/context/index.md），使用文档已假设的术语和缩写植入词汇表（docs/context/glossary.md）（rules/glossary-conventions.md）。随着概念被命名，两者同步增长。
使用系统已有的高级别 Mermaid 视图植入架构文档（docs/architecture.md）。一旦文档增长，升级为 docs/architecture/ 目录 + 索引（rules/architecture-diagrams.md）。
将已做出的决策记录为 ADR，以免重新争论——但在记录前与用户确认每条决策（参见在现有项目中采用 living docs，步骤 3–5）；绝不单独通过推理回填 ADR。

在现有项目（棕地项目）中采用 living docs

现有代码库已经包含了从未被书面记录下来的决策。这里的失败模式是 AI 代理通过推理回填 ADR 并将其呈现为最终确定的——记录用户从未被要求确认的决策。因此，采用是一个启发过程，而不是转录过程。

询问强制模式问题（首次运行）并持久化 ## Living Docs 块，与新项目完全相同。
搭建框架而不做决定。 创建 docs/ + 每个目录的 index.md、捆绑包根目录 docs/index.md，并根据代码、README 以及代理指南（CLAUDE.md / AGENTS.md） 中已有的词汇植入词汇表/上下文索引。这是机械性的操作——此处不做任何决定。
首先阅读现有上下文，然后盘点决策——作为候选，而非记录。 收集项目已有的内容：代码本身，加上 README、代理指南（CLAUDE.md / AGENTS.md）、包清单以及任何设计笔记或注释。据此，生成项目似乎体现的承载决策列表（技术栈、边界、数据模型、关键权衡）。尚未编写 ADR。
将清单呈现给用户并逐一确认。 对于每个候选决策，陈述推断出的决策及其似乎排除的替代方案，并要求用户确认、更正或丢弃它——对承载性决策进行深入追问（如果安装了 grill-me）。用户拥有决策权；AI 代理仅呈现代码所暗示的内容。
仅将确认的决策记录为 ADR。 这些是原始记录——它们不替代任何内容。捕获选定的方案以及用户确认的已拒绝的替代方案。用户丢弃的候选决策，或其原因无人知晓的决策，不会被发明为 ADR。
使用系统已有的高级别 Mermaid 视图植入架构文档（rules/architecture-diagrams.md），然后恢复下面的维护循环。

维护 living docs（每次任务）

编码前： 从项目指南读取 ## Living Docs 强制模式（如果该块不存在，这是首次运行——询问首次运行问题并持久化答案）。然后读取相关的宪法、ADR、BDR 以及上下文索引。
根据文档编程。 将当前任务的目标映射到 PRD、BDR、ADR 或 issue，并确保理解任何相关的架构图。
实施。 编写代码，遵守文档中指定的接口和行为。
更新文档。 如果结构性变更（新模块、模式变更、新流程、新决策）发生，在同一提交中更新相关文档和图表。执行维护不变式（rules/maintenance-invariant.md）。
链接。 确保新文档可从其目录索引和根索引访问。
如有疑问，重新读取不变式。

强制模式

首次运行问题

在首次加载此技能的项目中，在开始搭建或记录之前，AI 代理必须询问此问题（精确措辞）并持久化答案。如果用户没有明确偏好，默认为 strict。

“您希望 Living Docs 如何在此项目中强制执行文档纪律？回答：strict（AI 代理必须在实施任何结构性变更之前编写文档，并拒绝未附带 documentation 的变更）、prompt（AI 代理会提示，但如果用户坚持可以继续）、或 lazy（不强制——文档是可选的；用户主动请求时才编写）。

如果用户没有提供明确指示，默认使用 strict。

将此问题重复使用于每个新项目。一旦选择，## Living Docs 块已存在于项目指南中，则不再次询问。

强制执行规则

当项目使用 strict 模式时：

在任何结构性变更（新模块、模式变更、新流程、架构更改、数据模型更改）之前，加载并遵循相关的规则和模板。
如果用户要求进行结构性变更而未附带文档，AI 代理必须拒绝此变更，明确指出 strict 模式要求先提供文档。
如果用户提出“请稍后添加文档”，AI 代理必须坚持要求现在编写。
在 prompt 模式下：AI 代理会提示并要求文档，但如果用户明确否决则继续。
在 lazy 模式下：除非用户要求，否则不主动提供文档建议。

规则文件索引

文件	内容
`rules/adr-conventions.md`	ADR 格式、生命周期和替代规则
`rules/bdr-conventions.md`	BDR 格式、边界和测试设计矩阵
`rules/prd-conventions.md`	PRD 结构、质量属性场景和非功能需求
`rules/constitution-conventions.md`	宪法的范围、不可协商性和修改流程
`rules/architecture-diagrams.md`	Mermaid 图惯例、更新和索引规则
`rules/glossary-conventions.md`	词汇表结构、条目格式和更新规则
`rules/issue-workflow.md`	Issue 创建、更新和链接到决策
`rules/semantic-index.md`	大文档和关注点混杂的拆分规则
`rules/maintenance-invariant.md`	无漂移维护规则（用于项目指南）
`rules/doc-language.md`	文档语言选择策略和默认值
`rules/citation-conventions.md`	ABNT NBR 6023 引用格式规则

模板索引

文件	用途
`templates/claude-hard-rules.md`	项目指南 `CLAUDE.md` 的起点
`templates/adr.md`	新的 ADR 文档
`templates/bdr.md`	新的 BDR 文档
`templates/prd.md`	新的 PRD 文档
`templates/constitution.md`	新项目或修正案的宪法
`templates/issue.md`	新的 Issue/票证
`templates/architecture-index.md`	架构目录的 `index.md` 列表
`templates/glossary.md`	词汇表文件
`templates/context-index.md`	语义上下文索引

依赖项

okf-knowledge-format: OKF v0.1 格式约定。加载以检查或创作文档格式。
research-artifacts: 研究笔记格式和来源纪律。在研究环节加载。
deep-research: 用于深度研究迭代的工具。与研究工件配对使用。
grill-me（可选）：候选决策的深入追问提示。在棕地采用步骤 4 中加载。

上述依赖项不带有本技能，但会在相关调用点显式加载。

Living Docs — 活文档技能