Towards Data Science

Three Techniques to Understand Your Codebase When Coding Agents Write the Code

8.5内容质量

TL;DR · AI 摘要

使用Claude Code等编码代理时,通过功能备忘录、PR审查和HTML解释器三种技术可有效理解代码库。

核心要点

  • 用Claude Code编写功能备忘录可记录代码逻辑与业务关联
  • 审查编码代理生成的PR能发现潜在架构问题
  • HTML可视化解释器可将复杂代码转化为交互式文档

结构提纲

按章节快速跳转。

  1. 编码代理使开发效率提升但带来理解挑战

  2. 用户超过5人时需考虑安全、SLA等复杂因素

  3. 用自然语言记录代码实现的业务逻辑

  4. 分析编码代理生成代码的架构合理性

  5. 将代码转化为可视化交互文档

思维导图

用一张图看清主题之间的关系。

查看大纲文本(无障碍 / 无 JS 友好)
  • 编码代理时代代码理解
    • 核心挑战
      • 架构理解缺失
      • 业务逻辑模糊
    • 解决方案
      • 功能备忘录
      • PR审查
      • HTML可视化

金句 / Highlights

值得收藏与分享的关键句。

#Claude Code#代码理解#AI编码#软件工程
打开原文

当编码代理编写代码时,理解代码库的三种技巧 | Towards Data Science

编程

当编码代理编写代码时,理解代码库的三种技巧

学习如何使用 Claude Code 编写功能备忘录、审查拉取请求以及构建可视化 HTML 解释器,从而理解你的代理所交付的内容

Eivind Kjosbakken

2026年11月3日

7分钟阅读

在 Google 上关注我们

分享

更好地理解代码库的封面图片

在本文中,我将讨论如何在使用编码代理编写所有代码时更好地理解你的代码库。图片由作者提供。

使用 Claude Code 后,我写的代码量可能是以前的五十倍。我正在合并更多拉取请求,编写更多行代码,并整体推动更多功能。

只是几年前,开发人员工作的主要瓶颈仅仅是编写代码本身。你必须花费大量时间编写正确的代码,有时还要花时间研究新功能、需要安装的软件包以及需要通过 Stack Overflow 解码的错误。

然而,现在情况完全改变了,你可以直接使用 Claude Code 或类似的编码代理来实现功能。

我强烈建议你通过这样的编码代理编写所有代码。然而,我想在此提出一个观点:现在你使用编码代理编写所有代码、构建功能并修复错误后,理解能力现在已成为稀缺资源。

你对应用程序中不同功能的理解程度如何?你对导致错误的原因以及修复为何有效的理解程度如何?为什么这是一个稳健的修复方案——一个不会在其他地方引发问题的修复方案?

你对这些的理解程度将决定你构建可扩展应用程序和开发用户所需功能的能力。

这幅信息图突出了本文的主要内容。我将讨论我用来更好地理解代码库的三种具体技术。图片由 ChatGPT 提供。

为什么需要关注代码理解?

现在,你可能会问自己一个初步问题:为什么需要关注代码理解?

尤其是在人工智能时代,编码代理可以为你编写代码,可以修复任何出现的错误,等等。从纸面上看,你似乎甚至不需要知道如何做到所有这些就能构建一个有效的应用程序。

然而,我认为这与现实相去甚远。我认为我上一段落中描述的系统只有在你为少数用户或仅为自己构建内部应用且完全不进行扩展时才有效。

然而,一旦你超过五名用户,外部人员开始使用它,你就需要对外部人员进行培训;你必须考虑数据安全;你必须考虑不同个人的不同偏好;你必须拥有统一的 UI 系统;你必须遵守特定的 SLA;等等。在没有对代码库有任何理解的情况下随意编码根本行不通。

你的编码代理可以做到这些,但你需要理解应用程序的主要脉络:不同功能是什么,它们如何运作,如何优化,不同功能如何与其他功能交互等。这就是为什么我认为理解如此重要。

现在我们进入文章的正文部分,即我将介绍的三种技术,帮助你更好地理解代码库。这些技术的共同点在于,你通过某种方式利用编码代理来构建理解,而不是手动阅读代码。

我将讨论的三种主要技术是:

  • 在构建功能前制作备忘录
  • 使用 Claude Code 审查他人的 PRs
  • 使用 Claude 为特定功能构建 HTML 备忘录

在构建功能前制作备忘录

这张图片展示了功能备忘录可能的样式。你与编码代理一起撰写详细的规格说明,确保编码代理与你的意图保持一致,并且你理解编码代理将构建的内容。图片由 ChatGPT 提供。

我想要介绍的第一种技术是在构建功能前制作备忘录。我认为这在正确实现功能和理解实际构建内容方面都很重要。在构建任何内容之前,你应该启动大量研究代理,调查这些功能如何构建到应用程序中,实现它们的不同选项,实现功能时需要考虑的不同优缺点,以及其他需要考虑的论点。

