代码工程文档生成：从代码到战略蓝图的 AI 化实践

廖彗云 发表于 2026-3-27 14:44:59

<h2>代码工程文档生成：从代码到战略蓝图的 AI 化实践</h2><h2>背景</h2> 将代码仓库文档生成升级为战略级业务蓝图，核心是用标准化业务场景拆分 + 全量 UML 图表 + 结构化文档，让不懂技术的产品 / 管理者也能一眼看懂业务走向，同时支撑 IT 系统设计与数字化落地。阅读程序代码仓库的工作可全部交由AI完成，预先让AI生成详细的文档及图表，实际应用效果良好。快速开始 以 pi-mono 这个 13k star 的仓库为示例 
1. 打开 opencode/claude code + @MiniMax_AI M2.7 2. 输入如下的提示词, 回车 
3. 打开 vscode 安装 markdown viewer extension 扩展, 提升阅读体验<h2>工具</h2><table border="0" cellspacing="0" cellpadding="0"><tbody><tr><td>工具 / 能力</td><td>核心作用</td><td>关键配置 / 操作</td></tr><tr><td>opencode/claude code + @MiniMax_AI M2.7</td><td>代码仓库深度分析 + 多智能体协作 + 复杂任务拆解</td><td>1. 安装并配置 OpenCode，连接 MiniMax M2.7 模型；2. 用/connect配置 API 密钥，左下角切换模型；3. 内置 Build/Plan/General/Explore 智能体，@唤起子智能体（如@general分析复杂任务）</td></tr><tr><td>VS Code + Markdown Viewer Extension</td><td>文档预览 + Mermaid 图表渲染</td><td>1. 安装扩展并重启 VS Code；2. 开启实时预览，快速校验图表渲染</td></tr><tr><td>TRAE AI Skills</td><td>标准化技能封装 + 研发流程提效</td><td>1. 对话生成SKILL.md（如 “创建代码文档生成 Skill”）；2. 导入预设技能（技术文档撰写、代码审查等），一键复用专业流程</td></tr><tr><td>Google Jules</td><td>异步代码仓库操作 + PR 自动提交</td><td>1. 授权 GitHub 访问，克隆目标仓库；2. 下达指令生成文档，自动创建 PR 审阅</td></tr></tbody></table><h2>提示词</h2>我是一个不懂技术的产品经理，我希望通过标准 UML 图表系统性梳理业务逻辑。请你从“业务场景”维度出发进行分析，而不是只做功能拆解。一、必须按【业务场景】拆分对每一个核心业务场景单独分析，例如：- 下单场景- 支付场景- 发货场景- 售后场景- 退款场景- 对账场景- 审核场景- 风控拦截场景（如有必要请自行补充）每个场景必须包含：1️⃣ 场景目标 2️⃣ 参与角色 3️⃣ 触发条件 4️⃣ 前置条件 5️⃣ 正向流程（主路径） 6️⃣ 逆向流程（撤销 / 失败 / 异常 / 补偿流程） 7️⃣ 状态变化 8️⃣ 数据流转路径 9️⃣ 系统边界 可优化点 二、每个场景必须画完整 UML 图（大量 Mermaid）必须使用标准 UML 图类型，并且区分图类型：- 用例图（Use Case Diagram）- 活动图（Activity Diagram，分别画正向和逆向流程）- 时序图（Sequence Diagram）- 状态图（State Machine Diagram）- 类图（Class Diagram，如涉及核心对象）- 组件图（Component Diagram）- 部署图（如涉及多系统）要求：- 正向流程必须单独画一张活动图- 逆向流程必须单独画一张活动图- 不能只画 happy path- 必须包含异常分支- 必须包含条件判断- 必须体现系统边界- 必须标注角色- 必须体现状态流转三、文档输出要求生成多篇逻辑详尽的说明文档，输出到：docs/explain/*.md建议结构如下：# 01-整体业务蓝图.md- 业务全景图- 场景划分- 系统边界# 02-场景A-XXX业务.md（包含正向 + 逆向完整UML图）# 03-场景B-XXX业务.md# 04-数据模型与状态流转.md# 05-异常与补偿机制.md# 06-优化与扩展设计.md四、表达风格要求- 面向完全不懂技术的产品经理- 每一步都解释“为什么这样设计”- 逻辑必须极其清晰- 图表必须足够大、足够细- 即使不懂技术也能一眼看懂业务走向五、重要补充如果发现业务信息不完整，请主动做合理假设，并在文档中标注“假设前提”。请把它当成战略级产品蓝图来做，越详细越好。## ⚠️ 严格约束条件 (Constraints)- **Mermaid 语法防错（致命红线）**：在编写任何 Mermaid 代码时，**绝对禁止**在节点定义或描述中使用英文圆括号 `()` 或中文圆括号 `（）`，这会导致图表渲染崩溃。使用中括号 `[]` 或直接换行代替。- Mermaid 标准规范中，note 块应以 end note 结尾，而非 end（虽然部分渲染器兼容 end，但 end note 更标准）<h2>Jules实践</h2>我们在Jules平台异步实现https://jules.google.com/https://github.com/megadotnet/WeKnora/blob/main/docs/explain/01_core_rag_architecture.md<h2>操作补充说明</h2><ul><li>工具使用：确保opencode/claude code + @MiniMax_AI M2.7工具正常运行，若出现无法生成文档/图表的情况，可重启工具或检查网络连接；
</li><li>扩展安装：VS Code的markdown viewer extension扩展安装后，需重启VS Code才能生效，生效后可直接预览markdown文档及Mermaid图表；
</li><li>文档校验：生成文档后，需检查以下内容：Mermaid语法是否正确（无圆括号）、图表是否能正常渲染、内容是否符合提示词要求、逻辑是否清晰、无技术术语歧义；
</li><li>异常处理：若AI生成的文档存在逻辑缺失、图表错误等问题，可重新提交提示词，补充说明缺失的内容，让AI重新生成。</li></ul>生成的文档示例https://github.com/megadotnet/WeKnora/blob/main/docs/explain/01_core_rag_architecture.md <h2>关键操作规范与避坑指南</h2><h5>1. 文档生成核心步骤</h5><ol><li>代码仓库分析：用<code>@Explore</code>智能体快速扫描文件结构、核心接口、数据流转，明确业务边界；
</li><li>场景拆分：结合业务实际（如水果零售连锁的 “库存预警”“门店补货”），补充核心场景，避免遗漏；
</li><li>图表绘制：优先保证 Mermaid 语法正确，逆向流程必须覆盖 “失败、异常、补偿”，不遗漏任何分支；
</li><li>文档校验：重点检查 3 点 ——Mermaid 无圆括号、图表能正常渲染、逻辑覆盖全场景（含异常）；
</li><li>技能复用：在 TRAE 中导入 “技术文档撰写 Skill”，标准化输出格式，提升效率。 </li></ol><h5>2. 核心避坑点</h5><ul><li>❌ 禁止只画正向流程：必须单独绘制逆向流程活动图，覆盖所有异常场景；
</li><li>❌ 禁止 Mermaid 语法错误：圆括号是渲染崩溃核心原因，用<code>[状态：待支付]</code>替代<code>(状态：待支付)</code>；
</li><li>❌ 禁止假设不标注：所有合理假设必须在文档中明确，避免后续歧义；
</li><li>❌ 禁止脱离业务：优化点需结合实际场景（如水果零售的 “库存预测 AI 化”），不空谈技术。 </li></ul><h2>成果落地与应用</h2><ol><li>文档交付：生成的结构化文档可直接用于产品需求沟通、IT 系统设计、业务流程优化，支撑水果零售连锁、供应链管理等场景落地；
</li><li>技能沉淀：将本次生成的提示词、文档规范封装为 TRAE Skill，后续复用可节省 50% 以上文档生成时间；
</li><li>迭代优化：结合业务实际运行反馈，补充新场景（如 “会员积分兑换”“供应链溯源”），持续完善业务蓝图。</li></ol><h2>Skills</h2>在Trae中自动调用SkillsSkill在这儿https://gitmap.simprr.com/ <h2>参考</h2>Trae Skillshttps://docs.trae.ai/ide/skills?_lang=zh#66adbc65 来源：程序园用户自行投稿发布，如果侵权，请联系站长删除 免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！

页: [1]

程序园's Archiver

代码工程文档生成：从代码到战略蓝图的 AI 化实践