背景

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

快速开始

以 pi-mono 这个 13k star 的仓库为示例
1. 打开 opencode/claude code + @MiniMax_AI M2.7
2. 输入如下的提示词, 回车
3. 打开 vscode 安装  markdown viewer extension 扩展, 提升阅读体验

工具

提示词

我是一个不懂技术的产品经理，我希望通过标准 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://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. 文档生成核心步骤

1. 代码仓库分析：用@Explore智能体快速扫描文件结构、核心接口、数据流转，明确业务边界；
2. 场景拆分：结合业务实际（如水果零售连锁的 “库存预警”“门店补货”），补充核心场景，避免遗漏；
3. 图表绘制：优先保证 Mermaid 语法正确，逆向流程必须覆盖 “失败、异常、补偿”，不遗漏任何分支；
4. 文档校验：重点检查 3 点 ——Mermaid 无圆括号、图表能正常渲染、逻辑覆盖全场景（含异常）；
5. 技能复用：在 TRAE 中导入 “技术文档撰写 Skill”，标准化输出格式，提升效率。

2. 核心避坑点

• ❌ 禁止只画正向流程：必须单独绘制逆向流程活动图，覆盖所有异常场景；
• ❌ 禁止 Mermaid 语法错误：圆括号是渲染崩溃核心原因，用[状态：待支付]替代(状态：待支付)；
• ❌ 禁止假设不标注：所有合理假设必须在文档中明确，避免后续歧义；
• ❌ 禁止脱离业务：优化点需结合实际场景（如水果零售的 “库存预测 AI 化”），不空谈技术。

成果落地与应用

1. 文档交付：生成的结构化文档可直接用于产品需求沟通、IT 系统设计、业务流程优化，支撑水果零售连锁、供应链管理等场景落地；
2. 技能沉淀：将本次生成的提示词、文档规范封装为 TRAE Skill，后续复用可节省 50% 以上文档生成时间；
3. 迭代优化：结合业务实际运行反馈，补充新场景（如 “会员积分兑换”“供应链溯源”），持续完善业务蓝图。

Skills

在Trae中自动调用Skills

Skill在这儿

https://gitmap.simprr.com/

参考

Trae Skills

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