我不再逐行看 AI 写的代码了

文中的经历做了抽象，具体实现不便展开，只讲做法和体会。

离开黑湖以后，我在一家初创公司做了几个月 iOS 开发。那几个月，代码大多由 AI 写，我自己写得很少。这几个月改变最大的，不是我会了 Swift，而是我写代码的方式。

以前 AI 每改一次，我都要打开 VS Code，把 git diff 左右对照着一行行看；commit 信息也是自己写，一天能花掉半天。现在我基本不看了。

先说前提：给 AI 更多信任

一直盯着 git diff，潜台词其实是：我不太信任 AI 写的东西。

换个角度想。你是一个产品 leader 或者主管，把任务分给手下的人。你不会坐在他旁边看他敲每一行代码，而是跟他讲清楚要做什么，最后验收他做出来的整个功能。

现在 AI 就是那个手下。它的能力已经堪比顶级的博士生，知道的东西很多，比大部分人都聪明。既然这样，就可以信任它的工作，把自己放到主管的位置上：验收从功能出发，代码细节不用读那么久。

不信任的代价很实在：你会很累，速度也慢。AI 一分钟写完的东西，你花半小时逐行看，瓶颈就成了你自己。

信任不等于不管，也不等于自己什么都不懂（这点放在第 9 条说）。主管也要把任务讲清楚、看结果、对上线的东西负责。下面的小方法，都是从这个前提出发的：怎么把任务交代清楚，怎么验收，哪些事还得自己把关。

1. 先聊方案，再让它写

动手前，先跟 AI 把方案聊清楚：要改哪些地方、怎么改、有什么风险。方案对了，代码大概率不会偏；方案错了，diff 看得再仔细也救不回来。

我现在的顺序是：说清楚要什么 → 让 AI 讲它打算怎么做 → 我挑毛病 → 它动手 → 我大致扫一眼实现。

2. 按功能验收，而不是逐行读代码

AI 写完以后，我先看功能对不对：点一遍、跑一遍、看结果。实现只是扫一眼，看有没有明显走错的路。

要求 AI 交结果，而不是说“做完了”：跑过的测试、构建结果、截图。Claude Code 团队也是这么做的，他们在讲自己怎么审代码的文章里说，开 PR 之前就让 Claude 跑测试、构建，或者拿截图和设计稿对比，再开一个新的 Agent 来审改动¹。Anthropic 的官方建议里，也把“给 Claude 一个它能自己跑的检查”列为最重要的几件事之一²。

但要注意：测试通过不等于正确。有人让 AI 重写了一个 SQLite，能编译、测试全过，按主键查 100 行却比原版慢两万多倍³。所以验收时，性能和边界情况也要试。

3. commit 交给 AI 写

让 AI 写 commit 信息：一句标题，加几条要点，最后署名是哪个 Agent、哪个模型写的。

这样做省时间，而且 AI 写得比人全。以后想知道某处为什么这样改，翻 commit 就能找到当时的原因。

4. 在仓库里放一份给 AI 看的说明

在项目根目录放一个 AGENTS.md。这是很多 AI 编程工具共同认的格式⁴；Claude Code 读的是 CLAUDE.md，在里面写一行 @AGENTS.md，两边就共用同一份。

写这些：

• 怎么跑测试、怎么构建、怎么检查；
• 代码里容易误导人的地方，比如“这个旧写法别再学”；
• 团队定下来、但代码里看不出来的决定；
• 已经纠正过 AI 两次的事。

这四条来自 Anthropic 的官方建议²。能从代码里读出来的就别写，比如目录结构、依赖列表。说明要短，官方建议不超过 200 行，太长了 AI 反而会漏掉重要的那条²。

还有一句很值得加：“说明和代码不一致时，以代码为准，并告诉我哪里不一致。”一篇论文用 40 个项目测试 Claude Code 和 Codex，据它的摘要，说明过时又和代码冲突时，九成的情况 AI 会照着过时的说明做；加上这一句后，九成改为跟着代码走⁵。

一个例子（仅供参考）

下面是我按上面几条写的一个样子，项目名和命令都是编的。它不是最好的写法，只是给你一个起点；真正写的时候，按自己项目的情况删改，或者直接让 AI 读完代码库后帮你起草，再一起删。

# AGENTS.md

一个 React + TypeScript 的工厂报表前端。和我沟通用中文。

## 常用命令
- 安装依赖：pnpm install
- 本地运行：pnpm dev
- 跑单个测试：pnpm vitest run path/to/file.test.ts
- 类型检查：pnpm tsc --noEmit
- 交付前必须跑：pnpm lint && pnpm test，全部通过才算完成

