mcpField
D
doc-brd

doc-brd

github.com/vladm3105文档处理17130 次安装1 天前更新
代码仓库

关于 doc-brd

doc-brd 是用于编写业务需求文档（BRD）的技能，适用于新项目或功能的业务需求定义。它按模板组织目标、范围、利益相关者、成功标准及架构决策主题，并提供文档编号、追溯和验证规则。

主要功能

  1. 01区分平台型与功能型 BRD
  2. 02按模板组织需求文档
  3. 03梳理架构决策主题与备选方案
  4. 04管理文档编号、标签和索引
  5. 05检查结构、追溯关系与就绪门槛

适用场景

  1. 01启动项目或功能并定义业务需求
  2. 02记录战略目标、范围和成功标准
  3. 03将实现计划转写为业务语言需求

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/vladm3105/aidoc-flow-framework --skill doc-brd

安装后在 Claude Code 中输入/doc-brd确认已加载。

详细介绍

doc-brd

用途

创建一份业务需求文档（BRD）——SDD 流程的第 1 层。 BRD 使用业务语言记录业务目标、利益相关方、范围和成功标准， 不涉及任何产品或技术细节。

层级：1（入口，无上游）。 下游：PRD → EARS → BDD → ADR → SPEC → TDD → IPLAN → Code。

一次 MVP 迭代包含 5–15 项重点需求，分布在所需数量的 BRD 文档中：单份 BRD SHOULD 最多包含 5 项功能需求（GD-14），因此一个周期至少需要 ceil(N/5) 份文档——这是下限，不是上限。超过五项后，开始编写 BRD-02。新功能也应创建新的 BRD。仅在确实存在硬性前置条件时使用 @depends: BRD-NN；因前一份文档达到上限而创建的文档属于同级文档，应记录在 BRD-00 索引中。

使用时机

在以下情况使用 doc-brd：

  • 启动新项目或功能并定义业务需求时。
  • 记录战略一致性、市场背景和成功标准时。
  • 将实施计划转换为业务语言的需求时。

若要根据参考文档、提示词或 IPLAN 端到端生成文档，请使用 ../doc-brd-autopilot/SKILL.md。若要创建新项目骨架，请先运行 ../project-init/SKILL.md。

前置条件

BRD 是入口，因此无需验证上游工件。编写之前，请阅读：

  1. 模板（事实来源）： ${CLAUDE_PLUGIN_ROOT}/framework/layers/01_BRD/BRD-TEMPLATE.yaml
  2. 层级 README： ${CLAUDE_PLUGIN_ROOT}/framework/layers/01_BRD/README.md
  3. ID 与标签标准： ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md
  4. 编写风格： ${CLAUDE_PLUGIN_ROOT}/framework/governance/AUTHORING_STYLE.md

确认不存在 ID 冲突：ls docs/01_BRD/。切勿编造 BRD-XXX 之类的占位符，也不要引用不存在的文档。

层级指南

平台型 BRD 与功能型 BRD（先做判断）
信号类型
定义基础设施、技术栈或跨领域关注点平台型
其他 BRD 将依赖其架构选择平台型
描述一项面向用户的工作流／功能功能型
基于现有平台型 BRD 已确立的能力构建功能型
  • 平台型 BRD — 文件名为 BRD-NN_platform_{slug}；在 PRD 之前创建 ADR，以验证架构选择；§8（架构决策主题）填写下游 BRD 将依赖的已选类别。
  • 功能型 BRD — 文件名为 BRD-NN_{feature_slug}；遵循标准层级流程（BRD → PRD → EARS → BDD → ADR）；§8 引用平台型 BRD 已采纳的主题，而非引入新的架构决策。
必需结构（16 个章节）

document_control 为第 1 节（项目名称、版本、日期 YYYY-MM-DD、 所有者、编写者、状态、修订历史表）。然后依次为：

  1. 执行摘要（可选——派生内容；通过 section_toggles 切换）·
  2. 引言 · 4. 业务目标 · 5. 项目范围 · 6. 利益相关方 ·
  3. 功能需求 · 8. 架构决策主题（adr_topics）·
  4. 质量期望 · 10. 约束与假设 ·
  5. 验收标准与成功验证 · 12. 业务风险管理 · 13. 审批 ·
  6. 可追溯性 · 15. 术语表 ·
  7. 种子处置（seed_disposition——可选，_required: false；种子→SDD 吸收台账，GD-08 / SEED_CONTRACT.md）。

模板还定义了与编号章节并列的两个结构块：图表注册表（diagrams:）和生命周期引用附录（appendix:）——必需的结构请参阅相应模板键。章节编号和章节标识符取自模板自身的编号及顶层 YAML 键；模板是事实来源，本技能的列表仅用于导航，并非另一套定义。

