ln-120-reference-docs-creator

路径： 文件路径（references/、../ln-*）均相对于此技能目录。

参考文档创建器

类型： L2 Worker

此技能会创建参考文档结构（docs/reference/）和基于项目 TECH_STACK 编写的智能文档（ADR、指南、手册）。仅在技术选择有充分理由（存在非平凡的技术选型，且有替代方案）时才创建文档。

用途

创建参考文档目录结构（docs/reference/）及 README 导航页，然后根据 Context Store 中的 TECH_STACK，仅为有充分理由的技术选择生成 ADR、指南和手册。

何时使用此技能

此技能是由 ln-100-documents-pipeline 编排器调用的 L2 WORKER。

以下情况应直接使用此技能：

• 仅创建参考文档结构（docs/reference/）
• 为 ADR、指南和手册设置目录
• 不创建完整的文档结构（完整设置请使用 ln-100-documents-pipeline）

输入

来自 ln-100（通过 ln-110 Context Store）：

{
  "context_store": {
    "PROJECT_NAME": "my-project",
    "TECH_STACK": {
      "frontend": "React 18",
      "backend": "Express 4.18",
      "database": "PostgreSQL 15",
      "orm": "Prisma 5.0",
      "auth": "JWT",
      "cache": "Redis 7"
    },
    "DEPENDENCIES": [...],
    "flags": { "hasBackend": true, "hasDatabase": true, "hasFrontend": true }
  }
}

TECH_STACK 用于在阶段 2 创建智能文档。

必须阅读： 加载 references/docs_quality_contract.md 和 references/markdown_read_protocol.md。 可选规则目录：仅在需要确切的规则 ID、路径矩阵或允许的占位符例外时，加载 references/docs_quality_rules.json。

工作流

此技能遵循 4 阶段工作流：创建结构 → 创建智能文档 → 验证结构 → 验证内容。阶段 2 仅为有充分理由的技术选择创建文档。

---

阶段 1：创建结构

目标：建立参考文档目录和 README 导航页。

流程：

1.1 检查并创建目录：

• 检查 docs/reference/adrs/ 是否存在 → 若不存在则创建
• 检查 docs/reference/guides/ 是否存在 → 若不存在则创建
• 检查 docs/reference/manuals/ 是否存在 → 若不存在则创建
• 检查 docs/reference/research/ 是否存在 → 若不存在则创建
• 为每项记录日志："✓ 已创建 docs/reference/[name]/" 或 "✓ docs/reference/[name]/ 已存在"

1.2 检查并创建 README：

• 检查 docs/reference/README.md 是否存在
• 如果存在：
  • 跳过创建
  • 记录日志："✓ docs/reference/README.md 已存在，继续验证"
• 如果不存在：
  • 复制模板：ln-120-reference-docs-creator/references/templates/reference_readme_template.md → docs/reference/README.md
  • 替换占位符：
    • {{VERSION}} — "1.0.0"
    • {{DATE}} — 当前日期（YYYY-MM-DD）
    • {{ADR_LIST}} — - No ADRs yet. Add the first ADR when a nontrivial decision is accepted.
    • {{GUIDE_LIST}} — - No project guides yet. Add guides when patterns need project-specific explanation.
    • {{MANUAL_LIST}} — - No package manuals yet. Add manuals only for complex external APIs.
    • {{RESEARCH_LIST}} — - No research notes yet. Add research only when a concrete question is investigated.
  • 保留模板中的共享开篇约定和标准顶部章节
  • 记录日志："✓ 已根据模板创建 docs/reference/README.md"

1.3 输出：

docs/reference/
├── README.md         # Created or existing
├── adrs/            # Empty, ready for ADRs
├── guides/          # Empty, ready for guides
├── manuals/         # Empty, ready for manuals
└── research/        # Empty, ready for research documents

---

阶段 2：智能文档创建

目标：为有合理依据的技术选择创建 ADR、指南和手册。跳过简单或显而易见的选择。

2.1 检查上下文存储：

