ln-111-root-docs-creator

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

根文档创建器

类型： L3 Worker

L3 Worker，使用模板和协调器提供的 Context Store 创建 7 个根文档文件。

目的与范围

• 创建 7 个根文档文件（AI Agent 的入口）
• 接收来自 ln-110-project-docs-coordinator 的 Context Store
• 用项目专属数据替换占位符
• 自行验证结构和内容（22 个问题）
• 从不自行收集上下文；使用协调器提供的输入

输入

来自协调器：

• contextStore：包含所有占位符的键值对
  • PROJECT_NAME、PROJECT_DESCRIPTION
  • TECH_STACK_SUMMARY
  • DEV_COMMANDS（来自 package.json 脚本）
  • DATE（当前日期）
  • ENABLE_WORKFLOW_PRINCIPLES（可选布尔值；默认为 false）——当值为 true 时，在 AGENTS.md 中用 references/templates/agents_md_workflow_principles.md 的内容展开 {{WORKFLOW_PRINCIPLES_BLOCK}} 占位符
• targetDir：项目根目录

必须阅读： 加载 references/docs_quality_contract.md 和 references/agent_instructions_writing_guide.md（AGENTS.md / CLAUDE.md 的规范写作指南）。 可选规则目录：仅在需要精确规则 ID、路径矩阵或允许的占位符例外时，加载 references/docs_quality_rules.json。

创建的文档

文件	目标章节	问题
AGENTS.md	快速导航、Agent 入口、关键规则、（可选）工作流原则、开发命令、维护	Q1-Q6
CLAUDE.md	@AGENTS.md 导入 + ## Claude Code 差异内容（总计 ≤20 行）	Q1-Q6
docs/README.md	快速导航、Agent 入口、文档地图、维护	Q7-Q13
docs/documentation_standards.md	快速参考（60+ 项要求）、12 个主要章节、维护	Q14-Q16
docs/principles.md	核心原则（8 条）、决策框架、反模式、验证、维护	Q17-Q22

工作流

阶段 1：接收上下文

1. 解析协调器提供的 Context Store
2. 验证必需键是否存在（PROJECT_NAME、PROJECT_DESCRIPTION）
3. 为缺少的可选键设置默认值（ENABLE_WORKFLOW_PRINCIPLES 默认为 false）

Phase 2：创建文档

对于每份文档（AGENTS.md、CLAUDE.md、docs/README.md、docs/documentation_standards.md、docs/principles.md）：

1. 检查文件是否存在（幂等）
2. 如果存在：记录日志并跳过
3. 如果不存在：
   • 从 references/templates/ 复制模板
   • 对于 AGENTS.md：确保符合共享标头约定（SCOPE、DOC_KIND、DOC_ROLE: canonical、READ_WHEN、SKIP_WHEN、PRIMARY_SOURCES）和顶部章节约定（## Quick Navigation、## Agent Entry、## Critical Rules、## Maintenance）
   • 对于 AGENTS.md：如果 ENABLE_WORKFLOW_PRINCIPLES=true，则将 {{WORKFLOW_PRINCIPLES_BLOCK}} 占位符替换为 references/templates/agents_md_workflow_principles.md 的完整内容；否则删除占位符行及其前导注释
   • 对于 CLAUDE.md：使用导入桩模板（claude_md_template.md）。该模板包含 DOC_ROLE: derived、单独一行的 @AGENTS.md，以及范围有限的、特定于运行环境的增量内容。不要内嵌任何 AGENTS.md 内容
   • 对于 docs/principles.md：优先使用 Context Store 中已有的规范化原则输入
   • 如果没有项目特定的原则，则保留模板结构，仅填写当前项目来源能够支持的事实
   • 使用 Context Store 中的值替换 {{PLACEHOLDER}} 标记
   • 发布的根目录文档中不得残留模板标记
   • 如果缺少数据：省略相关说法，或使用简洁、中性的替代内容，但不要输出 [TBD: ...]
   • 写入文件

根目录入口规则（规范模型）：

• AGENTS.md 是唯一的规范内容来源。其中包含 Critical Rules 表、MCP Tool Preferences、Navigation、Development Commands 和可选的 Workflow Principles。
• CLAUDE.md 是特定于 Claude Code 的桩文件，包含 @AGENTS.md 以及带有特定运行环境规则的 ## Claude Code 增量内容（总计 ≤20 行，绝对上限为 50 行）。不要重复 AGENTS.md 的内容。
• Claude Code 会在会话启动时将 @path 导入内容展开到上下文中，因此导入的 AGENTS.md 会自动可用。
• 运行环境增量内容：命令术语（/compact、/memory show）、存储路径（~/.claude/projects/<project>/memory/）以及 Claude 专属功能（带有 paths: frontmatter 的 .claude/rules/、嵌套式按需加载）。