各章节内容及 cross_section_rules 请参阅 BRD-TEMPLATE.yaml。

第 8 节 — 架构决策主题（必需）

确定需要决策的架构主题，并针对 7 个类别进行以成本为重点、基于备选方案的分析。不要引用 ADR 编号——ADR 尚不存在。

#类别不适用的情况
1基础设施纯数据／分析项目
2数据架构没有持久化数据
3集成独立系统
4安全内部工具，且不涉及敏感数据
5可观测性仅限 MVP／原型
6AI／ML不包含 AI／ML 组件
7技术选型使用现有技术栈

每个 Selected 主题都带有一个 BRD.NN.08.xxxx 元素 ID，并包括状态、业务驱动因素、业务约束、一个备选方案概览表（含成本估算）、一个云服务提供商对比（GCP/Azure/AWS）、推荐的选型，以及该选型所隐含的 PRD 需求。分层职责：BRD §8 = 是什么、为什么、成本多少；PRD = 如何评估；ADR = 决策。

元素 ID 和标签
  • 元素 ID：BRD.{doc_id}.{section_id}.{hash}。请勿在此提示中计算哈希——调用生成器：python -m sdd_doc_lint.rehash --compute --doc-id NN --section-id SS --title T --description D（如发生冲突，使用 --length 8）。规范依据：framework/governance/ID_NAMING_STANDARDS.md；请勿在此重述算法。
  • 第 1 层不带任何 @ 上游标签；下游层为其添加标签（@brd: BRD.01.06.a7f3）。
  • 已移除的模式：AC-XXX、FR-XXX、BO-XXX、BC-XXX、旧版三段式 BRD.NN.xxxx。
上游来源配置

大多数 BRD 根据利益相关方输入编写——保留默认值 upstream_mode: "none"。只有当内容源自 docs/00_REF/ 文档时，才设置 upstream_mode: "ref" 并列出 upstream_ref_path（相对于 BRD 文件的路径）。

创建流程

  1. 确定类型——平台型还是功能型（见上表）。
  2. 预留 ID——下一个可用的 BRD-NN（两位数字；超过两位时不补前导零： BRD-01、BRD-99、BRD-102）。 按层独立编号（CLEANUP-PR-F 第 18 项）： 在你所在层的索引中选择下一个可用编号——上游层的编号不是你的编号 （各层文档编号按顺序独立分配；参见 framework/governance/ID_NAMING_STANDARDS.md §跨层基数）。
  3. 创建嵌套文件夹——每个 BRD 都应位于 docs/01_BRD/BRD-NN_{slug}/， 不论其大小。整体式文档：在其中创建 BRD-NN_{slug}.md；分节式文档 （>25 KB）：创建 BRD-NN.S_{section}.md，并根据 ${CLAUDE_PLUGIN_ROOT}/framework/layers/01_BRD/BRD-00_index.TEMPLATE.md 创建索引。
  4. 先填写文档控制（第 1 节），然后按照模板完成其余 14 个必需章节 以及图表注册表和附录；根据 section_toggles 切换 §2 （执行摘要）。
  5. 填写 §8（架构决策主题），涵盖 7 个类别。
  6. 配置上游模式（默认值为 none；内容来自 docs/00_REF/ 时使用 ref）。
  7. 更新 BRD 索引 docs/01_BRD/BRD-00_index.md，并将其纳入同一变更。
  8. 验证（见下文），并一并提交 BRD 和索引。

草稿模式（由 saga 驱动）

通过由 saga 驱动的自动驾驶子进程模式调用时（依据 ${CLAUDE_PLUGIN_ROOT}/framework/governance/REVIEW_SAGA.md 和 ../doc-brd-autopilot/SKILL.md 中的 saga 循环），此技能是创建→评审→修订循环中草稿阶段的入口。调用形式如下：

claude --plugin-dir "$PLUGIN_DIR" -p \
  "/aidoc-flow:doc-brd Draft BRD-<id> at <path>; use BRD-TEMPLATE.yaml + the source input at <seed-path>. Write to docs/01_BRD/BRD-<id>_<slug>/."

