doc-ref

doc-ref

用途

创建 参考文档（REF）——不参与正式可追溯链、用于补充 BRD 或 ADR 的自由格式文档。REF 文档提供背景信息（概览、摘要、指南）；不包含元素 ID、累积标签、就绪评分或质量门禁。

层级：跨领域实用工具——REF 文档仅限 BRD 和 ADR 父类型。

适用场景

使用 doc-ref 创建以下补充文档：

• BRD-REF — 项目概览、执行摘要、战略愿景、利益相关者指南。
• ADR-REF — 技术栈摘要、架构概览、基础设施指南。

不要用于：任何需要参与可追溯性的内容；核心工件（BRD/PRD/EARS/BDD/ADR/SPEC/TDD/IPLAN——请使用对应的 doc-* 技能）；或 BRD、ADR 以外的任何父类型。

行为

命名和位置

• 文件名：{TYPE}-REF-NN_{slug}.md（TYPE ∈ {BRD, ADR}）；H1： # {TYPE}-REF-NN: Title。
• NN 是长度可变的序列（2 位以上数字），每种父类型分别编号： BRD-REF-01、BRD-REF-102、ADR-REF-01 属于不同的序列。
• 文件位于父类型目录中，例如： docs/01_BRD/BRD-REF-01_project_overview.md、 docs/05_ADR/ADR-REF-01_technology_stack_summary.md。
• 正则表达式 — 文件：^(BRD|ADR)-REF-[0-9]{2,}_[a-z0-9_]+\.md$； H1：^#\s(BRD|ADR)-REF-[0-9]{2,}:.+$。

创建流程

1. 确定父类型 — 业务背景 → BRD-REF；架构背景 → ADR-REF。
2. 分配下一个编号 — 执行 ls docs/01_BRD/*-REF-* 2>/dev/null（或 05_ADR），并使用下一个可用的 NN。
3. 基于父模板起草，并精简为 REF 必需内容 — 从 ${CLAUDE_PLUGIN_ROOT}/framework/layers/01_BRD/BRD-TEMPLATE.yaml（BRD-REF）或 ${CLAUDE_PLUGIN_ROOT}/framework/layers/05_ADR/ADR-TEMPLATE.yaml（ADR-REF）开始，仅保留四个必需章节，删除可追溯性框架内容。
4. 放置文件 — 将文件放入父类型目录，并设置正确的 H1。

必需章节（4 个，必填）

1. YAML frontmatter（artifact_type: REF）。
2. 文档控制（版本、日期、作者、状态）。
3. 文档修订历史。
4. 引言（目的和范围）。

可选内容：相关文档（鼓励添加交叉引用），以及参考资料所需的任何内容章节。

验证（此技能即验证器）

仅检查阻断项：H1 是否符合 {TYPE}-REF-NN: Title；是否包含文档控制、修订历史和引言章节。豁免（不检查）：累积标签、完整可追溯性、质量门禁、就绪评分——REF 文档不参与该链。无需使用元素 ID。

相关资源

• 父模板：${CLAUDE_PLUGIN_ROOT}/framework/layers/01_BRD/BRD-TEMPLATE.yaml、 ${CLAUDE_PLUGIN_ROOT}/framework/layers/05_ADR/ADR-TEMPLATE.yaml
• 命名规范：${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md · ../doc-naming/SKILL.md
• 治理与各层规范：${CLAUDE_PLUGIN_ROOT}/framework/governance/ 以及各层的 ${CLAUDE_PLUGIN_ROOT}/framework/layers/NN_<X>/README.md
• 父技能：../doc-brd/SKILL.md · ../doc-adr/SKILL.md
• 工作流路由：../doc-flow/SKILL.md
• 图表：../charts-flow/SKILL.md