• 如果未提供 context_store → 跳过阶段 2，继续阶段 3
• 如果 context_store 中没有 TECH_STACK → 跳过阶段 2，继续阶段 3
• 记录："收到包含 TECH_STACK 的上下文存储：[类别数量]"

2.2 加载选择依据规则：

• 读取 references/tech_justification_rules.md
• 解析类别 → 有依据／跳过条件

2.3 分析 TECH_STACK 以创建 ADR：

对于 TECH_STACK 中的每个类别（frontend、backend、database、orm、auth、cache）：

1. 检查是否有充分依据（根据选择依据规则）：

   • frontend：如果是 React/Vue/Angular/Svelte，则有充分依据（存在多个选项）
   • backend：如果是 Express/Fastify/NestJS/Koa，则有充分依据（存在多个选项）
   • database：如果是 PostgreSQL/MySQL/MongoDB，则有充分依据（存在多个选项）
   • auth：如果是 JWT/OAuth/Session，则有充分依据（需要做出选择）
   • orm：如果是 Prisma/TypeORM/Sequelize，则有充分依据（存在多个选项）
   • cache：如果是 Redis/Memcached，则有充分依据（需要做出选择）

2. 如果选择简单，则跳过：

   • 仅使用 jQuery 的前端（无需选择框架）
   • 简单的 http server（无框架）
   • 仅用于开发的 SQLite
   • 无需身份验证
   • 仅使用原始 SQL
   • 仅使用内存缓存

3. 如果有充分依据，则创建 ADR：

   • 确定下一个 ADR 编号：adr-NNN-{category}.md
   • 使用模板：references/templates/adr_template.md
   • MCP 调研：mcp__context7__resolve-library-id(technology)
   • 填写模板：
     • 标题："ADR-NNN：{Category} 选择"
     • 背景：为什么需要做出选择
     • 决策：选定的技术及版本
     • 理由：根据调研得出的 3 个关键理由
     • 替代方案：另外 2 个选项及其优缺点
   • 保存至：docs/reference/adrs/adr-NNN-{category}.md
   • 记录："✓ 已为 {category} 创建 ADR：{technology}"

4. 如果没有充分依据，则跳过：

   • 记录："⊘ 已跳过 {category} 的 ADR：选择简单"

2.4 分析 TECH_STACK 以创建指南：

对于配置复杂的每项技术：

1. 检查是否有充分依据：

   • 配置文件超过 20 行
   • 使用自定义钩子／中间件／装饰器
   • 有 3 个或更多相关依赖项

2. 如果有充分依据，则创建指南：

   • 确定下一个指南编号：NN-{technology-slug}-patterns.md
   • 使用模板：references/templates/guide_template.md
   • MCP 调研：mcp__Ref__ref_search_documentation("{technology} patterns {current_year}")
   • 填写模板：
     • 原则：调研所得的行业标准
     • 我们的实现：项目如何使用该技术
     • 模式表：3 行「应该做／不应该做／适用时机」内容
   • 保存至：docs/reference/guides/NN-{technology}-patterns.md
   • 记录："✓ 已为 {technology} 创建指南"

3. 如果用法符合标准，则跳过：

   • 记录："⊘ 已跳过 {technology} 的指南：用法符合标准"

2.5 分析 TECH_STACK 以创建手册：

对于 API 复杂的每个软件包：

1. 检查是否有充分依据：

   • 软件包导出的方法超过 10 个
   • 当前版本中有破坏性变更
   • 不在简单软件包列表中：lodash、uuid、dotenv

2. 如果有充分依据，则创建手册：

   • 使用模板：references/templates/manual_template.md
   • MCP 调研：mcp__context7__get-library-docs(topic: "API")
   • 填写模板：
     • 软件包信息及版本
     • 2-3 个最常用的方法
     • 配置部分
   • 保存至：docs/reference/manuals/{package}-{version}.md
   • 记录："✓ 已为 {package} 创建手册"

3. 如果 API 简单，则跳过：

   • 记录："⊘ 已跳过 {package} 的手册：API 简单"

2.6 汇报智能创建结果：

