full-stack-doc

产品文档标准（full-stack-doc v3.0）

为产品文档强制采用固定的目录和命名约定，适用于通用产品系列。可直接复制的 Markdown 模板位于 templates/。详细的文件映射和约定见 references/structure.md。

---

1. 适用场景

• 创建或初始化产品文档仓库
• 为产品系列或独立产品搭建文档目录树
• 根据产品文档标准审查或统一现有仓库
• 生成或重命名文档，使其符合命名约定
• 使 product-docs/ 内容与模板结构保持一致
• 编写或扩展 10 份根目录规划文档中的任意一份

---

2. 从这里开始

复制或编辑模板前，只加载任务所需的参考资料：

• 占位符解释和机密信息处理：references/placeholder-protocol.md
• 产品、版本、模块和交付归属：references/document-boundaries.md
• 可选的架构和产品模式：references/applicability.md
• 可复用示例身份和调整规则：references/example-profiles.md
• 以证据为依据的完成标准：references/quality-rubric.md
• 确切文件名和依赖关系图：references/structure.md
• 项目 README 的选择、证据、双语和保留规则：references/readme-template-guide.md
• Rust 通用模板和可选领域配置选择器：templates/readme/rust-profiles/README.md
• 完整架构模板、证据和配置选择：references/architecture-template-guide.md

2.1 占位符摘要

占位符	含义	示例
{{PRODUCT_NAME}}	产品／品牌名称	ExampleCommerce、ExampleMemory
{{OPEN_SOURCE_NAME}}	开源版本名称（如果采用双轨制）	ExampleCommerce-Open、ExampleMemory-Open
{{VERSION}}	版本目录名称	V1、V2
{{MODULE_NAME}}	模块简称	登录页、设备中心
{{DATE}}	日期占位符	2026-03-27
{{OWNER}}	作者／审核者姓名	张三
{{ORGANIZATION}}	组织名称	ExampleOrg
{{DOC_ROOT}}	文档根目录	product-docs/ExampleProduct

替换文件名和内容中的双大括号占位符。像 {例如：订单中心} 这样的单大括号提示是撰写示例，不是全局标记。根目录保留一个 6、 文件；原有的详细功能列表已合并到 10、功能菜单与版本规划。

2.2 调整约定

1. 在填写模板前检查目标仓库并收集已确认的事实。
2. 选择适用的章节；删除不适用的双轨制、SaaS、DDD/COLA、Agent、CLI/IM、移动端或企业示例。
3. 将丰富的示例标注为示例，但绝不能将其当作目标产品的事实。
4. 将不确定内容标记为推断、假设或待确认，并尽可能附上证据。
5. 维护此技能时保留源示例；应改进边界和标注，而不是删除详细内容。
6. 将独立架构文档命名为 *-Architecture.md 或 *-Architecture.zh_CN.md；组件／版本限定词置于 -Architecture 之前。

---

3. 文档架构

3.1 四层结构

