ln-112-project-core-creator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Project Core Documentation Creator

项目核心文档生成器

L3 Worker that creates 4 core project documentation files. These are ALWAYS created regardless of project type.

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

Purpose & Scope

目的与范围

Creates 4 core project documentation files (required for all projects)
Receives Context Store from ln-110-project-docs-coordinator
Heavy use of auto-discovery (architecture needs full project scan)
Replaces placeholders with project-specific data
Self-validates structure and content (16+ questions)
Never gathers context itself; uses coordinator input

创建4个核心项目文档文件（所有项目均要求）
从ln-110-project-docs-coordinator接收Context Store
大量使用自动发现功能（架构文档需要完整项目扫描）
用项目特定数据替换占位符
自我验证结构与内容（16+个检查项）
从不自行收集上下文；仅使用协调器提供的输入

Invocation (who/when)

调用方式（调用方/时机）

ln-110-project-docs-coordinator: ALWAYS invoked as second worker (after ln-111)
Never called directly by users

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

Inputs

输入参数

From coordinator:

```
contextStore
```
: Full Context Store with all discovered data
- PROJECT_NAME, PROJECT_DESCRIPTION
- TECH_STACK (full object: frontend, backend, database, etc.)
- DEPENDENCIES (from package.json)
- SRC_STRUCTURE (folder analysis)
- EXTERNAL_SYSTEMS (from .env.example)
- CODE_CONVENTIONS (from eslint, prettier)
- ADR_LIST (from docs/reference/adrs/)
- LEGACY_CONTENT (optional, from ln-100 Phase 0 migration):
  - ```
  legacy_architecture
```
  : { layers[], components[], diagrams[], data_flow }
- ```
legacy_requirements
```
    : { functional[], non_functional[], user_stories[] }
  - ```
  legacy_tech_stack
```
  : { frontend, backend, database, versions }
```
targetDir
```
: Project root directory

LEGACY_CONTENT is used as base content when creating documents. Priority: Legacy > Auto-discovery > Template defaults.

来自协调器：

```
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/）
- LEGACY_CONTENT（可选，来自ln-100阶段0迁移）：
  - ```
  legacy_architecture
```
  : { layers[], components[], diagrams[], data_flow }
- ```
legacy_requirements
```
    : { functional[], non_functional[], user_stories[] }
  - ```
  legacy_tech_stack