✅ Smart Document Creation complete:
  - ADRs created: [count] (justified: frontend, backend, database)
  - ADRs skipped: [count] (trivial: cache=in-memory)
  - Guides created: [count]
  - Guides skipped: [count]
  - Manuals created: [count]
  - Manuals skipped: [count]

---

阶段 3：验证结构

目标：确保 reference/README.md 符合结构要求，并自动修复违规项。

流程：

2.1 检查开篇约定：

• 读取 docs/reference/README.md（前 5 行）
• 检查是否包含 `` 标签和元数据标记
• 预期：``
• 如果缺失：
  • 使用 Edit 工具在文件顶部附近添加缺失的开篇标记
  • 记录违规项：opening_contract_fixed = True

2.2 检查必需章节：

• 从 references/questions.md 加载预期章节
• 必需章节：
  • “架构决策记录（ADR）”
  • “项目指南”
  • “软件包手册”
  • “研究”
• 对每个章节：
  • 检查是否存在 ## [Section Name] 标题
  • 如果缺失：
    • 使用 Edit 工具添加包含占位符的章节：

      ## [Section Name]
      
      {{PLACEHOLDER}}
      

    • 记录违规项：missing_sections += 1

2.3 检查维护章节：

• 搜索 ## Maintenance 标题
• 如果缺失：
  • 使用 Edit 工具在文件末尾添加：

    ## Maintenance
    
    **Last Updated:** [current date]
    
    **Update Triggers:**
    - New ADRs added to adrs/ directory
    - New guides added to guides/ directory
    - New manuals added to manuals/ directory
    
    **Verification:**
    - [ ] All ADR links in registry are valid
    - [ ] All guide links in registry are valid
    - [ ] All manual links in registry are valid
    - [ ] Placeholders {{ADR_LIST}}, {{GUIDE_LIST}}, {{MANUAL_LIST}} synced with files
    

  • 记录违规项：maintenance_added = True

2.4 检查 POSIX 文件结尾：

• 检查文件是否以单个空行结尾
• 如果缺失：
  • 使用 Edit 工具添加末尾换行符
  • 记录修复：posix_fixed = True

2.5 报告验证结果：

• 记录摘要：

  ✅ Structure validation complete:
    - SCOPE tag: [added/present]
    - Missing sections: [count] sections added
    - Maintenance section: [added/present]
    - POSIX endings: [fixed/compliant]
  

• 如果发现违规项：“⚠️ 已自动修复 [total] 个结构违规项”

---

阶段 4：验证内容

目标：确保每个章节都以有意义的内容回答其问题，并通过自动发现填充目录（包括在阶段 2 中创建的文档）。

流程：

4.1 加载验证规范：

• 读取 references/questions.md
• 解析全部 3 个章节的问题和验证启发式规则

4.2 验证章节（参数化循环）：

定义章节参数：

sections = [
  {
    "name": "Architecture Decision Records (ADRs)",
    "question": "Where are architecture decisions documented?",
    "directory": "docs/reference/adrs/",
    "empty_state": "No ADRs yet.",
    "glob_pattern": "docs/reference/adrs/*.md",
    "heuristics": [
      "Contains link: [ADRs](adrs/) or [adrs](adrs/)",
      "Mentions 'Architecture Decision Record' or 'ADR'",
      "Has actual list or empty-state note",
      "Length > 30 words"
    ]
  },
  {
    "name": "Project Guides",
    "question": "Where are reusable project patterns documented?",
    "directory": "docs/reference/guides/",
    "empty_state": "No project guides yet.",
    "glob_pattern": "docs/reference/guides/*.md",
    "heuristics": [
      "Contains link: [Guides](guides/) or [guides](guides/)",
      "Has actual list or empty-state note",
      "Length > 20 words"
    ]
  },
  {
    "name": "Package Manuals",
    "question": "Where are third-party package references documented?",
    "directory": "docs/reference/manuals/",
    "empty_state": "No package manuals yet.",
    "glob_pattern": "docs/reference/manuals/*.md",
    "heuristics": [
      "Contains link: [Manuals](manuals/) or [manuals](manuals/)",
      "Has actual list or empty-state note",
      "Length > 20 words"
    ]
  },
  {
    "name": "Research",
    "question": "Where are research/investigation documents stored?",
    "directory": "docs/reference/research/",
    "empty_state": "No research notes yet.",
    "glob_pattern": "docs/reference/research/*.md",
    "heuristics": [
      "Contains link: [Research](research/) or [research](research/)",
      "Has actual list or empty-state note",
      "Length > 20 words"
    ]
  }
]