{{PRODUCT_NAME}}/
├── 1、{{PRODUCT_NAME}}-命名与品牌说明.md          ─┐
├── 2、{{PRODUCT_NAME}}-术语表与词汇表.md          │
├── 3、{{PRODUCT_NAME}}-市场与商业分析.md          │
├── 4、{{PRODUCT_NAME}}-技术与可行性分析.md        │ Root (10) — 产品级，与版本无关
├── 5、{{PRODUCT_NAME}}-技术方案与路线.md          │
├── 6、{{PRODUCT_NAME}}-产品与版本规划.md          │
├── 7、{{PRODUCT_NAME}}-领域模型设计.md            │
├── 8、{{PRODUCT_NAME}}-Architecture.zh_CN.md      │
├── 9、{{PRODUCT_NAME}}-视觉与交互DNA规范.md       │
├── 10、{{PRODUCT_NAME}}-功能菜单与版本规划.md      ─┘
│
├── V1/                                   ─┐
│   ├── 1、{{PRODUCT_NAME}}-需求调研文档-V1.md      │
│   ├── 2、{{PRODUCT_NAME}}-需求分析文档-V1.md      │
│   ├── 3、{{PRODUCT_NAME}}-V1-Architecture.zh_CN.md│ Version (7) — 版本级实施文档
│   ├── 4、{{PRODUCT_NAME}}-功能与界面规划-V1.md    │
│   ├── 5、{{PRODUCT_NAME}}-PRD文档-V1.md           │
│   ├── 6、{{PRODUCT_NAME}}-功能菜单与版本规划-V1.md│
│   ├── 7、{{PRODUCT_NAME}}-UI设计说明-V1.md        │
│   │                                     ─┘
│   ├── 1、{模块A}/                       ─┐
│   │   ├── {{PRODUCT_NAME}}-{模块A}-PRD-V1.md      │ Module (3) — 可选，按模块
│   │   ├── {{PRODUCT_NAME}}-{模块A}-Stitch设计提示词.md │
│   │   └── {{PRODUCT_NAME}}-{模块A}-UI设计说明-V1.md    ─┘
│   └── ...
│
├── 其他/                                 ─┐
│   ├── 1、技术细分模板.md                │
│   ├── 2、功能提测模板.md                │ Delivery (5) — 可选，研发交付
│   ├── 3、测试结果模板.md                │
│   ├── 4、上线通知模板.md                │
│   └── 5、项目运维模板.md                ─┘
│
├── 技术调研/                             ── 技术调研、协议分析（版本无关）
└── assets/                               ── 图片、附件等

3.2 范围摘要

范围	数量	模板	命名模式
根目录	10	templates/root/	{{MODULE_INDEX}}、{{PRODUCT_NAME}}-{文档名}.md
版本（{{VERSION}}/）	7	templates/version/	{{MODULE_INDEX}}、{{PRODUCT_NAME}}-{文档名}-{{VERSION}}.md
模块（可选）	每个模块 3 份	templates/module/	{{PRODUCT_NAME}}-{{MODULE_NAME}}-{类型}-{{VERSION}}.md
交付（可选）	5	templates/delivery/	视上下文而定

3.3 根目录 10 份文档——编写链

文档间存在严格的上下游依赖关系，编写时应按顺序递进：

flowchart LR
    D1["1、命名与品牌"] --> D2["2、术语表"]
    D2 --> D3["3、市场分析"]
    D3 --> D4["4、可行性分析"]
    D4 --> D5["5、技术方案"]
    D5 --> D6["6、版本规划"]
    D6 --> D7["7、领域模型"]
    D7 --> D8["8、系统架构"]
    D8 --> D9["9、视觉DNA"]
    D6 --> D10["10、功能菜单"]
    D9 --> D10

序号	文档	关键输入	关键输出	对标 Mermaid 类型
1	命名与品牌说明	产品愿景	品牌口径、边界	graph LR（品牌关系）
2	术语表与词汇表	Doc 1 品牌定位	统一语言	无（纯表格）
3	市场与商业分析	Doc 1 定位 + 外部数据	TAM/SAM/SOM、竞品、定价	quadrantChart / funnel
4	技术与可行性分析	Doc 3 机会 + Doc 5 初步选型	可行性结论、风险	flowchart / sequenceDiagram
5	技术方案与路线	Doc 4 结论	技术栈、ADR、里程碑	flowchart / gantt
6	产品与版本规划	Doc 3 商业 + Doc 5 路线	版本矩阵、定价、发布策略	graph / timeline
7	领域模型设计	Doc 2 术语 + Doc 6 功能边界	限界上下文、聚合、事件	classDiagram / graph TB
8	系统架构设计	Doc 5 技术栈 + Doc 7 领域	分层、数据流、部署	flowchart / sequenceDiagram
9	视觉与交互 DNA 规范	Doc 1 品牌气质	色彩、字体、组件、动效	flowchart（页面骨架）
10	功能菜单与版本规划	Doc 6 + Doc 8 + Doc 9	导航、路由、功能清单、优先级	mindmap / pie / flowchart