Phase 3：自我验证

对于每份已创建的文档：

1. 检查前 12 行中是否有 SCOPE 标签
2. 检查元数据标记（DOC_KIND、DOC_ROLE、READ_WHEN、SKIP_WHEN、PRIMARY_SOURCES）
3. 对于 AGENTS.md：检查是否包含 Quick Navigation、Agent Entry、Critical Rules、Maintenance
4. 对于 CLAUDE.md：检查是否存在 @AGENTS.md 导入行，且文件不超过 50 行
5. 检查必需章节（见 questions_root.md）
6. 检查是否符合 docs-quality 规范（没有禁用占位符，没有泄露的模板元数据）
7. 检查是否使用 POSIX 换行符（文件末尾只有一个换行符）
8. 尽可能自动修复问题

Phase 4：返回状态

向协调器返回：

{
  "created_files": ["AGENTS.md", "CLAUDE.md", "docs/README.md", "docs/documentation_standards.md", "docs/principles.md"],
  "skipped_files": [],
  "quality_inputs": {
    "doc_paths": ["AGENTS.md", "CLAUDE.md", "docs/README.md", "docs/documentation_standards.md", "docs/principles.md"],
    "owners": {
      "AGENTS.md": "ln-111-root-docs-creator",
      "CLAUDE.md": "ln-111-root-docs-creator",
      "docs/README.md": "ln-111-root-docs-creator",
      "docs/documentation_standards.md": "ln-111-root-docs-creator",
      "docs/principles.md": "ln-111-root-docs-creator"
    }
  },
  "validation_status": "passed"
}

重要说明

核心规则

• 幂等： 切勿覆盖现有文件；跳过并记录日志
• 不收集上下文： 所有数据均来自协调器的 Context Store
• 可发布的输出： 根目录文档不得包含 [TBD: ...]、TODO 或泄露的模板元数据
• 语言： 所有根目录文档均使用英语（通用标准）
• SCOPE 标签： 每个文件的前 10 行中必须包含（HTML 注释会从 Claude Code 注入的上下文中剥离，但维护者和审计人员仍可见）
• 规范源-桩文件根目录模型： AGENTS.md 是唯一内容来源；CLAUDE.md 是 @AGENTS.md 导入内容及范围有限的运行环境增量。设计理由和反模式见 references/agent_instructions_writing_guide.md。

NO_CODE_EXAMPLES 规则（强制）

根目录文档定义的是导航和标准，而不是实现：

• 禁止： 代码块、实现片段
• 允许： 表格、链接、命令示例（1 行）
• 模板规则： 所有模板都包含 `` 标签——务必遵守

技术栈适配规则（MANDATORY）

• 所有外部链接必须与项目技术栈匹配（从 Context Store 检测）
• .NET 项目 → Microsoft 文档；Node.js → MDN、npm 文档；Python → Python 文档
• 切勿混用技术栈参考资料（.NET 项目中不得包含 Python 示例）

格式优先级（MANDATORY）

表格/ASCII > 列表（仅限枚举）> 文本（最后选择）

运行时摘要产物

MANDATORY READ： 加载 references/docs_generation_summary_contract.md

接受可选的 summaryArtifactPath。

摘要类型：

• docs-generation

必需的负载语义：

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

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

完成定义

• 已接收并验证 Context Store
• 已创建根文档（若已存在则跳过）
• 已替换所有占位符；根文档中不再有 [TBD: ...] 标记或模板元数据
• CLAUDE.md 中恰好包含一行 @AGENTS.md，且精简的 harness 增补不超过 50 行
• 如果 ENABLE_WORKFLOW_PRINCIPLES=true：已在 AGENTS.md 中扩充工作流原则分片；如果为 false：已移除占位行
• 自我验证已通过（SCOPE、元数据标记、顶部章节、Maintenance、POSIX）
• 已核实准确性： 所有文档事实均与当前代码一致（路径、函数、API、配置均存在且准确）
• 已返回状态

参考文件

• 模板：references/templates/agents_md_template.md、references/templates/claude_md_template.md、references/templates/agents_md_workflow_principles.md、references/templates/docs_root_readme_template.md、references/templates/documentation_standards_template.md、references/templates/principles_template.md
• 问题：references/questions_root.md（Q1-Q22）
• 写作指南： references/agent_instructions_writing_guide.md（关于 @AGENTS.md 导入模式、大小预算和反模式的权威说明）
• 环境状态： references/environment_state_contract.md（检测与引导模式）

---

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