工程实践

AI 写的代码，为什么总像“差不多对”？我用 opencode 把 commit 前审查做成三道门 我用opencode做代码审查，注重agents.md的质量，聚焦多轮核心BUG输出质量，减少MR被驳回的风险 审查阶段不要使用可写 agent。 可写 agent 看到问题后很容易顺手修复，修复后的代码又变成新的审查对象。我要的是报告，不是未经确认的工作树变化。 AGENTS.md 不是越长越好。 我见过把抽象价值观、编码风格和所有历史事故都塞进去的规则文件，最后 AI 什么都读到了一点，却没有一条真正执行到位。规则应当短、具体、可验证。 不要只统计 AI 提了多少条意见。 我更看重高价值意见的比例、误报率、漏报案例和处理耗时。意见越多不等于审查越好。 我最近在 Go 项目里遇到过一个很典型的例子：我让 AI 把一个用 sync.Mutex 保护的缓存改成 sync.RWMutex，因为读请求远多于写请求。代码能编译，go test -race 也通过了，我正准备提交时又看了一遍 diff，才发现 AI 在 RLock() 之后没有为所有提前返回的分支补上 RUnlock()。原代码用 defer Unlock() 做了一次兜底，锁的种类变了，兜底结构却没有一起变。 这个问题不是函数体“完全写错”，而是局部正确、整体破坏。测试没有触发那个错误分支，竞态检测自然也抓不到。类似的情况我见过很多：错误被 _ 接住、context 半路丢失、goroutine 没有退出条件、异常路径没有补齐、依赖被悄悄换成团队没人维护的库。AI 生成代码的速度越快，diff 的影响半径就越容易被低估。 我现在把 commit 前的审查拆成三道门：机器门负责确定性检查，AI 自审负责挑出候选风险，人工 review 负责业务判断和最终签字。这篇文章记录我在 Go 项目里实践这套流程的方式，也会说明 opencode 适合放在哪一层、哪些事情仍然不能交给它。 蓝色 表示工具或事实，绿色 表示我的实践判断，红色 表示容易踩的坑，黄色 表示可以直接改写到自己项目里的模板。 一、先把 commit 当成一次小型发布 以前我把 git commit 当作保存进度，后来几次线上问题让我改了看法：commit 是把一组行为变化交给团队和环境的发布动作。即使还没有上线，它也已经影响了后续 review、合并、回滚和事故追踪。 ...

AI 生成代码该怎么审：一套可以直接使用的实操框架 我的核心要求：减少 BUG，减轻 Review 压力，避免生产环境出现不可逆的风险。不要怕对同一个任务开多个agent，重要的是让不同关注点能充分执行，人工做最后的审核兜底； 一、AI 写得越快，审查越不能只看“像不像对的” AI 一分钟可以生成几百行代码，几小时就能跑完一轮 PR 流程。真正决定质量的，已经不只是 AI 写得快不快，而是我们能不能在代码生成之后，用合适的方法把它审干净。我自己每天让 AI 生成大约一半的代码改动，但最后原样合进主干的，大概只有三成。剩下的代码往往不是“完全写错”，而是“看起来很像对”：错误被 _ 接住，权限校验在调用链里悄悄漏掉，并发场景只覆盖了 happy path，或者引入了一套团队没人熟悉的依赖。这些问题可能过得了 lint、单元测试和评审，却会在生产环境里变成真正的事故。 所以，我现在不把 AI 当成“替我批准代码的人”，而是把它放在风险筛查器的位置：先帮我快速找出值得追问的地方，再由作者、人工 Reviewer 和领域负责人作最终判断。这个定位也和公开实践比较一致：OWASP 把人工代码审查定义为对自动化安全测试的补充，重点放在业务逻辑、复杂安全实现和具体上下文上；Google 的评审指南则强调，测试本身也需要人来判断是否真的有效。可参考 OWASP Secure Code Review Cheat Sheet 和 Google 的代码评审实践。 二、先把审查输入准备好，AI 才不会对着空气猜 我以前最容易犯的错，是把一段代码直接丢给 AI，然后补一句“帮我仔细审查”。现在我会先准备一张很短的“审查输入卡”，至少包含下面五项： 目标：这次改动要解决什么问题？不解决什么问题？ 不变量：哪些已有行为、权限边界、接口兼容性和数据约束绝对不能被破坏？ 范围：本次 PR 改了哪些文件、调用链和配置？哪些内容只是必要上下文？ 验证：新增或修改了哪些测试？正常路径、异常路径和回滚路径分别是什么？ 风险：是否涉及登录、权限、支付、个人信息、文件上传、数据库迁移、加密或外部依赖？ 日常 PR 我会让 AI 以 diff 为主，只补充相关接口、数据结构、配置和测试。OWASP 也把 diff-based review 作为 Pull Request 和日常开发的适用方式；新系统、重大版本、遗留系统接管或事故复盘，才更适合做全量的 baseline review。另一个有效做法是控制 PR 的大小：Google 建议一个变更尽量只做一件自洽的事，相关测试跟着代码一起提交，大型重构与功能修改分开。这样做的收益很直接：AI 看得少而准，人也更容易发现真正的行为变化。 ...