## 约定
- 请求一律走 src/api/client.ts，不要直接用 fetch
- 新页面用 src/pages/ 下的函数组件写法；src/legacy/ 还在用，但别学它的写法
- 改了某个函数的参数或返回值，先搜出所有调用的地方一起改

## 容易踩的坑
- 打印模板的列宽单位是字符数，不是像素
- 测试环境要先设好 API_BASE_URL，见 .env.example

## 遇到问题时
- 先读 docs/pitfalls/ 里有没有同类问题
- 一个问题花了很久才解决，或者踩了以前没记过的坑，你自己在 docs/pitfalls/ 新建一篇，
  只写四段：问题、原因、解法、下次别再犯的误区；不用等我提醒
- 同一个问题连续两次没修好，停下来，告诉我试了什么、为什么失败、你现在怎么想

## 提交
- commit 信息用中文：一句标题，加几条要点
- 最后一行写：作者：<Agent 名> 模型：<模型名>

## 文档和代码不一致时
- 以代码为准，并在回复里列出哪里不一致

可以照着看的开源仓库

光看文字有点抽象，下面三个开源仓库可以直接打开看，从短到长。这是 2026-11-01 看到的样子，它们以后可能会改。

• temporalio/sdk-java⁶（Java，AGENTS.md 约 60 行）：最朴素的写法，就是一份“新人上手指南”：各个目录是干什么的、怎么格式化、怎么跑全部测试和单个测试、commit 和 PR 要写什么、提交前要过哪些检查。适合第一次写的时候照着抄结构。
• astral-sh/uv⁷（Rust，AGENTS.md 约 50 行）：整份就是一条条规则，每条用 ALWAYS、NEVER、PREFER、AVOID 开头，比如“永远不要以为 clippy 警告或测试失败是本来就有的”“不要把我们的对话过程写进代码注释和 PR 描述里”。短，但每条都是踩过坑才写下的。
• tldraw/tldraw⁸（React + TypeScript，AGENTS.md 约 230 行）：跟前端团队最接近，结构也最完整，值得仔细看：
  • CLAUDE.md 只有一行 @AGENTS.md，和上面说的一样；
  • 开头是几条核心规则，比如“只用 pnpm；用 yarn 会失败，而且已经用 hook 拦住了”——必须遵守的规则，不光写在说明里，还用工具强制；
  • 写清楚每个包是干什么的、改哪类东西该去哪里；
  • 写测试、写文档、提交 commit、开 PR 这些重复的活，各写成一个 skill，放在 skills/ 目录，再链接给 Claude、Cursor 等不同工具共用，不复制多份。

开源仓库里，我没找到把“踩坑记录”单独放一个目录、让 AI 自己往里写的例子；tldraw 用 skill 沉淀做法，是最接近的。踩坑记录这块，可以照上面示例里“遇到问题时”那一节自己加。

另外几个入口：

• agents.md 官网：格式说明、推荐写哪几部分，以及几个开源项目的例子⁴
• GitHub 上搜 path:AGENTS.md，能看到几万个项目各自怎么写⁹
• Anthropic 的官方建议里有一个很短的 CLAUDE.md 示例，以及哪些该写、哪些不该写²

5. 把踩过的坑记下来，让 AI 自己记

每次花了很久才解决的问题，都值得留一篇短记录，只写四段：一开始的问题、真正的原因、最后的解法、下次别再犯的误区。放在 docs/pitfalls/ 之类的目录里，在 AGENTS.md 里告诉 AI 排查问题时先读这里。

关键是让 AI 自己记，不用人每次提醒。把规则写进 AGENTS.md，像上面例子里那样：“踩了以前没记过的坑，你自己新建一篇记录”。这样它下次遇到同类问题，会先去翻自己以前的记录。

我待过的项目里，几个月就攒了上百篇。有人把这叫作“复利式工程”：每个任务学到的东西写下来，下一个任务开始前先读，经验就一点点攒起来了¹⁰。

要注意的是，AI 自己记的东西也会记错、会过时。隔一阵子让 AI 对照代码清理一遍，删掉过时的。

6. 让 AI 记住“每个文件负责什么”

以前写 WPS 插件时，哪个模板坏了该去哪个文件改，我心里都有数，那是一张装在脑子里的地图。现在这张图要交给 AI：在文件开头写一两句“这个文件负责什么、有什么坑”，再加上 AGENTS.md 的入口说明。

不用写“这个文件被谁调用、又调用了谁”。代码里本来就有，AI 自己会搜；写在注释里反而要跟着每次改动同步，一忘就成了错的。

想了解代码库的某一块时，直接让 AI 讲给你听，它读的总是最新的代码。Claude Code 团队说，他们团队里没有人脑子里装着整个代码库，想了解哪一块，就让 Claude 现场生成一份讲解¹。

