ln-112-project-core-creator

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

项目核心文档创建器

类型： L3 Worker

用于创建 4 个核心项目文档文件的 L3 Worker。无论项目类型如何，始终都会创建这些文件。

目的与范围

• 创建 4 个核心项目文档文件（所有项目都必须包含）
• 接收来自 ln-110-project-docs-coordinator 的 Context Store
• 大量使用自动发现（架构分析需要扫描整个项目）
• 将占位符替换为项目专属数据
• 自行验证结构和内容（16 个以上问题）
• 从不自行收集上下文；使用协调器提供的输入

调用（调用方／时机）

• ln-110-project-docs-coordinator： 始终作为第二个 Worker 调用（在 ln-111 之后）
• 用户不得直接调用

输入

来自协调器：

• contextStore：包含所有已发现数据的完整 Context Store
  • PROJECT_NAME、PROJECT_DESCRIPTION
  • TECH_STACK（完整对象：前端、后端、数据库等）
  • DEPENDENCIES（来自 package.json）
  • SRC_STRUCTURE（文件夹分析）
  • EXTERNAL_SYSTEMS（来自 .env.example）
  • CODE_CONVENTIONS（来自 eslint、prettier）
  • ADR_LIST（来自 docs/reference/adrs/）
• targetDir：项目根目录

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

创建的文档（4 个）

文件	目标章节	问题	自动发现
docs/project/requirements.md	功能需求（FR-XXX-NNN 格式）	Q23	低
docs/project/architecture.md	包含 C4 图的 11 个 arc42 章节	Q24-Q34	高
docs/project/tech_stack.md	前端、后端、数据库、其他	Q35-Q38	高
docs/architecture/patterns_catalog.md	模式摘要、4 项评分模型、趋势跟踪	—	高

工作流

阶段 1：接收上下文

1. 解析协调器提供的完整 Context Store
2. 验证必需的键（PROJECT_NAME、TECH_STACK）
3. 提取架构专属数据（SRC_STRUCTURE、DEPENDENCIES）

阶段 2：创建文档

针对每份文档（docs/project/requirements.md、docs/project/architecture.md、docs/project/tech_stack.md、docs/architecture/patterns_catalog.md）：

1. 检查文件是否存在（幂等）
2. 如果存在：记录日志并跳过
3. 如果不存在：
   • 从 references/templates/ 复制模板
   • docs/project/requirements.md：从当前产品／项目资料中提取需求，并规范为 FR-XXX 结构
   • docs/project/architecture.md：根据当前源代码树、ADR 和运行时边界提取结构；根据实际代码事实生成图表
   • docs/project/tech_stack.md：从当前依赖项和配置文件中提取版本和选择理由
   • docs/architecture/patterns_catalog.md：
     • 从 references/templates/patterns_template.md 复制模板
     • 自动检测当前代码库中的模式：
       • Grep("Queue|Worker|Job|Bull") → 作业处理
       • Grep("EventEmitter|publish|subscribe") → 事件驱动
       • Grep("Cache|Redis|Memcached") → 缓存
       • Grep("CircuitBreaker|Retry") → 弹性
     • 将检测到的模式添加为“Status: Detected”（尚未审核）
     • 如果模式名称匹配，则链接到现有 ADR
     • 标记：``
   • 将 {{PLACEHOLDER}} 替换为 Context Store 中的值
   • 保留共享开篇约定：SCOPE、DOC_KIND、DOC_ROLE、READ_WHEN、SKIP_WHEN、PRIMARY_SOURCES
   • 保留标准顶部章节：Quick Navigation、Agent Entry、Maintenance
   • 根据 SRC_STRUCTURE 生成 C4 图表（如果 architecture.md 中没有旧版图表）
   • 插入 ADR 链接（architecture.md 第 8 节）
   • 发布的项目文档中不得残留模板标记
   • 如果缺少数据：省略相关论断或使用简洁、中性的兜底表述，但不得输出 [TBD: ...]

阶段 3：自我验证

针对每份创建的文档：

1. 检查开篇内容块中的 SCOPE 标签和元数据标记
2. 检查必需的顶部章节（Quick Navigation、Agent Entry、Maintenance）
3. 检查必需章节（来自 questions_core.md）
4. 验证特定格式要求：
   • requirements.md：FR-XXX 标识符、MoSCoW 标签
   • architecture.md：11 个章节、C4 图表、ADR 引用
   • tech_stack.md：版本，以及每项技术的选择理由
5. 检查是否符合 docs-quality 约定（没有禁用的占位符、泄露的模板元数据，且文档类型／角色有效）
6. 尽可能自动修复问题

阶段 4：返回状态

向协调器返回：

{
  "created_files": ["docs/project/requirements.md", "docs/project/architecture.md", "docs/project/tech_stack.md", "docs/architecture/patterns_catalog.md"],
  "skipped_files": [],
  "quality_inputs": {
    "doc_paths": ["docs/project/requirements.md", "docs/project/architecture.md", "docs/project/tech_stack.md", "docs/architecture/patterns_catalog.md"],
    "owners": {
      "docs/project/requirements.md": "ln-112-project-core-creator",
      "docs/project/architecture.md": "ln-112-project-core-creator",
      "docs/project/tech_stack.md": "ln-112-project-core-creator",
      "docs/architecture/patterns_catalog.md": "ln-112-project-core-creator"
    }
  },
  "validation_status": "passed",
  "diagrams_generated": 3
}

关键说明

• **幂等：**绝不覆盖现有文件
• **深度自动发现：**architecture.md 需要深入分析项目
• **C4 图表：**根据 SRC_STRUCTURE 以 Mermaid 格式生成
• **ADR 集成：**第 8 节链接到 docs/reference/adrs/
• **arc42 合规：**符合 ISO/IEC/IEEE 42010:2022 结构
• **可发布的输出：**核心项目文档不得包含 [TBD: ...]、TODO 或泄露的模板元数据

NO_CODE_EXAMPLES 规则（强制）

文档描述的是约定和决策，而非实现：

• **禁止：**超过 5 行的代码块、函数实现、导入语句、DI 配置
• **允许：**Mermaid 图表、组件表、方法签名（1 行）、ADR 链接
• **不要写代码，而应：**引用源代码，例如“参见 src/Services/UserService.cs:45”
• **模板规则：**所有模板都包含 `` 标签——必须遵循

技术栈适配规则（强制）

• 链接必须指向适用于相应技术栈的文档（.NET 使用 Microsoft 文档，JS 使用 MDN）
• 切勿混用技术栈参考资料（.NET 项目中不得使用 Python 示例）

格式优先级（强制）

表格 > Mermaid／ASCII 图表 > 列表 > 文本

运行时摘要工件

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

接受可选的 summaryArtifactPath。

摘要类型：

• docs-generation

必需的负载语义：

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

将摘要写入提供的工件路径，或在结构化输出中返回相同的信封。

完成定义

• 已接收并验证 Context Store
• 已创建 4 份核心文档（若已存在则跳过）
• 已生成 C4 图（Context、Container、Component）
• 已填充 ADR 链接
• 已自动检测模式并添加到目录
• 已通过自我验证（元数据标记、顶部章节、格式）
• 已验证时效性： 所有文档事实均与当前代码相符（路径、函数、API、配置均存在且准确）
• 已返回状态

参考文件

• 模板：references/templates/requirements_template.md、references/templates/architecture_template.md、references/templates/tech_stack_template.md
• 模式模板：references/templates/patterns_template.md
• 问题：references/questions_core.md（Q23-Q38）

---

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