修炼AI技能
AI 教程 / AI 编程实战 / AI 代码理解：让模型读懂并讲解陌生代码

AI 代码理解：让模型读懂并讲解陌生代码

接手一个没写过代码库、排查别人留下的 bug、或者 review 一段看不懂的实现，是日常开发里最耗时的环节之一。AI 编程助手已经不只是补齐下一行代码，它能在你给出适当上下文后，把陌生代码翻译成人话。本文讲清楚 AI 能帮你做哪些解释任务、怎么写提示词才靠谱、以及一套可落地的工作流。

为什么读陌生代码很慢

读别人代码慢，通常不是因为语法，而是因为缺三样东西：

  • 全局结构。你不知道模块之间怎么连，只能从入口文件一行行顺着读，容易陷进细节。
  • 命名意图。变量名、函数名可能来自业务黑话，光看名字猜不出它服务哪个场景。
  • 调用关系。一个改动会影响哪些下游，得手动在编辑器里反复跳转、全局搜索才能拼出大致链路。

传统做法是先跑起来、打断点、看日志，再反过来推断结构。这个反馈链路很长，而且对新人尤其不友好。AI 的价值在于把「读代码」这件事前置：先让模型给出概览和假设，你再带着问题去验证，而不是从空白开始硬啃。

AI 能做的解释任务

把「理解代码」拆成具体任务，AI 在以下几类上已经相当可用。

生成架构概览

给模型一个目录结构或几个核心文件，它能总结出：这个仓库大概分几层、每层的职责、主数据流怎么走。这一步能帮你建立心智地图，知道该先读哪几个文件。

逐段与逐函数解释

选中一段看不懂的逻辑，让模型按行或按函数解释「这段在做什么、为什么这么做、有什么边界条件」。对于加密、并发、正则这类容易出错的代码尤其有用。

命名与意图推断

模型能结合上下文猜测含糊命名的含义，比如把「calc(x, y, flag)」解释成「根据用户类型和地区计算运费，flag 为 true 时免运费」。注意这是推断，不是事实，需要你回头确认。

调用关系与依赖图

让模型列出「谁调用了这个函数」「这个函数依赖哪些模块」「改动它会波及哪些地方」。部分工具（见下文）还能直接生成 Mermaid 或 PlantUML 的调用图。

主流工具在这几类任务上的侧重点不同：GitHub Copilot 在编辑器内用聊天解释选中代码；Claude 凭借大上下文窗口可以一次吃下整个仓库再回答；Cursor 强调对整库的检索与追踪；aider 用仓库地图把关键符号喂给模型。

高效提示词模板

模型解释得好不好，很大程度取决于你怎么问。三条原则。

给足上下文

不要只贴一段函数就问「这是什么」。告诉模型：这是什么语言、跑在什么框架里、这段代码属于哪个业务模块、你目前已理解到哪一步。上下文越具体，解释越贴合你的真实场景。

以下是一个用 FastAPI 写的订单服务片段，我刚接手这个项目，
还不了解它的鉴权流程。请先简述这段代码的职责，
再逐行解释 decorate 函数里那段校验逻辑在防什么。

限定范围与深度

明确你要概览还是细节，避免模型输出一堆你用不上的泛泛而谈。可以指定输出长度、目标读者（新人还是资深）、关注点（性能、安全还是可读性）。

只关注安全相关的问题，不要展开性能优化建议。
用三条要点总结风险，并给出对应的代码位置。

要求结构化输出

让模型用固定格式返回，方便你后续整理成文档或笔记。常见结构是：职责一句话、关键步骤列表、依赖与调用方、需要注意的坑。

请按以下结构输出：
1. 这段代码做什么（一句话）
2. 关键步骤（带行号）
3. 依赖与调用方
4. 我接下来该读哪个文件

推荐工作流

与其一次把整个仓库丢给模型，不如分层推进。

  1. 先要架构图。给目录结构和 README，让模型画一张模块关系图（Mermaid 即可），确认你对整体结构的理解没有大偏差。
  2. 再逐模块深入。挑一个你最关心的模块，让它解释入口函数和关键类。
  3. 带着问题追问。针对不清楚的点继续问，比如「这个异常在哪里被捕获」「这个缓存 key 怎么失效」。
  4. 让模型补文档。理解得差不多后，请它生成函数级 docstring 或一份模块说明，你再校对修正。
  5. 交叉验证。把模型的结论和代码实际运行、单元测试、日志对照，别全信。

这套流程的核心是先广后深、先假设后验证，让 AI 当导游而不是当裁判。

实战示例

假设你在仓库里看到下面这段 Python，不知道它在干什么。

def resolve(items, threshold):
    out = []
    seen = set()
    for it in items:
        if it.score < threshold:
            continue
        if it.uid in seen:
            continue
        seen.add(it.uid)
        out.append(it)
    return sorted(out, key=lambda x: x.score, reverse=True)

可以这样向模型提问：

下面这段 Python 函数来自一个推荐系统的候选排序模块，
请解释它的职责、每一步在过滤什么、以及最后排序的依据。
另外，指出两个潜在问题。

（在此粘贴上面的代码）

一个靠谱的回答应当指出：它先按阈值过滤低分候选，再用 uid 去重，最后按分数从高到低排序返回；潜在问题可能包括没有对空输入做保护、以及「seen」去重可能误伤同 uid 不同内容的候选。你需要做的，是回头确认「uid」在业务上的真实含义，判断去重是否符合预期。

理解之后，可以让模型补上 docstring：

def resolve(items, threshold):
    """从候选集中筛选并排序推荐项。

    先丢弃分数低于阈值的项，再按 uid 去重，
    最后按分数降序返回。
    """
    out = []
    seen = set()
    for it in items:
        if it.score < threshold:
            continue
        if it.uid in seen:
            continue
        seen.add(it.uid)
        out.append(it)
    return sorted(out, key=lambda x: x.score, reverse=True)

补上的注释仍要以代码实际行为为准，模型写的 docstring 若与实现不符，必须以实现为准去修正。

常见陷阱

用 AI 解释代码时，有几类错误最容易发生。

编造接口与不存在的函数

模型可能「脑补」出代码里并没有的函数、参数或配置项，说「这段代码调用了 validate_token 做校验」，而仓库里根本没有这个函数。遇到任何具体符号，都要在代码里搜一下确认存在。

过度自信地给出错误结论

模型解释得头头是道，不代表它读懂了。尤其在涉及并发、时区、浮点精度、边界条件时，错误结论往往写得非常确定。把它当成一个表达流利的同事，结论仍需你用测试或日志验证。

忽视版本与环境差异

同一段代码在不同依赖版本下行为可能不同。模型训练数据有截止时间，它给出的 API 用法可能已过时，涉及具体库时要核对官方文档。

上下文被截断导致误读

当仓库很大、只贴了片段时，模型看不到完整调用链，容易做出片面判断。要么给足相关文件，要么用支持整库检索的工具。

小结

AI 让理解陌生代码的成本大幅下降：先用它生成架构概览建立地图，再逐模块深入、带着问题追问，最后把结论整理成文档。关键是把模型当导游而非裁判，对具体符号和结论保持验证习惯，尤其警惕它编造接口和过度自信。配合合适的工具与提示词，读代码这件事可以从硬啃变成有方向的探索。

参考与延伸阅读

本文累计阅读 — 次