1. 为什么“让 AI 写代码”这件事远没有看起来那么省心我做了十多年全栈从前端切图到后端调优、从数据库索引到线上排障基本都亲手摸过一遍。这两年 Coding Agent 火起来之后身边不少同行第一反应是“终于可以躺平了”——把需求往对话框里一贴等它吐代码复制粘贴跑通就完事。我自己也经历过这个阶段刚开始用的时候确实爽一个 CRUD 接口几秒钟就出来了一个 React 组件连样式带逻辑一起给你看着挺唬人。但真正把 AI 生成的代码往生产环境里塞过几轮之后我的态度变了。不是 AI 不行而是**“让 AI 写代码”和“和 AI 一起写代码”是两件完全不同的事**。前者你把自己降级成了一个复制粘贴的工具人后者你才是那个掌控全局的工程师。标题里说的“5 条协作纪律”就是我从踩坑里总结出来的、让 AI 真正成为队友而不是定时炸弹的几条硬规矩。这篇文章适合谁看如果你是全栈工程师日常要同时碰前端、后端、数据库、部署脚本并且已经开始用或者打算用 Coding Agent 帮你干活那这篇就是写给你的。如果你只是偶尔让 AI 写个正则、解释个报错那也能从里面挑几条用得上的。核心关键词就几个AI、全栈工程师、CLAUDE.md、AGENTS.md、Coding Agent我会围绕它们把整套协作方法讲透。先说结论AI 写代码最大的风险不是它写错而是它写得太顺、太像对的让你放松了警惕。一个变量名起得漂漂亮亮、注释写得头头是道、结构看着无比合理的函数里面可能藏着一个边界条件没处理、一个并发场景没考虑、一个安全漏洞没堵上。你如果只是扫一眼觉得“嗯不错”那坑就埋下了。所以下面这 5 条纪律本质上都是围绕“如何不被 AI 的流畅输出骗过去”来展开的。2. 第一条纪律先立规矩再让 AI 动手——CLAUDE.md 与 AGENTS.md 的正确用法2.1 为什么需要一个“项目宪法”文件很多人用 Coding Agent 的方式是打开对话框直接说“帮我写个用户登录接口”。Agent 就开始噼里啪啦输出。问题是它不知道你的项目用的是 Express 还是 Fastify不知道你的数据库是 PostgreSQL 还是 MySQL不知道你的错误处理是抛异常还是返回 Result 对象不知道你的日志库是 winston 还是 pino。它只能靠猜猜出来的东西风格和你项目格格不入你还得花时间改。CLAUDE.md 和 AGENTS.md 这类文件的作用就是给 AI 立一部“项目宪法”。你把项目的技术栈、目录结构、编码规范、常用命令、禁忌事项写进去Agent 每次动手之前先读这个文件输出的代码就会自动贴合你的项目风格。这不是什么高深技术就是一个放在项目根目录的 Markdown 文件但效果立竿见影。我自己的项目里CLAUDE.md 通常包含这几块内容项目概述一句话说清这是干什么的、技术栈清单框架、语言、数据库、缓存、消息队列的具体版本、目录结构说明哪个目录放什么、编码规范命名、注释、错误处理、日志、常用命令启动、测试、构建、迁移、以及“绝对不要做的事”比如不要引入新的依赖、不要改数据库 schema、不要动某个核心模块。2.2 AGENTS.md 和 CLAUDE.md 的分工这两个文件名字不同但本质是一类东西——给 Agent 的上下文说明文件。不同工具可能约定不同的文件名比如有的用 AGENTS.md有的用 CLAUDE.md有的用 .cursorrules。我的做法是主文件只留一份其他名字用软链接或者直接复制避免多处维护导致不一致。具体分工上我会把内容分成两层项目级 AGENTS.md放在仓库根目录写全局性的规矩所有 Agent 都读这一份。模块级 AGENTS.md放在具体子目录里写这个模块特有的约定。比如src/payment/AGENTS.md里写清楚支付模块的幂等要求、金额单位是分不是元、所有对外调用必须带超时。这样 Agent 在改支付模块的时候会同时读到全局规矩和模块规矩输出的代码就不会出现“金额用浮点数”这种低级错误。2.3 写 AGENTS.md 的几个实操要点第一用命令式语气不要用描述式。写“所有 API 响应必须包含 requestId 字段”不要写“我们通常会在响应里加 requestId”。Agent 对命令式语句的遵循度明显更高。第二给出正例和反例。光说“错误处理要统一”没用你得贴一段正确代码和一段错误代码Agent 才知道你要的是哪种。我通常会在文件里放两三个代码块一个“这样写”一个“不要这样写”。第三定期更新。项目演进过程中技术栈会变、规范会变AGENTS.md 如果半年不更新Agent 就会按老规矩办事反而添乱。我一般每个 sprint 结束的时候顺手过一遍改几行。第四不要写太长。我见过有人把 AGENTS.md 写成几千行的百科全书结果 Agent 读的时候注意力被稀释关键规矩反而记不住。控制在 200 行以内只写最重要的。提示AGENTS.md 里不要放敏感信息比如数据库密码、API 密钥。这些应该走环境变量文件里只写“从环境变量读取变量名是 XXX”。3. 第二条纪律需求拆到 AI 能一口吃下再喂给它3.1 大需求直接丢给 AI 会发生什么我试过让 Agent 一次性实现“用户注册 登录 找回密码 邮箱验证”这一整套功能。结果它确实吐出来一大堆代码但问题一堆注册和登录用了两套不同的密码加密方式找回密码的 token 生成逻辑和邮箱验证的 token 逻辑重复但又不完全一样错误码定义散落在四五个文件里。我花了整整一个下午去理顺比自己写还累。根本原因在于AI 的工作记忆是有限的。你给它一个太大的任务它没法在脑子里同时装下所有约束只能顾此失彼。就像你让一个新人一天之内搞定整个用户系统他也会手忙脚乱。3.2 怎么拆才算“一口吃下”我的经验是一个任务单元应该满足三个条件能在一次对话里说清楚、产出的代码不超过 200 行、有明确的验收标准。比如“实现用户注册接口”就太大了拆成“定义用户表 schema”“实现密码哈希工具函数”“实现注册接口的 controller”“写注册接口的单元测试”就合适。拆的时候有个技巧按数据流拆不要按文件拆。按文件拆容易拆出“写 userService.js”这种任务AI 不知道里面该有什么。按数据流拆就是“输入是什么、输出是什么、中间经过哪些处理”AI 更容易理解。3.3 给 AI 的每个任务都要带“验收标准”我现在的习惯是每次让 Agent 干活都会在 prompt 末尾加一段“验收标准”。比如验收标准 1. 输入邮箱格式非法时返回 400错误码 INVALID_EMAIL 2. 邮箱已存在时返回 409错误码 EMAIL_EXISTS 3. 密码少于 8 位时返回 400错误码 PASSWORD_TOO_SHORT 4. 成功时返回 201响应体包含 userId 和 createdAt 5. 所有分支都要有对应的单元测试有了这段Agent 输出的代码质量明显提升因为它知道“做到什么程度算完”。而且我验收的时候也有依据不用凭感觉判断。3.4 拆任务的粒度参考表任务类型太大不要这样合适推荐接口开发实现整个用户模块实现注册接口的 controller 层前端组件做一个后台管理页面做一个带分页的用户列表表格组件数据库设计整个数据库设计 orders 表的 schema 和索引重构重构整个项目把 utils/date.js 里的函数改成纯函数测试给项目加测试给 password.js 加单元测试覆盖 5 个分支这张表是我自己踩坑总结的你可以直接拿去用。核心原则就是AI 一次只做一件事做完验收再做下一件。4. 第三条纪律AI 写的代码你必须逐行读懂再合并4.1 “看着对”和“真的对”之间隔着一条河这是我最想强调的一条。AI 生成的代码有个特点它看起来总是很合理。变量命名规范、缩进整齐、注释到位、结构清晰。你扫一眼会觉得“嗯没问题”然后就直接 commit 了。但真正的 bug 往往藏在细节里。我遇到过一个典型案例Agent 写了一个分页查询代码长这样const offset (page - 1) * pageSize; const results await db.query( SELECT * FROM users ORDER BY created_at DESC LIMIT ? OFFSET ?, [pageSize, offset] );看着没问题对吧但我们的数据库是 MySQLLIMIT ? OFFSET ?这种参数化写法在某些驱动版本下会报错得写成LIMIT ?, ?。这个 bug 在本地测试没暴露因为本地驱动版本不一样上了预发环境才炸。如果我当时逐行读一遍去查一下驱动文档就能提前发现。4.2 逐行读的时候重点看什么我总结了一个检查清单每次 review AI 代码的时候按这个过一遍边界条件空数组、null、undefined、0、负数、超大数这些情况处理了吗错误处理每个可能失败的操作网络请求、数据库查询、文件读写都有 try-catch 或者错误返回吗并发安全如果有共享状态考虑过并发读写吗需要加锁吗资源释放打开的文件、数据库连接、定时器都有对应的关闭逻辑吗安全用户输入有没有做校验和转义SQL 有没有参数化敏感信息有没有打日志性能有没有 N1 查询有没有在循环里做网络请求有没有不必要的全表扫描这六条过一遍大部分坑都能提前发现。刚开始会觉得慢但养成习惯之后review 一段 100 行的代码也就三五分钟。4.3 不要跳过“跑一遍”这一步逐行读完之后还有一步不能省实际跑一遍。AI 生成的代码经常有“看起来能跑但实际跑不起来”的问题比如引用了不存在的依赖、用了未定义的变量、路径写错了。这些静态看不一定能发现跑一下立刻暴露。我的做法是Agent 输出代码后先让它自己跑一遍测试如果项目有测试框架跑通了再人工 review。如果 Agent 说“我无法执行代码”那我就手动复制到本地跑。总之没跑过的 AI 代码绝不合并。4.4 一个真实的翻车案例有一次我让 Agent 写一个“删除过期 session”的定时任务。它写了一个 cron 表达式0 0 * * *注释写着“每天凌晨执行”。我看着没问题就合并了。结果上线后发现 session 根本没被清理。查了半天才发现0 0 * * *在某些 cron 实现里是“每小时的第 0 分钟的第 0 秒”也就是每小时执行一次不是每天。正确写法应该是0 0 0 * * *六位或者0 0 * * *配合特定的库配置。这个坑让我记住了一件事AI 对“约定俗成”的东西经常搞错因为它见过的写法太多分不清哪个是当前项目的约定。所以凡是涉及配置、表达式、协议格式的地方必须查文档确认。5. 第四条纪律让 AI 写测试但别让它自己判卷5.1 AI 写测试的优势和陷阱让 AI 写单元测试是个好主意因为它不嫌烦能把各种边界条件都覆盖到。我经常让 Agent 给一个函数生成测试它一口气能写出十几个 case比我手动想得全。但这里有个陷阱AI 写的测试可能和 AI 写的实现“串通”了。什么意思就是实现里有个 bug测试里恰好也按这个 bug 的逻辑来断言结果测试全绿bug 却还在。这种情况在 AI 同时写实现和测试的时候特别容易发生因为它脑子里的“预期行为”和“实际实现”是一致的哪怕这个一致是错的。5.2 正确的做法实现和测试分开写我的做法是实现和测试分两次让 AI 写中间隔一段时间或者换一个对话。写实现的时候只给需求不给测试写测试的时候只给接口签名和需求文档不给实现代码。这样 AI 写测试的时候是“盲写”更容易发现实现里的问题。更严格一点的做法是测试由人来定验收标准AI 只负责把标准翻译成代码。比如我先手写一个测试用例列表- 输入空字符串应抛出 InvalidArgumentError - 输入超长字符串1000 字符应截断到 1000 - 输入包含特殊字符应原样保留 - 输入 null应返回空字符串然后让 Agent 按这个列表写测试代码。这样测试的“意图”是我定的AI 只是执行者就不会出现“串通”的问题。5.3 测试覆盖率不是越高越好我见过有人追求 100% 覆盖率让 AI 把每个分支都测到。结果测试文件比实现文件还长维护成本极高而且很多测试是“为了覆盖而覆盖”测的是 getter/setter 这种没营养的东西。我的建议是核心业务逻辑追求高覆盖工具函数适度覆盖胶水代码不强制覆盖。比如支付金额计算、权限判断、状态机流转这些地方必须每个分支都测到而像“把两个字符串拼起来”这种函数测一两个 case 就够了。5.4 让 AI 帮你找“没测到的地方”有个技巧很好用写完测试之后让 Agent 分析一下“哪些分支没有被测试覆盖到”。它会给你列出漏掉的分支你再决定要不要补。这比你自己去数覆盖率报告快得多。注意AI 分析的覆盖率不一定准它可能会漏掉一些隐式分支比如异常处理里的 catch。所以最终还是要以实际的覆盖率工具输出为准。6. 第五条纪律把 AI 当队友但决策权永远在你手里6.1 AI 会“自信地犯错”这是 AI 最危险的地方它不知道自己不知道什么。你问它一个它没见过的 API它不会说“我不确定”而是会编一个看起来很像的出来。你让它选一个技术方案它会选一个“听起来合理”的但不一定适合你的场景。我遇到过一次让 Agent 推荐一个 Node.js 的定时任务库。它推荐了一个叫node-schedule的说“轻量、易用、支持 cron 表达式”。听起来没问题但我多问了一句“它支持分布式锁吗”Agent 说“支持通过 Redis 适配器”。我去查了一下发现那个适配器已经两年没维护了而且有已知的并发 bug。如果我直接信了上线后定时任务在多个实例上重复执行数据就乱了。6.2 决策权在人的三个体现第一技术选型必须人拍板。AI 可以给你列选项、分析优劣但最终用哪个得你根据团队情况、维护成本、社区活跃度来定。AI 不知道你们团队没人会 Rust也不知道你们运维只支持 Docker 部署。第二架构设计必须人主导。AI 可以帮你画个草图、写个伪代码但模块怎么划分、服务怎么拆分、数据怎么流转这些涉及长期演进的决策必须人来定。AI 的视野局限在当前对话里看不到半年后的扩展需求。第三上线前的最终检查必须人来做。AI 可以帮你跑测试、做 lint、检查格式但“这个改动会不会影响线上用户”“这个配置在高峰期扛不扛得住”“这个日志会不会泄露隐私”这些判断只有人能做出。6.3 建立“AI 建议 → 人审核 → 人决策”的流程我现在的工作流是这样的AI 提建议让 Agent 给出 2-3 个方案附上各自的优劣。人做调研我去查文档、看社区讨论、问同事经验验证 AI 说的对不对。人做决策综合所有信息选一个方案写清楚选它的理由。AI 执行让 Agent 按选定的方案写代码。人验收逐行 review、跑测试、上线观察。这个流程看起来比“直接让 AI 写”慢但返工率低得多。我算过一笔账直接让 AI 写然后返工平均一个功能要来回改 3-4 次走这个流程基本一次过。总体时间反而更省。6.4 一个心态上的调整最后说个心态问题。很多人用 AI 写代码潜意识里是“我想偷懒”。这个心态本身没错但偷懒要偷对地方。AI 适合帮你干“体力活”——写重复的样板代码、生成测试用例、格式化数据、查文档。但“脑力活”——想清楚要做什么、判断什么是对的、决定怎么做——这些不能偷懒偷了就会出问题。把 AI 当成一个手速极快但经验尚浅的实习生你可以让他帮你干活但他交上来的东西你必须检查关键决策你必须自己拿主意。这个定位摆正了协作就顺了。7. 五条纪律的落地检查清单与常见坑速查7.1 每次和 AI 协作前的自检清单我把上面五条纪律浓缩成一个清单每次开工前过一遍[ ] 项目根目录有 AGENTS.md 或 CLAUDE.md且内容是最新的[ ] 当前任务已经拆到“一次对话能说清、产出不超过 200 行”[ ] 任务描述里带了明确的验收标准[ ] 实现和测试分开写测试的验收标准由人定[ ] 代码合并前逐行读过重点检查边界、错误、并发、资源、安全、性能[ ] 代码实际跑过测试通过[ ] 技术选型和架构决策是人拍的板不是 AI 说了算这个清单我贴在显示器旁边刚开始需要刻意对照用了一两个月之后就变成肌肉记忆了。7.2 常见坑速查表坑表现解法风格不一致AI 写的代码和项目其他部分格格不入完善 AGENTS.md给出正反例任务太大AI 输出一堆代码但互相矛盾按数据流拆任务每个任务带验收标准隐藏 bug代码看着对跑起来出错逐行 review 实际跑一遍测试串通实现有 bug 但测试全绿实现和测试分开写测试标准人定选型踩坑AI 推荐的库有已知问题人做调研查文档和社区反馈配置错误cron 表达式、路径、环境变量写错涉及配置的地方查文档确认依赖冲突AI 引入了项目里没有的依赖AGENTS.md 里写明“不要引入新依赖”安全漏洞SQL 拼接、XSS、敏感信息打日志review 时专门过一遍安全检查清单7.3 几个我踩过的具体坑坑一Agent 自作主张改了公共函数。有一次我让 Agent 改一个模块它顺手把utils/format.js里的一个函数改了理由是“这样更优雅”。结果另一个模块依赖那个函数的旧行为直接挂了。后来我在 AGENTS.md 里加了一条“修改任何公共函数前必须先询问”。坑二Agent 生成的迁移脚本没考虑回滚。它写了一个ALTER TABLE加字段的脚本但没写回滚逻辑。上线后发现有问题想回退只能手动写反向脚本。现在我的规矩是所有数据库迁移必须同时提供 up 和 down。坑三Agent 把测试写成了“实现复读机”。它写的测试是这样的expect(add(1, 2)).toBe(3)然后实现是return a b。这种测试没有任何价值因为它只是把实现逻辑用另一种方式写了一遍。好的测试应该测“行为”而不是“实现”比如测“输入两个正数返回它们的和”“输入负数返回正确结果”“输入超大数不溢出”。7.4 关于 CLAUDE.md 和 AGENTS.md 的补充说明这两个文件目前没有统一标准不同工具支持情况不一样。我的建议是不管你用什么工具都在项目根目录放一个 AGENTS.md内容按我上面说的写。如果工具支持其他文件名就做个软链接指过去。这样换工具的时候不用重写团队新人也能通过这个文件快速了解项目规范。文件内容不用追求大而全先写最重要的 10 条用起来之后再慢慢补。我见过有人花一整天写 AGENTS.md结果写完之后再也没更新过反而成了负担。正确的做法是边用边补遇到 Agent 犯错就加一条规矩这样文件会越来越贴合实际需求。8. 我个人的一些体会用 AI 写代码这两年我最大的感受是AI 没有让我变懒反而让我对代码质量的要求更高了。以前自己写代码有些小问题可能就放过去了现在 AI 写得快我有更多时间去做 review 和测试反而把标准提上去了。另一个感受是全栈工程师在 AI 时代反而更值钱了。因为 AI 可以帮你写前端、写后端、写脚本但“把所有这些串起来、保证整体一致”这件事只有全栈工程师能做。你如果只懂前端AI 写的后端代码你 review 不了你如果只懂后端AI 写的前端交互你判断不了。全栈的视野在 AI 协作里是刚需。最后分享一个小技巧我会定期让 Agent 帮我 review 我自己写的代码。把一段我手写的代码贴给它问“这段代码有什么问题”。它经常能指出一些我忽略的边界情况。这个用法反过来用效果很好——AI 不只是写代码的工具也是 review 代码的帮手。至于那五条纪律说到底就是一句话AI 可以帮你写但不能帮你负责。代码上线出了事背锅的是你不是 AI。想清楚这一点你就知道该怎么和它协作了。