7. 人管大事，AI 管细节

不看每一行，不等于什么都不管。下面这些还是要人来判断：

• 该不该做这个功能；
• 数据库变更、架构调整；
• 计费、权限这类出了错代价很大的代码；
• 最后上线的东西，由人负责。

Claude Code 团队列的“人还要做的事”也差不多：决定该不该做、审危险的代码、做架构评审、核对证据、为上线的改动负责¹。小改动、细节、样板代码，交给 AI。

8. 连续修不好就停下来

AI 修同一个问题连续失败两次，就别让它继续试了。让它写下试了什么、为什么失败、现在怎么想，然后人来判断换个方向。这条可以直接写进 AGENTS.md。

9. 但别完全不懂：我还没解决的问题

前面一直在说信任 AI，这一条说说反面。这是我自己踩的坑，到现在也没完全想明白。

一开始觉得不用学。 刚开始做 iOS 时，我让 Claude 把一个网页项目改写成 iOS 原生应用，它写得又快又好，我很震惊。当时就想：是不是不用把 Swift 全学会，知道个大概结构，细节交给 AI 就行？但心里也有点不安：AI 写得太快，我跟不上；不懂每个组件是干什么的，就是 AI 在控制，我自己没有发言权。

后来发现没有掌控感。 两三个月下来，我对 SwiftUI 还是不太懂，因为代码全是 AI 写的，我没有建立起这个框架的心智模型。用 AI 写 React 时我心里有底，因为 React 我自己写了两年，知道大致结构对了，样式一般不会出大问题，只要盯住接口逻辑。Swift 不一样，AI 写得对不对我判断不了，只能在那儿硬调。一遇到难的问题，AI 改了半天越改越错，我也看不出是哪儿出了问题；再跟它说，感觉像玄学，不知道该怎么说它才不会理解歪，很容易有挫败感。

试过补，但很难沉下来。 我也试过：跟着教程一天一课从变量学起，坚持了几天；工作里遇到不懂的，让 AI 给我补知识，记成笔记。有一次临近下班，我自己建了个 demo 项目，终于弄明白某几个属性到底是干什么的，那一刻特别开心，“终于不是摸黑箱了”。同事也提醒过我：先别管排期，慢慢来，把东西弄清楚；不一定从头学一整套教程，项目里用到什么就学什么。

可是道理都懂，真要沉下来很难。用上班时间学，我心里总有压力，想着需求还在等，有点愧疚，也着急；下班以后，我又想留一点自己的生活空间，不太想再碰工作上的事。两头都有点难受。这不能怪别人，更多是我自己还没找到平衡。之前在黑湖，我的主管给过我这样的空间，让我慢慢琢磨，现在回想起来很感激。AI 让写代码变快了，但怎么给自己留出学习的时间，我还在摸索。

后来看到不只我这样：

• Anthropic 做过一个实验，让 52 个（大多是初级的）工程师学一个新的 Python 库，一半用 AI，一半自己写。用 AI 的那组，事后理解测验平均 50 分，自己写的那组 67 分；而用 AI 的那组也没有快多少¹¹。
• 同一个实验里，差别主要在怎么用 AI：让 AI 直接写代码、直接修 bug 的人，得分不到 40%；让 AI 写完再追问“为什么这样写”、或者只问概念自己动手改错的人，得分高得多¹¹。
• Addy Osmani 写过自己的经历：他让 Claude 做了一个功能，测试通过了，只扫了一眼就接受了，“三天后，我已经说不清它是怎么工作的了”。他把这叫作“理解债”¹²。

我现在的想法（还没做到，只是想这么试）：

• 对一个框架有心智模型，遇到问题才知道往哪儿找，不然最后会陷入被动。所以再快，也想给自己留出学框架本身的时间。
• 让 AI 写完以后，多问一句“为什么这样写”“这个属性是干什么的”。不熟的东西，自己建个小 demo 试一试。
• AI 一直改不对的时候，提醒它先去网上查这个问题的最佳实践和官方文档，再动手。我的感觉是 GPT 更需要这样提醒，Claude 会聪明一点；这只是我的体感。

这条跟前面的“信任 AI”不矛盾：主管不用看手下的每一行代码，但主管自己得懂这一行。

这些只是我的感受，有的人好像没这个问题。说不上好坏，你自己试试看。

说到底，这些方法都是一件事：把自己从写代码、读代码的人，变成交代任务、验收结果的人。如果你只想试一件事，我建议从第 3 条开始：下次提交时，让 AI 帮你写 commit。然后再试第 1 条，动手前先跟它聊方案。

这篇文章是 AI 写的，你完全可以拿 AI 去读。更重要的是，我想记录下我的一些理解，也想分享给大家。