# 智能体工程模式 12：按顺序讲解代码

作者：Hex4C59 · 发布于 2026-10-11

原文：https://hex4c59.cc/translations/agentic-engineering-patterns-linear-walkthroughs/


> **译文信息**
>
> - 原文：[Linear walkthroughs](https://simonwillison.net/guides/agentic-engineering-patterns/linear-walkthroughs/)
> - 作者：Simon Willison
> - 中文翻译与整理：Hex4C59（AI 辅助）
> - 翻译整理：2026-10-11
>
> 本文为非官方中文译文，依据提供的原文正文翻译。正文中的「我」、项目经历和学习效果均指原作者；工具和模型名称保留原文记录。译者未执行示例命令或运行 Present 应用。

有时，让编程智能体有条理地讲解一个代码库，会很有帮助。

你可能需要尽快熟悉一份已有代码，也可能忘记了自己写过的代码的细节，或者整个项目都是通过 Vibe Coding 做出来的，现在需要弄明白它到底如何工作。

配合合适的智能体运行框架（harness），前沿模型能够生成详细的讲解，帮助你理解代码的工作方式。

## 使用 Showboat 和 Present 的示例 {#an-example-using-showboat-and-present}

最近，我在 Mac 上使用 Claude Code 和 Opus 4.6，通过 [Vibe Coding 做了一个 SwiftUI 幻灯片演示应用](https://simonwillison.net/2026/Feb/25/present/)。

当时，我要做一场演讲，介绍 2025 年 11 月至 2026 年 2 月间前沿模型的进展。我喜欢在演讲里至少安排一个小花样，也就是一个 [STAR 时刻](https://simonwillison.net/2019/Dec/10/better-presentations/)——Something They'll Always Remember，让听众一直记得的瞬间。这一次，我决定在演讲结束时揭晓：播放这些幻灯片的应用本身，就是 Vibe Coding 能做到什么的一个例子。

我把代码发布到 [GitHub](https://github.com/simonw/present)，随后才意识到，自己根本不知道它实际上是怎样工作的。整个应用都是我靠提示词做出来的，这里有[部分会话记录](https://gisthost.github.io/?bfbc338977ceb71e298e4d4d5ac7d63c)，而我完全没有关注它写出的代码。

于是，我启动了一个新的网页版 Claude Code 实例，让它访问我的仓库，并输入以下提示词：

> 阅读源码，然后规划一份按顺序展开的代码讲解，详细解释整个应用如何工作。
>
> 接着运行「`uvx showboat –help`」来了解 Showboat。使用 Showboat 在仓库中创建一个 `walkthrough.md` 文件，并在其中完成讲解。用 `showboat note` 添加说明；用 `showboat exec` 配合 `sed`、`grep`、`cat` 或任何你需要的工具，加入正在讲解的代码片段。

> **译者注：** 提示词中的 `–help` 保留了原文的长横线排印。复制运行时，应使用两个半角连字符，即 `uvx showboat --help`。

[Showboat](https://github.com/simonw/showboat) 是我开发的一个工具，用来帮助编程智能体撰写能够展示其工作过程的文档。这里可以查看 [showboat --help 的输出](https://github.com/simonw/showboat/blob/main/help.txt)。这份帮助信息经过专门设计，包含模型使用工具所需了解的全部内容。

`showboat note` 命令向文档添加 Markdown 内容。`showboat exec` 接收一条 shell 命令，执行它，然后把命令和输出一起加入文档。

我要求它使用「`sed`、`grep`、`cat` 或任何你需要的工具，加入正在讲解的代码片段」，是想让这些工具直接从源码中读取片段，避免 Claude Code 手动复制时引入幻觉或错误。

这种做法效果非常好。这是 [Claude Code 使用 Showboat 生成的文档](https://github.com/simonw/present/blob/main/walkthrough.md)。它详细讲解了全部六个 `.swift` 文件，清楚地解释了代码如何工作，也提供了能够据此开展工作的具体说明。

仅仅阅读这份文档，我就学到了很多 SwiftUI 应用的组织方式，也掌握了一些 Swift 语言本身的具体知识。

如果你担心 LLM 会拖慢你学习新技能的速度，我强烈建议采用这样的做法。即便是一个花了大约 40 分钟、通过 Vibe Coding 做出来的玩具项目，也能成为探索新技术生态、学到有趣新技巧的机会。

---

[上一篇原文：让智能体执行手动测试](https://simonwillison.net/guides/agentic-engineering-patterns/agentic-manual-testing/) · [下一篇原文：交互式讲解](https://simonwillison.net/guides/agentic-engineering-patterns/interactive-explanations/)