由于 claude -p 没有 subagent_type CLI 参数，persona 绑定（business_analyst 视角 → ${CLAUDE_PLUGIN_ROOT}/framework/governance/REVIEW_CREWS.yaml 中的 aidoc-flow:requirements-analyst Agent，以及 ../review-team/SKILL.md 中的视角到 Agent 对照表）会移入此 SKILL 的提示词。当调用简介中包含单词 Draft（不区分大小写）——表示这是由 saga 驱动的草稿阶段——按以下方式调度作者：

  1. 调度一个 Task 子 Agent，设置 subagent_type=aidoc-flow:requirements-analyst， 并以 business_analyst 视角执行（根据 REVIEW_CREWS.yaml 中 BRD 团队的定义，担任 BRD 作者）。
  2. 提供 BRD-TEMPLATE.yaml + 源输入（传入路径中的 REF / 提示词 / IPLAN 种子文件）+ 此 SKILL 的 ## Creation Process（上文）作为编写规则。
  3. 子 Agent 按照标准布局，将 BRD 写入嵌套文件夹 docs/01_BRD/BRD-<id>_<slug>/。
  4. 子 Agent 返回后，写入 saga.json 转换记录草稿完成：如果 .aidoc/review/01_BRD/<BRD-id>/saga.json 中存在 saga.json，则将 {"ts": "<now>", "from": "FANOUT_STARTED", "to": "BRANCH_COMPLETED", "scope": "branch:business_analyst"} 追加到 transitions[]。（如果不存在 saga.json，则这是独立调用—— 按照 REVIEW_SAGA.md §“FRAMEWORK_SPEC_VERSION semantics”中的 声明与实现规则，跳过 saga 写入。）

在 saga 循环之外调用时（用户直接运行 /aidoc-flow:doc-brd 来编写 BRD）， 遵循上文的 ## Creation Process，不调度 Task 子 Agent（此时用户是作者）。 两种模式并存；触发条件是简介中包含 Draft 且存在 <path> 参数。

验证

验证器说明（感知 review_mode）。 以下结构检查是确定性基线，在每种模式下都会执行。在 team 模式下，../doc-brd-audit/SKILL.md 会调度 BRD 团队（architect/business_analyst/auditor/chaos_engineer/security_engineer）进行内容质量评审；在 single_pass 模式下，审计会在一次检查中应用所有视角。无论哪种模式，此技能（作者）都不会给产物评分——只负责生成产物。

此技能是验证器（没有运行时代码）。对照 ${CLAUDE_PLUGIN_ROOT}/framework/layers/01_BRD/README.md 和 ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md 进行检查。

  • 文档控制（第 1 节）为第一节。
  • 所有必需的模板章节均存在且非空：§1、§3–§15，以及 图表注册表和附录；仅当 section_toggles 包含 §2 执行摘要时，才要求该节。 通过读取 BRD-TEMPLATE.yaml 列出各节。
  • §8 涵盖所有 7 类 ADR 主题；不引用 ADR 编号。
  • 元素 ID 符合 BRD.NN.SS.xxxx；不使用已移除的模式。
  • 已创建或更新可追溯性矩阵 / 索引；没有失效链接。
  • 图表约定：必须包含 @diagram: c4-l1 和 @diagram: dfd-l1（使用 ../charts-flow/SKILL.md）；如果存在序列图，则添加序列标签。

错误代码（严重级别均为 error）：XDOC-006 标签格式无效 · XDOC-008 内部链接失效 · XDOC-009 缺少可追溯性章节。

质量门禁（阻断性）： 继续下一步前，PRD-Ready 评分必须 ≥ 90/100。

BRD-REF 文档（通过 ../doc-ref/SKILL.md）为自由格式参考文档 — 不受就绪评分、累积标签和质量门禁的约束。

下一技能

../doc-prd/SKILL.md — PRD 引用此 BRD（@brd: BRD.NN.SS.xxxx）， 定义产品功能和 KPI，并继承 §8 中的架构主题。

适配

读取 .aidoc/profile.yaml；仅遵循此技能的可调参数 （section_toggles、glossary）。忽略未知键；如果没有配置文件，则使用 框架默认值。权威依据： ${CLAUDE_PLUGIN_ROOT}/framework/governance/ADAPTATION.md。

相关资源

  • 模板 / 编写规则：${CLAUDE_PLUGIN_ROOT}/framework/layers/01_BRD/BRD-TEMPLATE.yaml
  • 层级 README：${CLAUDE_PLUGIN_ROOT}/framework/layers/01_BRD/README.md
  • 索引模板：${CLAUDE_PLUGIN_ROOT}/framework/layers/01_BRD/BRD-00_index.TEMPLATE.md
  • ID 和标签标准：${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md
  • 质量门禁：../doc-brd-audit/SKILL.md · 修复：../doc-brd-fixer/SKILL.md
  • 生成流水线：../doc-brd-autopilot/SKILL.md

快速参考

目的定义业务需求和目标
层级1（入口点）
上游标签无
关键决策平台还是功能
必须包含§1 文档控制、§3–§15 必需章节、§8（7 个类别）、图表登记表、附录
下一步doc-prd

评论

支持 Markdown