Software Design Doc Regenerator

面向软件详细设计文档重生成的 Codex Skill，用于从现有 DOCX、源代码仓库、Enterprise Architect（EA）模型或 XMI 导出、数据库结构、接口规范和部署配置中提取证据，重新生成风格一致、内容可追溯、技术事实更可靠的详细设计文档。

适用场景

• 现有详细设计文档由多人编写，章节风格、术语和粒度不一致。
• 文档套用了公司模板，但内容规范性不足，需要重新整理。
• 文档中的类图、组件图、时序图等来自 EA 截图，样式不统一或难以维护。
• 需要根据当前代码库、数据库、接口和部署配置校正文档内容。
• 需要把设计说明、图、表和代码证据建立对应关系，减少凭印象写文档的问题。

核心原则

这个 skill 不把详细设计文档当成普通文字润色任务，而是当成工程交付物处理：

• 所有重要设计结论必须来自代码、EA 模型、数据库、接口规范、配置或旧文档证据。
• 无法证明的内容必须标记为 needs-owner-input、legacy-doc-only 或 conflict。
• 优先生成可编辑的 PlantUML、Mermaid、Graphviz 或 draw.io 图源文件，而不是继续依赖截图。
• 先审计，再重写；先建立证据包，再生成正文。
• 保留 Markdown 审查版，便于 diff、人工确认和后续迭代。

推荐输入

优先提供以下材料：

1. 现有详细设计文档 .docx 和公司模板。
2. 对应源代码仓库，包括后端、前端、数据任务、测试、配置和部署文件。
3. EA 模型成果，优先提供 XMI/XML 导出；.eap、.eapx、.qea 也可以作为输入。
4. 数据库 DDL、迁移脚本、OpenAPI/Swagger、消息结构、部署清单、运维文档等。

典型产物

完整流程通常会生成：

• inventory.md / inventory.json：输入材料盘点。
• evidence-pack.json 或 evidence-pack.md：代码、EA、数据库、接口等证据包。
• design-doc-audit.md：旧文档质量审计。
• traceability-matrix.md：章节、结论和证据的追踪矩阵。
• diagrams/：可编辑图源文件及必要的渲染图。
• generated-design.md：审查版详细设计文档。
• generated-design.docx：需要时生成的 Word 文档。

使用方式

在 Codex 中直接引用：

使用 $software-design-doc-regenerator，基于这个 DOCX、代码库和 EA 导出，先做详细设计文档审计和输入证据盘点。

本 skill 附带一个轻量输入盘点脚本：

python3 scripts/inventory_project.py \
  --docx /path/to/current-design.docx \
  --code-root /path/to/source-repo \
  --ea /path/to/ea-export-or-model \
  --output-dir /path/to/output/inventory

多个代码库或 EA 输入可以重复传入 --code-root 和 --ea。

后续迭代方向

• 增强 Java/Spring、Vue/React、SQL、OpenAPI、Kubernetes 等源码解析。
• 增加 EA XMI 到 PlantUML/Mermaid 的结构化转换。
• 增加 DOCX 模板样式复用和章节编号校验。
• 增加面向公司详细设计模板的定制章节规范。