```
  : { frontend, backend, database, versions }
```
targetDir
```
：项目根目录

LEGACY_CONTENT 会作为创建文档时的基础内容。优先级：遗留内容 > 自动发现内容 > 模板默认值。

Documents Created (4)

创建的文档（4个）

File	Target Sections	Questions	Auto-Discovery
docs/project/requirements.md	Functional Requirements (FR-XXX-NNN format)	Q23	Low
docs/project/architecture.md	11 arc42 sections with C4 diagrams	Q24-Q34	High
docs/project/tech_stack.md	Frontend, Backend, Database, Additional	Q35-Q38	High
docs/architecture/patterns_catalog.md	Pattern summary, 4-score model, trend tracking	—	High

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

Workflow

工作流程

Phase 1: Receive Context

阶段1：接收上下文

Parse full Context Store from coordinator
Validate required keys (PROJECT_NAME, TECH_STACK)
Extract architecture-specific data (SRC_STRUCTURE, DEPENDENCIES)

解析来自协调器的完整Context Store
验证必填字段（PROJECT_NAME、TECH_STACK）
提取架构特定数据（SRC_STRUCTURE、DEPENDENCIES）

Phase 2: Create Documents

阶段2：创建文档

For each document (requirements.md, architecture.md, tech_stack.md, patterns_catalog.md):

Check if file exists (idempotent)
If exists: skip with log
If not exists:
- Copy template from
```
references/templates/
```
- Check LEGACY_CONTENT for this document type:
  - For
```
architecture.md
```
    : If
```
LEGACY_CONTENT.legacy_architecture
```
    exists:
    - Use
      legacy_architecture.layers[]
      for "## Building Block View" (Section 5)
    - Use
      legacy_architecture.components[]
      for component descriptions
    - Use
      legacy_architecture.diagrams[]
      for existing diagrams (preserve mermaid/images)
    - Use
      legacy_architecture.data_flow
      for "## Runtime View" (Section 6)
    - Merge with auto-discovered SRC_STRUCTURE (legacy takes priority)
    - Mark:
      
      at top of merged sections
  - For
```
requirements.md
```
    : If
```
LEGACY_CONTENT.legacy_requirements
```
    exists:
    - Use
      legacy_requirements.functional[]
      as base for FR-XXX requirements
    - Use
      legacy_requirements.user_stories[]
      if FR format not found
    - Augment with template structure (add MoSCoW labels if missing)
  - For
```
tech_stack.md
```
    : If
```
LEGACY_CONTENT.legacy_tech_stack
```
    exists:
    - Use
      legacy_tech_stack.versions
      as base for technology versions
    - Merge with auto-discovered TECH_STACK (legacy versions take priority)
    - Use
      legacy_tech_stack.rationale
      for decision explanations
  - For
```
patterns_catalog.md
```
    :
    - Copy template from
      shared/templates/patterns_template.md
    - Auto-detect patterns in codebase:
      - Grep("Queue|Worker|Job|Bull") → Job Processing
      - Grep("EventEmitter|publish|subscribe") → Event-Driven
      - Grep("Cache|Redis|Memcached") → Caching
      - Grep("CircuitBreaker|Retry") → Resilience
    - Add detected patterns as "Status: Detected" (not yet audited)
    - Link to existing ADRs if pattern names match
    - Mark:
      
- Replace
```
{{PLACEHOLDER}}
```
  with Context Store values
- Generate C4 diagrams from SRC_STRUCTURE (for architecture.md, if no legacy diagrams)
- Insert ADR links (for architecture.md Section 8)
- Mark
```
[TBD: X]
```
  for missing data

针对每个文档（requirements.md、architecture.md、tech_stack.md、patterns_catalog.md）：

检查文件是否已存在（幂等性）
若已存在：记录日志并跳过
若不存在：
- 从
```
references/templates/
```
  复制模板
- 检查该文档类型对应的LEGACY_CONTENT：
  - 对于
```
architecture.md
```
    ：若
```
LEGACY_CONTENT.legacy_architecture
```
    存在：
    - 使用
      legacy_architecture.layers[]
      填充「## 构建块视图」（第5章）
    - 使用
      legacy_architecture.components[]
      填充组件描述
    - 使用
      legacy_architecture.diagrams[]
      填充现有图表（保留Mermaid/图片）
    - 使用
      legacy_architecture.data_flow
      填充「## 运行时视图」（第6章）
    - 与自动发现的SRC_STRUCTURE合并（遗留内容优先级更高）
    - 在合并章节顶部标记：
      
  - 对于
```
requirements.md
```
    ：若
```
LEGACY_CONTENT.legacy_requirements
```
    存在：
    - 使用
      legacy_requirements.functional[]
      作为FR-XXX需求的基础
    - 若未找到FR格式，则使用
      legacy_requirements.user_stories[]
    - 补充模板结构（若缺失则添加MoSCoW标签）
  - 对于
```
tech_stack.md
```
    ：若
```
LEGACY_CONTENT.legacy_tech_stack
```
    存在：
    - 使用
      legacy_tech_stack.versions
      作为技术版本的基础
    - 与自动发现的TECH_STACK合并（遗留版本优先级更高）
    - 使用
      legacy_tech_stack.rationale
      填充决策说明
  - 对于
```
patterns_catalog.md
```
    ：
    - 从
      shared/templates/patterns_template.md
      复制模板
    - 自动检测代码库中的模式：
      - Grep("Queue|Worker|Job|Bull") → 任务处理模式
      - Grep("EventEmitter|publish|subscribe") → 事件驱动模式
      - Grep("Cache|Redis|Memcached") → 缓存模式
      - Grep("CircuitBreaker|Retry") → 弹性模式
    - 将检测到的模式标记为「状态：已检测」（尚未审核）
    - 若模式名称匹配，则链接至现有ADR
    - 标记：
      
- 将
```
{{PLACEHOLDER}}
```
  替换为Context Store中的值
- 若没有遗留图表，则从SRC_STRUCTURE生成C4 diagrams（用于architecture.md）
- 插入ADR链接（用于architecture.md第8章）
- 为缺失的数据标记
```
[TBD: X]
```

Phase 3: Self-Validate

阶段3：自我验证

For each created document:

Check SCOPE tag in first 10 lines
Check required sections (from questions_core.md)
Validate specific format requirements:
- requirements.md: FR-XXX identifiers, MoSCoW labels
- architecture.md: 11 sections, C4 diagrams, ADR references
- tech_stack.md: versions, rationale for each technology
Check Maintenance section
Auto-fix issues where possible

针对每个已创建的文档：

检查前10行中的SCOPE标签
检查必填章节（来自questions_core.md）
验证特定格式要求：
- requirements.md：FR-XXX标识符、MoSCoW标签
- architecture.md：11个章节、C4 diagrams、ADR引用
- tech_stack.md：版本信息、每项技术的选型理由
检查维护章节
尽可能自动修复问题

Phase 4: Return Status

阶段4：返回状态

Return to coordinator:

json

{
  "created": ["docs/project/requirements.md", ...],
  "skipped": [],
  "tbd_count": 5,
  "validation": "OK",
  "diagrams_generated": 3
}

向协调器返回：

json

{
  "created": ["docs/project/requirements.md", ...],
  "skipped": [],
  "tbd_count": 5,
  "validation": "OK",
  "diagrams_generated": 3
}

Critical Notes

重要说明

Idempotent: Never overwrite existing files
Heavy auto-discovery: architecture.md requires deep project analysis
C4 diagrams: Generated from SRC_STRUCTURE in Mermaid format
ADR integration: Section 8 links to docs/reference/adrs/
arc42 compliance: ISO/IEC/IEEE 42010:2022 structure
TBD markers: Use
```
[TBD: X]
```
for missing data

幂等性： 绝不覆盖现有文件
深度自动发现： architecture.md需要对项目进行深度分析
C4 diagrams： 从SRC_STRUCTURE生成，采用Mermaid格式
ADR集成： 第8章链接至docs/reference/adrs/
arc42合规： 符合ISO/IEC/IEEE 42010:2022结构标准
TBD标记： 对缺失数据使用
```
[TBD: X]
```

NO_CODE_EXAMPLES Rule (MANDATORY)

NO_CODE_EXAMPLES规则（强制）

Documents describe contracts and decisions, NOT implementations:

FORBIDDEN: Code blocks > 5 lines, function implementations, imports, DI configuration
ALLOWED: Mermaid diagrams, component tables, method signatures (1 line), ADR links
INSTEAD OF CODE: Reference source: "See src/Services/UserService.cs:45"
TEMPLATE RULE: All templates include
```

