docs-desc-generation

name	docs-desc-generation
description	Codex 的业务域文档生成技能。适用于为 Java 项目初始化或补充 `docs/desc/` 业务域文档、建立领域上下文、生成技术速查和域文档骨架。当项目缺少业务域文档、需要建立知识库或需要补齐某个业务域说明时使用。

业务域文档生成

本技能负责生成和补充项目的业务域文档体系。它和 docs/codex/{version}/ 的需求/设计/计划/追踪文档不是一回事：

• docs/desc/：长期业务上下文与领域知识库
• docs/codex/{version}/：某轮需求交付的阶段产物

一、开始执行

执行前先完成：

1. 检查 .gitignore 是否包含 .codex/
2. 按 task-control 规则注册本任务
3. 确认本次是“初始化文档”还是“补某个域的文档”

二、工作区机制

使用 Codex 版工作区：

• 工作区目录：.codex/desc-work/{branch}/
• 所有阶段产出先写入工作区
• 不直接覆盖正式区 docs/desc/
• 每阶段完成后允许用户决定继续、人工整合或再审查

最终正式产物：

文件	用途
docs/desc/README.md	业务域索引、系统概览、阅读建议
docs/desc/TECH-REF.md	技术速查、问题定位、关键入口
docs/desc/{domain}/{domain}-domain.md	各业务域详细文档

三、流程总览

阶段0：骨架建立
  -> 工作区 README + TECH-REF
阶段1：逐域深入
  -> 各域 domain 文档
阶段2：跨域补全
  -> 业务域关系图 + 核心数据流
阶段3：全局优化
  -> 统一术语、去重、补缺
阶段4：准确性抽查
  -> 核心声明与代码交叉验证
验收
  -> 确认是否整理进正式区 docs/desc/

四、文档编写约束

1. 不写代码行号引用
2. 不大段粘贴源码
3. 没读过的代码不写结论
4. 不确定的信息标记“待确认”
5. 流程、表格、职责说明优先于代码摘抄

五、阶段执行

阶段0：骨架建立

输出：

• 工作区 README.md
• 工作区 TECH-REF.md

至少完成：

1. 技术栈识别
2. 分层架构识别
3. 核心 Service 清单
4. 业务入口清单
5. 核心数据表清单
6. 生成骨架文档

工作区建议路径：

.codex/desc-work/{branch}/README.md
.codex/desc-work/{branch}/TECH-REF.md

阶段1：逐域深入

对每个业务域输出：

.codex/desc-work/{branch}/{domain}/{domain}-domain.md

每个域至少包含：

• 业务概述
• 核心业务流程
• 数据模型
• 业务规则
• 异步流程
• 域间交互
• 常见问题定位

补充数据模型时，优先使用 dev-small-tool 查询真实表结构、索引和字段信息，不凭记忆猜测表名。

阶段2：跨域补全

基于各域文档补充：

• 业务域关系图
• 核心数据流
• README 阅读建议

阶段3：全局优化

整体阅读工作区文档，统一：

• 术语
• 结构
• 域边界
• 流程命名
• 问题定位表达

阶段4：准确性抽查

至少抽查 1 到 2 个核心域：

• 状态枚举是否和代码一致
• 事件、线程池、锁名是否和代码一致
• 关键入口、关键调用链是否准确

发现问题时，先修复，再决定是否扩大抽查范围。

六、与现有技能的关系

• 与 dev-constraints：当项目缺少业务域文档时，dev-constraints 可引导进入本技能
• 与 dev-small-tool：查询真实表结构、索引、配置时优先使用它
• 与 task-control：多阶段文档生成任务必须注册
• 与 project-entry：本技能可作为项目初始化或上下文补齐任务的一条分支能力

七、验收清单

至少检查：

• 工作区目录结构完整
• README 存在且可读
• TECH-REF 存在且有关键入口/表/问题定位
• 每个目标业务域都有 -domain.md
• 没有明显行号引用
• 关键声明抽查已做

八、正式区整理建议

本技能默认只生成工作区版本，不自动覆盖正式区。

如果用户明确要求整理到正式区，可按以下方式处理：

1. 先人工审查 .codex/desc-work/{branch}/
2. 再同步到 docs/desc/
3. 同步时优先保留工作区中已核对过的内容

九、模板

创建文档时，优先参考 templates.md。