代码工程文档生成：从代码到战略蓝图的 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 图表系统性梳理业务逻辑。
请你从“业务场景”维度出发进行分析，而不是只做功能拆解。
一、必须按【业务场景】拆分
对每一个核心业务场景单独分析，例如：
– 下单场景
– 支付场景
– 发货场景
– 售后场景
– 退款场景
– 对账场景
– 审核场景
– 风控拦截场景
（如有必要请自行补充）
每个场景必须包含：
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 更标准）
Jules实践
我们在Jules平台异步实现
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在这儿
参考
Trae Skills
https://docs.trae.ai/ide/skills?_lang=zh#66adbc65
文章摘自：https://www.cnblogs.com/wintersun/p/19780748
京ICP备14020293号-4