```
tag - FOLLOW IT

文档用于描述约定与决策，而非实现细节：

禁止： 超过5行的代码块、函数实现、导入语句、DI配置
允许： Mermaid图表、组件表格、方法签名（1行）、ADR链接
替代代码的方式： 引用源代码："参见src/Services/UserService.cs:45"
模板规则： 所有模板均包含
```

```
标签，请严格遵循

Stack Adaptation Rule (MANDATORY)

技术栈适配规则（强制）

Links must reference stack-appropriate docs (Microsoft for .NET, MDN for JS)
Never mix stack references (no Python examples in .NET project)

链接必须引用适配技术栈的文档（.NET项目引用Microsoft文档，JS项目引用MDN文档）
绝不能混合技术栈引用（.NET项目中不得出现Python示例）

Format Priority (MANDATORY)

格式优先级（强制）

Tables > Mermaid/ASCII diagrams > Lists > Text

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

Definition of Done

完成标准

Context Store received and validated
4 core documents created (or skipped if exist)
C4 diagrams generated (Context, Container, Component)
ADR links populated
Patterns auto-detected and added to catalog
Self-validation passed (SCOPE, sections, format)
Status returned to coordinator

已接收并验证Context Store
4个核心文档已创建（或因已存在而跳过）
已生成C4 diagrams（上下文图、容器图、组件图）
已填充ADR链接
已自动检测模式并添加至模式目录
自我验证通过（范围、章节、格式）
已向协调器返回状态

Reference Files

参考文件

Templates:

references/templates/requirements_template.md

architecture_template.md

tech_stack_template.md

Patterns template:
```
shared/templates/patterns_template.md
```
Questions:
```
references/questions_core.md
```
(Q23-Q38)

Version: 2.2.0 (Added Stack Adaptation and Format Priority rules) Last Updated: 2025-01-12

模板：

references/templates/requirements_template.md

、

architecture_template.md

、

tech_stack_template.md

模式模板：
```
shared/templates/patterns_template.md
```
检查项：
```
references/questions_core.md
```
（Q23-Q38）

版本： 2.2.0（新增技术栈适配与格式优先级规则） 最后更新： 2025-01-12