用 AI 向团队解释复杂代码：五步 prompt 工作流
写代码是外化你的思考，解释代码却要从零重建别人的心智模型。你知道函数做什么，难的是知道评审者、初级队友、值班工程师不知道什么——这个差距就是沟通破裂的地方。AI 缩小差距的方式：按需、几秒内、在多个抽象层级生成解释。
Step 1：贴代码，设定受众
最大错误是用"解释这段代码"这种泛化 prompt——输出几乎总是定错层级。告诉模型你为谁写：
你是一位资深工程师，向一位懂 Python 但从未接触过此服务的中级队友解释代码。
说明这个函数做什么、为什么这样组织、调用者使用前需要知道什么。
要具体。除非定义，否则避免术语。控制在 150 词以内。
[粘贴函数]
约束（150 词以内、避免术语除非定义）在做实际工作。没有它们你得到一本教科书；有它们你得到能直接贴进 PR 评论的东西。
Step 2：生成"心智模型"摘要
有通俗解释后，要一句能记住的心智模型：
现在给我一句话，抓住这个函数的核心理念模型。
格式："把这件事想成 [类比或简短描述]。"
对 token bucket 限流器的示例输出："把它想成一个漏水桶——token 以固定速率补充，每个请求花一个；桶空时请求被拒绝直到重新填满。"这一句话对团队理解的作用大于三段的行内注释。
Step 3：为不同读者产出分层解释
作者负责处理金融事件的服务，同一段逻辑要被后端工程师、QA 工程师、产品经理读同一份 wiki 页：
从三个层级解释下面的代码：
1. 后端工程师：关注实现细节、边界情况、性能特征。
2. QA 工程师：关注输入、输出、要测的失败模式。
3. 非技术干系人：用通俗语言关注代码为用户做了什么。
每段清晰标注，100 词以内。
[粘贴代码]
输出是可直接放进文档、工单或 wiki 的三段，除了快速检查不需要编辑。
Step 4：让 AI 找出令人意外的地方
这是多数工程师跳过的步骤。复杂代码有隐藏 gotcha——作者知道但从未记录的假设和边界情况：
读下面的代码告诉我：
- 第一次读的新工程师会惊讶什么？
- 这段代码做了哪些签名里看不出来的假设？
- 如果这些假设变了会坏什么？
[粘贴代码]
输出作为文档里"Caveats"或"Watch out for"节的基础。30 秒换来下一个工程师一小时不困惑。
Step 5：把解释变成行内注释
最后闭环：生成可以随代码提交的注释：
用你刚写的解释，为下面的代码生成行内注释。
规则：注释"为什么"不注释"什么"——假设读者能读代码。
用完整句子。尽量每行一条。别逐行注释——只注不明显的。
[粘贴代码]
产出的是真正有用的注释，而不是"// 把 i 加 1"这种噪音。
组合起来
完整工作流：受众定向解释 → PR 评论或 Slack 消息；一句心智模型 → 团队 wiki、README 头部；分层解释 → wiki 页或工单描述；意外与假设 → 文档"Caveats"节；行内注释 → 提交进仓库。每步不超过两分钟，总投入不到十分钟，换来以前要一小时、或根本没写的文档。
实践建议：把受众和约束（长度、术语、格式）写进 prompt 而非靠模型猜；输出只做 sanity check 不要全文重写；"意外与假设"步骤对遗留代码价值最高，值得每次都跑。
来源：How to Explain Complex Code to Your Team with AI - DEV Community