最好的理解方式是让编码代理在构建功能前创建备忘录,以确保你真正理解正在构建的内容、你构建内容的含义以及需要考虑的其他事项。备忘录还应存储你做出的任何决策。例如,如果你在构建功能时选择方案 A 或方案 B,并用于做出该决策的论据。

使用 Claude Code 审查他人的 PRs

在这张图片中,我展示了使用 Claude Code 或其他编码代理进行 PR 审查时,A PR 审查可能的样子。我的编码代理在左侧,GitHub PR 页面在右侧,尝试理解拉取请求。图片由 ChatGPT 提供。

另一种你可以利用的重要技术是使用 Claude Code 审查他人的 PRs。现在,我意识到在某些情况下,手动审查拉取请求是必要的。这可能发生在你触及代码关键部分时,你认为逐行人工审查比使用编码代理审查更有价值。

但在大多数情况下,我认为你并不需要人工审查代码。在大多数情况下,让独立的编码代理在创建拉取请求前审查代码就足够了。我认为这涵盖了约 80% 的拉取请求。然后有一些半关键的拉取请求,可能需要其他人查看,以确认是否有遗漏或需要考虑的内容。在这些情况下,我认为让这位独立人员不必逐行审查,而是让他们的编码代理查看 PR 并与编码代理讨论,以自行构建理解就足够了。

他们应该通过创建 PDF 或 HTML 文件来建立理解,例如解释功能、工作原理、功能开发过程中做出的不同决策、优缺点等。这样,审阅者可以真正理解 PR 实际做了什么,并更容易对 PR 提供反馈,同时建立对功能工作方式的理解,从而更深入地了解代码库。这将帮助他们在未来开发其他功能、修复漏洞时更加得心应手。

使用 Claude 为特定功能构建 HTML 备忘录

这张图片展示了创建 HTML 备忘录可能的样子,用于理解应用程序中的特定功能。图片由 ChatGPT 生成。

最后,我想介绍的技巧是为应用程序中的特定功能构建 HTML 备忘录。我强烈建议您在此处尽可能具体。我曾尝试过一种更广泛的方法,即直接要求 Claude 生成一个完整的 HTML 文件,解释整个代码库的工作原理等。但后来我意识到这种方法效果并不理想。首先,这给 Claude 提供了过多的信息。

因此,对我更有效的方法是让 Claude 聚焦于代码库的特定部分。这可以是代码库中的某个具体页面,或者跨多个页面使用的某个具体服务。我再次建议您尽可能具体。将 Claude 指向代码库的这一部分,让它生成一个动画 HTML 备忘录,解释其工作原理。应尽可能多地使用可视化内容,仅在必要且文本显然能帮助人类更好地理解功能时才添加文字。

我通常的做法是,每次在等待编码代理工作时有空闲时间,例如,我会查看一个新功能或近期可能发生变化的功能,要求 Claude 为它生成 HTML 备忘录,然后花几分钟阅读。根据功能的复杂程度,我可能花费 5 分钟,也可能花费 15-20 分钟。如果我有任何疑问,我会在聊天中与 Claude 讨论。通过这种方式,每次有空闲时间都进行这样的操作,我就能逐层逐步地建立对整个代码库的理解。

结论

在本文中,我讨论了在人工智能时代如何更好地理解代码库,这个时代中编码代理负责编写所有代码,而人类仅负责审阅代码并协调编码代理。我分享了三种主要方法来深入理解我的代码库。

第一种方法是在构建功能之前创建功能备忘录,这样我能在功能构建之前真正理解自己要构建的内容。第二种方法是尝试使用 Claude Code 审阅他人的拉取请求。我实现这一点的方式是启动一个独立的 Claude 会话,将其指向我们正在审阅的 PR 的 GitHub 页面,并与 Claude Code 讨论该 PR,从而理解拉取请求的作用。这有助于我建立对即将进入代码库的代码的理解。

最后,我还讨论了为应用中已有的特定功能单独构建 HTML 备忘录的做法。每当有空闲时间时,我都会定期这么做,比如在等待 Claude Code 的输出结果时。随着时间推移,当我为应用中的每个功能或服务都完成这样的梳理后,我将对整个代码库形成全面的理解。需要特别注意的是,代码库当然会持续发生变化,因此保持对代码库理解的持续更新至关重要。

👋 联系方式

👉 我的免费电子书和网络研讨会:

🚀 通过大语言模型将工程效率提升 10 倍(免费 3 天电子邮件课程)

📚 获取我的视觉语言模型电子书

💻 我的视觉语言模型网络研讨会

👉 在社交媒体上找到我:

💌 Substack

🔗 LinkedIn

🐦 X / Twitter