doc-ref

用途

doc-ref 用于创建 Reference Documents（REF，参考文档）——自由格式的补充文档，用于支撑 BRD 或 ADR，但不参与正式的可追溯性链条。REF 文档提供上下文（概览、摘要、指南），不携带元素 ID、累积标签、就绪评分或质量门禁。

层级：横切工具——REF 文档仅限 BRD 和 ADR 两种父类型。

适用于以下补充材料：

不适用于：任何应参与可追溯性的内容；核心工件（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,}:.+$。

确定父类型——业务上下文 → BRD-REF；架构上下文 → ADR-REF。
分配下一个编号——ls docs/01_BRD/*-REF-* 2>/dev/null（或 05_ADR）并取下一个可用的 NN。
基于父模板起草，裁剪至 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）开始，只保留四个必备章节，去掉可追溯性脚手架。
将文件放入父类型目录，并使用正确的 H1。

可选：Related Documents（鼓励交叉引用）以及参考材料所需的任何内容章节。

仅做阻塞性检查：H1 匹配 {TYPE}-REF-NN: Title；Document Control、Revision History 和 Introduction 章节存在。豁免（不检查）：累积标签、完整可追溯性、质量门禁、就绪评分——REF 文档不参与该链条。不适用任何元素 ID。