减少 AI 返工，我现在一般这么做 原文：Review AI-generated code 与 AI 代码审查实践的综合解读 作者：我（结合个人 AI 编程实践整理） 来源：GitHub、Uber、Cloudflare、Trellis 等公开资料，整理于 2026 年 08 月 26 日 AI 写代码越来越快，但返工并没有因此自动消失。我现在更关心的，不是 AI 一次写了多少，而是错误能不能更早暴露、修改能不能更小、人工判断能不能用在真正重要的地方。 这篇文章记录的，就是我目前用来减少 AI 代码返工的一条实践路径。 一、我以前把 AI 当成“写得更快的人”，后来发现它更像“放大器” 刚开始用 AI 写代码时，我最在意的是它能不能一次生成几百行、能不能把一个需求快速改完。后来真正经历了几轮线上问题、PR 返工和反复讨论，我才意识到：AI 放大的不只是产出速度，也会放大需求里的空白、上下文里的误导和开发者自己的错误判断。代码生成得越快，如果没有同步增加验证能力，Review 只是被动接收更多半成品。 我最近看了一些开发者分享和团队实践，大家的结论其实很接近：不要把“AI 写了多少代码”当成成功指标，而要看它是否减少了无效沟通，是否能在进入人工 Review 前被自动检查，是否让 reviewer 更快理解真正的风险。GitHub 的官方建议也很直接：先检查功能、上下文和意图，再看代码质量、依赖和安全；最终合并责任仍在开发者身上。我现在给自己的目标因此换了一个说法：不是保证 AI 一次写对，而是让错误尽可能早暴露，让每一轮修改尽可能小，让机器能判断的事情不要消耗人工判断，让必须由人判断的事情明确标出来。 二、写之前先做上下文盘点：不要让 AI “自己理解整个仓库” 我遇到过最浪费时间的一类任务，是直接对 Agent 说“先理解一下这个仓库，再实现功能”。小项目这样做问题不大，仓库一大，Agent 往往会先花很多时间猜目录结构，读到相似但已经废弃的实现，最后在错误的上下文上给出一份看起来很合理的方案。社区里有开发者把自己的流程总结成：先画仓库地图，再找相关文件，检查上下文是否足够，最后检查回答是否确实基于这些文件。我照着这个思路调整后，最大的变化不是回答更长，而是少了“改错文件”和“参考旧逻辑”的返工。 我现在会把任务拆成四步： 先定位：让 AI 只列出与任务直接相关的目录、入口、调用方、测试和配置，不要马上改代码。 再确认：让它说明每个文件为什么相关，哪些文件只是相似样例，哪些内容可能已经过期。 再补上下文：补充接口契约、数据库结构、历史 PR、业务规则和失败案例；如果这些信息没有提供，就明确标成未知。 最后锁范围：规定允许修改的文件和不允许顺手做的重构，要求它在动手前复述范围。 我会先使用这样的提示： 先不要写代码。请完成以下任务： 1. 列出本任务涉及的入口、调用链、数据结构、测试和配置； 2. 区分“已从仓库确认的事实”和“你的推测”； 3. 指出还缺少哪些上下文，以及缺失它们会影响什么判断； 4. 给出最小改动计划，列出准备修改和明确不修改的文件； 5. 等我确认计划后再实现。 这里有一个容易被忽略的细节：我不会把所有文档一股脑塞给 AI。上下文太多同样会稀释重点，我更倾向于使用“渐进披露”：先给仓库地图和任务相关文件，遇到具体问题再补充协议、ADR、历史 PR 或业务文档。AI 必须回答“我实际参考了哪些文件”，而不是笼统地说“我已经理解整个项目”。上下文的关键不是多，而是相关、最新、可核对。 如果它引用了过期文档，我会先停下来校正上下文，而不是继续修补错误答案。 ...