---

4. 脚手架搭建工作流

步骤 1 — 根目录文档

将 templates/root/ 中的全部 10 个文件复制到项目根目录。将每个文件重命名，并替换 {{PRODUCT_NAME}}：

# Example: ExampleCommerce
for f in templates/root/*.md; do
  name=$(basename "$f" | sed 's/{{PRODUCT_NAME}}/ExampleCommerce/g')
  cp "$f" "product-docs/ExampleCommerce/$name"
done

步骤 2 — 版本文档

创建 {{VERSION}}/（例如 V1/）。从 templates/version/ 复制 7 个文件。在文件名和内容中替换 {{PRODUCT_NAME}} 和 {{VERSION}}。

步骤 3 — 模块文档（可选）

为每个功能模块创建 {{VERSION}}/{{MODULE_INDEX}}、{{MODULE_NAME}}/。从 templates/module/ 复制 3 个文件。替换 {{PRODUCT_NAME}}、{{MODULE_NAME}} 和 {{VERSION}}。

示例（ExampleCommerce V1 商品采集）：

V1/1、商品采集/
├── ExampleCommerce-商品采集-PRD-V1.md
├── ExampleCommerce-商品采集-Stitch设计提示词.md
└── ExampleCommerce-商品采集-UI设计说明-V1.md

步骤 4 — 交付文档（可选）

将 templates/delivery/ 复制到 其他/ 或专用交付文件夹。替换 {{PRODUCT_NAME}} 和日期。

步骤 5 — 特殊目录

创建 技术调研/ 存放技术调研资料，创建 其他/ 存放非标准文档。demo/、assets/、.stitch/ 等目录保持不变。

步骤 6 — 验证

运行验证清单（第 7 节）。

---

5. 质量标准

5.1 以证据为导向的质量门槛

行数、表格数和图表数是诊断指标，而非验收门槛。只要文档能提供可追溯的证据，支持下一项决策或交付步骤，即视为完整。

维度	要求结果
范围	明确说明受众、所有权、纳入与排除范围，以及上下游边界
证据	外部主张注明来源、日期和置信度；有关代码库的主张应指向文件、API、测试或运行时证据
决策	记录备选方案、决策、理由、约束和撤销条件
一致性	各文档中的术语、版本、时间线、菜单名称、API、状态和验收标准保持一致
交付	每项需求都有可验证的验收标准；适用时，架构/UI 部分涵盖故障、空状态、加载、权限和回滚状态
真实性	能区分已确认事实、推断、假设和待定事项

使用 references/quality-rubric.md 进行评分。仅在图表和表格能显著提升关系或比较的清晰度时才添加。

5.2 通用文档结构

每份根目录文档必须包含以下标准结构：

文档头部：

# {{PRODUCT_NAME}} 文档标题

> **文档说明**：一句话说明文档用途与范围。
>
> **版本**：V1.0.0
> **最后更新**：{{DATE}}

文档尾部：

---

**文档版本**：V1.0.0
**创建日期**：{{DATE}}
**最后更新**：{{DATE}}
**文档状态**：✅ 待评审

5.3 格式规范

元素	规范
章节编号	## N. 顶级，### N.M 子级，层级不超过 3 层
表格对齐	使用 :--- 左对齐
可行性评级	✅ 高可行 / ⚠️ 中可行 / 🔴 低可行
优先级	P0（必须）/ P1（重要）/ P2（期望）/ P3（可选）
版本标签	🆓 免费 / 👤 个人 / 👥 专业 / 🏢 企业
状态标记	✅ 已实现 / 🔧 开发中 / ⏳ 计划中 / ❌ 不实现
Mermaid	每图前后空行；diagram 类型应匹配内容（见 3.3 对标列）
代码块	标注语言（typescript/go/bash/yaml/sql）
中英混排	中文与英文/数字间加空格：OpenAI 模型

5.4 交叉引用规则

• Doc 3 关联文档必须链接 Doc 1（品牌边界）和 Doc 5（技术可行性）
• Doc 5 甘特图日期必须与 Doc 6 版本里程碑、Doc 10 发布节奏一致
• Doc 7 聚合名称必须在 Doc 2 术语表中有定义
• Doc 8 分层名称必须与 Doc 5 技术选型对应
• Doc 10 功能列表的版本标注必须与 Doc 6 版本矩阵一致

---

6. 注意事项

• 版本文件夹中的序号 1–7 保留给 7 份标准文档。非标准文档必须使用 8+，或放入 其他/。
• 根目录有一个编号为 6、 的文件（产品与版本规划）。详细功能列表嵌入在 10、功能菜单与版本规划 中。
• 除非用户明确要求，否则不要重新整理特殊目录（demo/、assets/、.stitch/、stitch_*、实施指南/）。
• 交付模板是可选的，且不占用根目录级标准序号。
• 当产品采用开源 + 商业双轨模式（例如 ExampleCommerce-Open/ExampleCommerce）时，每条产品线都应有各自完整的 10 份文档，并相互交叉引用。

---

7. 验证清单

从技能目录运行附带的结构验证器：

python3 scripts/validate_templates.py

对于生成的独立架构文档，交付前请验证文件名：

python3 scripts/validate_architecture_filenames.py \
  docs/ExamplePlatform-Architecture.md \
  docs/ExamplePlatform-Architecture.zh_CN.md

然后检查无法通过文件数量验证的语义一致性：

• 目标事实有证据支撑；示例仍标记为示例
• 根目录/版本/模块/交付职责的归属没有重复
• 已移除或调整不适用的双轨、DDD/COLA、Agent、SaaS、CLI/IM、移动端或企业版章节
• 市场、技术、版本和菜单文档中的时间线日期一致
• 术语与术语表一致；菜单、路由、API 和状态名称在 PRD/UI/架构文档中一致
• 需求具有可观察的验收标准，并在相关场景中涵盖失败/权限/空/加载状态
• 未引入已解决的密码、令牌、私有路径或私有产品/仓库名称
• 独立架构文件名符合 *-Architecture.md 或 *-Architecture.zh_CN.md

---

8. 模板清单

组别	位置	数量	主要职责
产品基线	templates/root/	10	品牌、术语、市场、技术、路线图、领域、架构、设计 DNA 和产品级 IA
版本交付	templates/version/	7	调研、分析、版本架构、范围、PRD、菜单和 UI 决策
模块详情	templates/module/	3	模块专属 PRD、设计生成提示词和 UI 规范
工程交付	templates/delivery/	5	技术拆解、测试交接/结果、发布和运维
项目入口	templates/readme/	5 + 7 个 Rust 配置文件	Java、Rust、插件和技能生态的直接使用模板、完整参考，以及可组合的 Rust 领域覆盖
架构设计	templates/architecture/	1 + 7 份配置文件	完整架构契约，以及运行时、插件、边缘、事件、AI 和控制平面配置

原有的 25 个生命周期模板有意保留了详细的可复用内容和明确标记的完整示例。README 系列新增了 4 个特定类型的模板和 1 个完整参考；Rust 模板新增了 7 份可组合的配置文件。架构系列新增了 1 个完整主模板和 7 份配置文件。不要将其中任何模板替换为空洞的简短框架。

---

9. 相关技能

• doc-coauthoring：通过访谈协作起草文档。安装命令：npx skills add full-stack-skills/document-skills --skill doc-coauthoring。
• api-doc-generator：由源码/OpenAPI 驱动的 API 文档。安装命令：npx skills add full-stack-skills/document-skills --skill api-doc-generator。

10. 完成约定

报告完成前，请说明使用了哪些模板组、移除了哪些可选模式、哪些声明仍属于假设/TBD，以及哪些验证命令已通过。对于独立架构文档输出，请报告文件名验证结果。如果无法检查目标代码库，请明确说明，不要将示例内容说成已确认事实。