对于 sections 中的每个章节：

1. 读取章节内容：

   • 从 reference/README.md 中提取章节

2. 检查内容是否回答问题：

   • 应用验证启发式规则
   • 如果任一启发式规则通过 → 内容有效，跳到下一章节
   • 如果全部失败 → 内容无效，继续

3. 自动发现（如果内容无效或存在空状态）：

   • 使用 Glob 工具扫描目录（section.glob_pattern）
   • 如果找到文件：
     • 提取文件名
     • 生成动态列表：

       - [ADR-001: 前端框架](adrs/adr-001-frontend-framework.md)
       - [02-仓储模式](guides/02-repository-pattern.md)
       - [Axios 1.6](manuals/axios-1.6.md)
       

     • 使用 Edit 工具将空状态文本替换为生成的列表
     • 记录更改：sections_populated += 1
   • 如果未找到文件：
     • 保留简洁的空状态说明
     • 记录：empty_states_kept += 1

4. 跳过外部 API 调用：

   • 不要使用 MCP Ref 搜索（模板中已有格式示例）

4.3 报告内容验证结果：

• 记录摘要：

  ✅ Content validation complete:
    - Sections checked: 4
    - Populated from auto-discovery: [count]
    - Placeholders kept (no files): [count]
    - Already valid: [count]
  

---

完整输出结构

docs/
└── reference/
    ├── README.md                     # Reference hub with registries
    ├── adrs/                         # Empty or with ADR files
    ├── guides/                       # Empty or with guide files
    ├── manuals/                      # Empty or with manual files
    └── research/                     # Empty or with research files

---

参考文件

模板

参考 README 模板：

• references/templates/reference_readme_template.md (v2.0.0) - 参考资料中心，包含：
  • SCOPE 标签（仅用于参考文档）
  • 三个包含占位符的注册表部分
  • 维护部分

文档模板（用于 Phase 2 智能创建）：

• references/templates/adr_template.md - Nygard ADR 格式（7 个部分）
• references/templates/guide_template.md - 模式文档（做法/避免做法/适用时机）
• references/templates/manual_template.md - API 参考格式
• references/templates/research_template.md - 研究/Spike 文档

依据规则：

• references/tech_justification_rules.md - 映射关系：类别 → 创建/跳过条件

验证规范：

• references/questions.md (v2.0) - 由问题驱动的验证：

  • Q1-Q3：注册表部分（ADR、指南、手册）
  • Q4-Q7：智能文档验证（ADR 背景、替代方案、模式）
  • 自动发现提示

• **必须阅读：**加载 references/research_tool_fallback.md

---

最佳实践

• 不要过早验证：Phase 1 创建结构，Phase 3 验证结构
• 智能创建：Phase 2 仅为有充分依据的选择创建文档
• 参数化验证：Phase 4 使用循环验证 3 个部分（不重复代码）
• 优先自动发现：在调用外部 API 前扫描实际文件
• 幂等：✅ 可安全地多次运行（创建前检查是否已存在）
• 职责分离：CREATE → SMART DOCS → VALIDATE STRUCTURE → VALIDATE CONTENT

NO_CODE_EXAMPLES 规则（指南中必须遵守）

指南记录模式，而非实现：

• **禁止：**完整的函数实现、超过 5 行的代码块
• **允许：**做法/避免做法/适用时机表格、方法签名（1 行）、伪代码（1-3 行）
• **不要写代码，改为：**引用源代码位置：“参见 src/hooks/usePlan.ts:15-30”
• **模板规则：**guide_template.md 包含 `` 标签——务必遵循

技术栈适配规则（必须遵守）

• ADR 必须引用适合技术栈的替代方案（比较 React 与 Vue，而非 React 与 Django）
• 指南必须链接到正确平台的文档（.NET 使用 Microsoft 文档，JS 使用 MDN）