AI 一口气生成几百行代码，我们该怎么高效且正确地处理代码审核 一、当 AI 能在一分钟里吐出一两百行代码时，真正的难点早已不是“写不出来”，而是“接得住、查得动、改得回、负责得起”。我自己一天常常让 AI 写十几轮，单次 50–300 行很常见，一周下来累计几千行并不夸张。这里面能直接合进主干的大概只有一半，剩下要么是风格不一致、要么是越权操作、要么是没覆盖到我期望的边界，真正被我留下来再加工的常常只有三分之一。速度确实上去了，但读、改、回滚这些事没有便宜半分。我需要同时做目标设计者、规则制定者和成果验收者：先把问题、边界和验收条件讲清楚，再让 AI 在明确的范围里多试几种写法、多跑几轮检查，最后由我看差异、看风险、看回滚路径，再决定是否合并。这一顺序不能反过来——如果我自己都不知道“完成”长什么样，再快的生成也只是把模糊需求放大成更难检查的代码。带着这个结论再读这个题目，会更容易看清它真正在问什么：不是“AI 写得太快怎么办”，而是“当写的成本被工具压平以后，程序员到底该把时间花在哪几个动作上，才能既不返工，也不背锅”。 二、过去半年我最大的感受是，AI 把“写一段代码”的价格压下去了，但“看懂一段代码”的价格几乎没变。一个函数能不能写出来，今天大多数时候已经不构成瓶颈；真正占用时间的，是它处在什么上下文、用了哪些约定、隐含了哪些假设、会不会影响别的模块。一个项目里如果突然多出几百行 AI 代码，常见问题不是“明显错误”，而是“看起来很像正确答案”。我整理了几类实际反复遇到的偏差：在 Go 项目里写出 Python 风格的命名（snake_case 夹杂驼峰、把 换成 ），在 React 项目里调用一年前版本的 清理写法，在 iOS 项目里把 写成一串 嵌套，在 SQL 里写出 ORM 不能识别的方言。这些都不算 Bug，跑得起来，过得了 lint，但放进项目里就是和团队既有代码打架。错误处理走的是另一套约定、用了项目里没人熟悉的依赖、或者把一份本该抽出来的逻辑写成了复制粘贴，也都同源。这并不是 AI 不努力，而是它默认按“训练里最常见的写法”回答，而不是按“这一个项目里最合理的写法”回答。读代码一旦要一边猜意图、一边查背景、一边补差异，效率马上塌掉。所以处理 AI 批量生成代码的第一个动作，不是立刻评审，而是先把这些代码放到一个能被人快速消化的上下文里：让它先和现有约定对齐，再让它进入人的视线。我自己的小习惯是：先跑一遍项目的 formatter / import-sort / gofmt-prettier / eslint --fix，把肉眼可见的风格差异抹掉，再开始看逻辑。看起来是小事，能省下 review 时一半的争论。 三、把 AI 当成“一小时能写完一周活”的同事是不够的，更准确的定位是：它负责在明确边界内把重复部分做出来，人负责在模糊地带做判断。越模糊的需求，越不该直接交给 AI；越清晰的接口，越适合让 AI 多试几种实现。具体到我自己：在把任务交给 AI 之前，我会先填一份简短的“任务说明模板”，哪怕只是几行清单： 目标：这次改动要解决什么，用一两句话讲清楚； 不能破坏的行为：列出已有的功能、API 兼容点、对外契约； 验收条件：包括成功路径、失败路径、边界输入、需要的日志或埋点； 范围：哪些文件/模块允许改动，哪些只能引用不能改； 测试：要求覆盖的关键 case（哪怕只是几条自然语言描述）； 依赖：允许引入哪些新包，是否需要更新 lockfile、是否要走安全 review。 这份清单写在 issue、PR 描述、或者本地 prompt 模板里都行。我自己最常用的是把它贴在每次开新对话的第一段，让 AI 在生成前自己复述一遍——如果 AI 的复述和我理解的不一致，我先纠正它，再让它写代码。这一步看起来比直接生成慢一点，但它避免了我最怕的那种返工：代码已经写得很长，最后才发现我根本没想清楚要的是什么。一旦让 AI 开始写，我会刻意要“两三种实现思路”，而不是一个最终答案：每种思路分别有什么取舍、依赖、风险点，分别适合什么场景。AI 在这里负责的是“扩宽选择范围”，我负责的是“决定走哪条”。判断做完之后，AI 仍然很有用：写样板、补测试、翻译接口、改一处风格、批量重命名——这些是它擅长、我也乐意外包的部分。把“想清楚”和“写出来”分成两步，比把“想”也外包出去重要得多。 ...