| name | docs-desc-generation |
| description | Codex 的业务域文档生成技能。适用于为 Java 项目初始化或补充 `docs/desc/` 业务域文档、建立领域上下文、生成技术速查和域文档骨架。当项目缺少业务域文档、需要建立知识库或需要补齐某个业务域说明时使用。 |
业务域文档生成
本技能负责生成和补充项目的业务域文档体系。它和 docs/codex/{version}/ 的需求/设计/计划/追踪文档不是一回事：
docs/desc/：长期业务上下文与领域知识库docs/codex/{version}/：某轮需求交付的阶段产物
一、开始执行
执行前先完成：
- 检查
.gitignore 是否包含 .codex/
- 按
task-control 规则注册本任务
- 确认本次是“初始化文档”还是“补某个域的文档”
二、工作区机制
使用 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/
四、文档编写约束
- 不写代码行号引用
- 不大段粘贴源码
- 没读过的代码不写结论
- 不确定的信息标记“待确认”
- 流程、表格、职责说明优先于代码摘抄
五、阶段执行
阶段0：骨架建立
输出：
- 工作区
README.md
- 工作区
TECH-REF.md
至少完成：
- 技术栈识别
- 分层架构识别
- 核心 Service 清单
- 业务入口清单
- 核心数据表清单
- 生成骨架文档
工作区建议路径：
.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：跨域补全
基于各域文档补充：
阶段3：全局优化
整体阅读工作区文档，统一：
阶段4：准确性抽查
至少抽查 1 到 2 个核心域：
- 状态枚举是否和代码一致
- 事件、线程池、锁名是否和代码一致
- 关键入口、关键调用链是否准确
发现问题时，先修复，再决定是否扩大抽查范围。
六、与现有技能的关系
- 与
dev-constraints：当项目缺少业务域文档时，dev-constraints 可引导进入本技能
- 与
dev-small-tool：查询真实表结构、索引、配置时优先使用它
- 与
task-control：多阶段文档生成任务必须注册
- 与
project-entry：本技能可作为项目初始化或上下文补齐任务的一条分支能力
七、验收清单
至少检查：
- 工作区目录结构完整
- README 存在且可读
- TECH-REF 存在且有关键入口/表/问题定位
- 每个目标业务域都有
-domain.md
- 没有明显行号引用
- 关键声明抽查已做
八、正式区整理建议
本技能默认只生成工作区版本，不自动覆盖正式区。
如果用户明确要求整理到正式区，可按以下方式处理：
- 先人工审查
.codex/desc-work/{branch}/
- 再同步到
docs/desc/
- 同步时优先保留工作区中已核对过的内容
九、模板
创建文档时，优先参考 templates.md。