格式优先级（必须遵守）

表格（做法/避免做法/适用时机）> ASCII 图表 > 列表 > 文本

---

前置条件

调用方：ln-100-documents-pipeline 编排器

需要：

• docs/ 目录（由 ln-111-root-docs-creator 创建，或已存在于目标项目中）

创建：

• docs/reference/ 目录结构及 README 中心页
• 已验证的结构和内容（从现有文件自动发现）

---

关键规则

• **仅创建有依据的文档：**仅为存在实际替代方案的非平凡技术选择创建文档；跳过平凡或显而易见的选择
• **NO_CODE_EXAMPLES：**指南记录模式（做法/避免做法/适用时机表格），而非实现；不得包含超过 5 行的代码块
• **技术栈适配：**ADR 的替代方案必须适合技术栈（React 与 Vue，而非 React 与 Django）；链接必须指向相应平台的文档
• **格式优先级：**表格（做法/避免做法/适用时机）> ASCII 图表 > 列表 > 文本
• **幂等：**创建前检查是否已存在；可安全地多次运行

运行时摘要产物

**必须阅读：**加载 references/docs_generation_summary_contract.md

接受可选的 summaryArtifactPath。

摘要类型：

• docs-generation

必需的负载语义：

• worker = "ln-120"
• status
• created_files
• skipped_files
• quality_inputs
• validation_status
• warnings

将摘要写入提供的产物路径，或在结构化输出中返回相同的封装对象。

完成定义

完成工作前，请核实所有检查项：

✅ 阶段 1 - 创建结构：

• docs/reference/ 目录存在
• docs/reference/adrs/ 目录存在
• docs/reference/guides/ 目录存在
• docs/reference/manuals/ 目录存在
• docs/reference/research/ 目录存在
• docs/reference/README.md 存在（新建或已存在）

✅ 阶段 2 - 创建智能文档（如果提供了上下文存储）：

• 为合理的技术选择创建 ADR（非简单选择）
• 跳过简单选择的 ADR（并记录）
• 为配置复杂的技术创建指南
• 为 API 复杂的包创建手册
• 每份已创建的文档都包含实际内容（而非占位内容）

✅ 阶段 3 - 验证结构：

• 顶部附近包含 SCOPE 标签和元数据标记
• 包含快速导航、Agent 入口和维护部分
• 包含四个登记表部分（ADR、指南、手册、研究）
• 末尾包含维护部分
• 符合 POSIX 文件结尾规范

✅ 阶段 4 - 验证内容：

• 根据 questions.md 检查所有章节
• 所有登记表均包含空状态说明或实际条目（无原始占位内容）
• 未出现验证启发式检查失败

✅ 报告：

• 已记录阶段 1：创建摘要
• 已记录阶段 2：智能创建（创建/跳过数量）
• 已记录阶段 3：结构修复（如有）

返回约定

向 ln-100 返回规范化状态：

{
  "created_files": ["docs/reference/README.md", "docs/reference/adrs/adr-001-frontend.md"],
  "skipped_files": [],
  "quality_inputs": {
    "doc_paths": ["docs/reference/README.md", "docs/reference/adrs/adr-001-frontend.md"],
    "owners": {
      "docs/reference/README.md": "ln-120-reference-docs-creator",
      "docs/reference/adrs/adr-001-frontend.md": "ln-120-reference-docs-creator"
    }
  },
  "validation_status": "passed"
}

✅ 报告（续）：

• 已记录阶段 4：内容更新（如有）

元分析

可选参考：仅当用户要求运行后元分析或按协议格式进行运行回顾时，才加载 references/meta_analysis_protocol.md。

技能类型：documentation-creator。收到请求时，在所有阶段完成后运行。使用 documentation-creator 格式在聊天中输出。

---

技术详情

标准：

• Michael Nygard 的 ADR 格式（7 个章节）
• ISO/IEC/IEEE 29148:2018（文档标准）

语言：仅限英语

---

版本： 8.2.0 最后更新： 2025-01-12