代码工程文档AI生成

背景

将代码仓库文档生成升级为战略级业务蓝图，核心是用标准化业务场景拆分 + 全量 UML 图表 + 结构化文档，让不懂技术的产品 / 管理者也能一眼看懂业务走向，同时支撑 IT 系统设计与数字化落地。阅读程序代码仓库的工作可全部交由AI完成，预先让AI生成详细的文档及图表，实际应用效果良好。

快速开始

以 pi-mono 这个 13k star 的仓库为示例1. 打开 opencode/claude code + @MiniMax_AI M2.7

2. 输入如下的提示词, 回车3. 打开 vscode 安装 markdown viewer extension 扩展, 提升阅读体验

工具

工具 / 能力	核心作用	关键配置 / 操作
opencode/claude code + @MiniMax_AI M2.7	代码仓库深度分析 + 多智能体协作 + 复杂任务拆解	1. 安装并配置 OpenCode，连接 MiniMax M2.7 模型；2. 用/connect配置 API 密钥，左下角切换模型；3. 内置 Build/Plan/General/Explore 智能体，@唤起子智能体（如@general分析复杂任务）
VS Code + Markdown Viewer Extension	文档预览 + Mermaid 图表渲染	1. 安装扩展并重启 VS Code；2. 开启实时预览，快速校验图表渲染
TRAE AI Skills	标准化技能封装 + 研发流程提效	1. 对话生成SKILL.md（如 “创建代码文档生成 Skill”）；2. 导入预设技能（技术文档撰写、代码审查等），一键复用专业流程
Google Jules	异步代码仓库操作 + PR 自动提交	1. 授权 GitHub 访问，克隆目标仓库；2. 下达指令生成文档，自动创建 PR 审阅

提示词

我是一个不懂技术的产品经理，我希望通过标准 UML 图表系统性梳理业务逻辑。请你从“业务场景”维度出发进行分析，而不是只做功能拆解。一、必须按【业务场景】拆分对每一个核心业务场景单独分析，例如：下单场景支付场景发货场景售后场景退款场景对账场景审核场景风控拦截场景（如有必要请自行补充）每个场景必须包含：场景目标参与角色触发条件前置条件正向流程（主路径）逆向流程（撤销 / 失败 / 异常 / 补偿流程）状态变化数据流转路径系统边界可优化点二、每个场景必须画完整 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业务.md04-数据模型与状态流转.md05-异常与补偿机制.md06-优化与扩展设计.md四、表达风格要求面向完全不懂技术的产品经理每一步都解释“为什么这样设计”逻辑必须极其清晰图表必须足够大、足够细即使不懂技术也能一眼看懂业务走向五、重要补充如果发现业务信息不完整，请主动做合理假设，并在文档中标注“假设前提”。请把它当成战略级产品蓝图来做，越详细越好。⚠️ 严格约束条件 (Constraints)Mermaid 语法防错（致命红线）：在编写任何 Mermaid 代码时，绝对禁止在节点定义或描述中使用英文圆括号() 或中文圆括号（），这会导致图表渲染崩溃。使用中括号[]或直接换行代替。Mermaid 标准规范中，note 块应以 end note 结尾，而非 end（虽然部分渲染器兼容 end，但 end note 更标准）

Jules实践

我们在Jules平台异步实现

https://jules.google.com/

https://github.com/megadotnet/WeKnora/blob/main/docs/explain/01_core_rag_architecture.md

操作补充说明

工具使用：确保opencode/claude code + @MiniMax_AI M2.7工具正常运行，若出现无法生成文档/图表的情况，可重启工具或检查网络连接；

扩展安装：VS Code的markdown viewer extension扩展安装后，需重启VS Code才能生效，生效后可直接预览markdown文档及Mermaid图表；

文档校验：生成文档后，需检查以下内容：Mermaid语法是否正确（无圆括号）、图表是否能正常渲染、内容是否符合提示词要求、逻辑是否清晰、无技术术语歧义；

异常处理：若AI生成的文档存在逻辑缺失、图表错误等问题，可重新提交提示词，补充说明缺失的内容，让AI重新生成。

生成的文档示例

https://github.com/megadotnet/WeKnora/blob/main/docs/explain/01_core_rag_architecture.md

关键操作规范与避坑指南

1. 文档生成核心步骤

代码仓库分析：用@Explore智能体快速扫描文件结构、核心接口、数据流转，明确业务边界；

场景拆分：结合业务实际（如水果零售连锁的 “库存预警”“门店补货”），补充核心场景，避免遗漏；

图表绘制：优先保证 Mermaid 语法正确，逆向流程必须覆盖 “失败、异常、补偿”，不遗漏任何分支；

文档校验：重点检查 3 点 ——Mermaid 无圆括号、图表能正常渲染、逻辑覆盖全场景（含异常）；

技能复用：在 TRAE 中导入 “技术文档撰写 Skill”，标准化输出格式，提升效率。

2. 核心避坑点

❌ 禁止只画正向流程：必须单独绘制逆向流程活动图，覆盖所有异常场景；

❌ 禁止 Mermaid 语法错误：圆括号是渲染崩溃核心原因，用[状态：待支付]替代(状态：待支付)；

❌ 禁止假设不标注：所有合理假设必须在文档中明确，避免后续歧义；

❌ 禁止脱离业务：优化点需结合实际场景（如水果零售的 “库存预测 AI 化”），不空谈技术。

成果落地与应用

文档交付：生成的结构化文档可直接用于产品需求沟通、IT 系统设计、业务流程优化，支撑水果零售连锁、供应链管理等场景落地；

技能沉淀：将本次生成的提示词、文档规范封装为 TRAE Skill，后续复用可节省 50% 以上文档生成时间；

迭代优化：结合业务实际运行反馈，补充新场景（如 “会员积分兑换”“供应链溯源”），持续完善业务蓝图。

Skills

在Trae中自动调用Skills

Skill在这儿

https://gitmap.simprr.com/

参考

Trae Skills

https://docs.trae.ai/ide/skills?_lang=zh#66adbc65