★ FEATURED ARTICLE 六个月的“纯 Agent 编码”到底意味着什么社区里对这个话题的看法一直很撕裂一边是“AI 生成的东西只能当玩具”另一边是“我把日常编码全交给 Agent人只负责提需求和 review”。如果半年前有人告诉我他会“只用 Agent 写代码”我大概率会觉得这是标题党。但 Agent 工具的迭代速度让这件事变成了现实。这篇文章不聊模型跑分也不聊宏大趋势只做一件事把“用 Agent 写代码”从安装配置到日常协作的完整链路拆开讲清楚它解决了什么问题、改变了什么环节、有哪些坑。如果你已经装了 Claude Code 或在 VS Code 里配置过 Agent但还没找到一套稳定的工作流这篇文章值得读完。我先把结论放在前面纯 Agent 编码真正改变的不是“谁写代码”而是“人的工作从打字变成了定义问题和验收结果”。代码质量的下限不再取决于你敲键盘的速度而是取决于你把需求说得多清楚、把验收标准定得多硬、把权限边界划得多严。1. 半年只用 Agent 写代码到底在写什么“只用 Agent 写代码”这句话字面意思很容易被误解成“人完全不碰代码AI 全自动交付”。真实情况不是这样。以功能开发为例一个典型的 Agent 驱动工作日循环是人把需求和约束写成任务说明交代仓库结构、入口文件、允许改动的范围。Agent 读取相关文件给出实现计划等人确认。Agent 开始改代码跨文件修改、补充或修改测试。Agent 自己运行测试和构建命令根据失败信息反复修正。人检查 diff、跑回归、做安全审查最后合入提交。在这个流程里人还是要写代码的——只不过写的是“需求说明”“review 意见”和“验收反馈”而不是实现逻辑。偶尔你也会手改一两行但那属于特例不是常态。这半年里比较大的变化不是工作效率的数字而是思维方式的切换。过去写代码时人的注意力在“怎么实现”上函数怎么命名、分支怎么组织、边界条件怎么处理。切换到 Agent 模式后注意力必须前置到“定义问题”这个任务到底要解决什么验收标准是什么哪些文件绝对不能动如果这些问题不清晰Agent 就会用最“合理”的猜测把代码写完然后你需要花更多时间在 review 里把它揪出来。从这个角度看Agent 并没有让人变懒它只是把工作量从编码期挪到了需求期和 review 期。还有一个很容易被忽略的事实Agent 模式的成立依赖两个技术前提。一是模型的上下文窗口足够大可以一次读入多个文件并记住跨文件的依赖关系二是 Agent 具备执行命令和读文件的能力可以在真实环境里自我验证而不是只给出“看起来对”的代码。这两点缺一不可。如果你只拿到一个“对话框里生成代码片段”的工具那还不是 Agent最多算升级版补全。2. 编程 Agent 的核心概念与能力边界2.1 Agent 与自动补全的根本区别很多人把 AI 编程工具都叫“AI 编程助手”但自动补全和 Agent 是两种物种。对比维度自动补全 / 行内建议编程 Agent输入方式光标位置触发逐行补全接收一个完整任务描述上下文范围当前文件、当前函数整个仓库、多个文件、执行结果典型动作补全一行或一个函数读文件、改文件、跑命令、调测试自我修正基本没有根据报错和测试结果循环修正交付物代码片段一个可提交的变更集合自动补全解决的是“下一个 token 写什么”的问题Agent 解决的是“这个任务怎么完成”的问题。前者是键盘的延伸后者是流程的参与者。理解这个区别很重要因为很多人在第一次使用 Agent 时还带着“逐行检查补全建议”的习惯结果发现 Agent 一口气改了十几个文件然后陷入恐慌。这不是 Agent 坏了而是它的工作方式本来就是这样。2.2 Agent 的工作闭环一个规范的 Agent 工作闭环包含五个阶段规划根据任务描述列出需要读取的文件和修改步骤。读取读取项目结构、相关源码、配置文件、测试代码。编辑执行代码修改通常是多文件操作。执行运行测试、构建、lint 等命令。观察与修正读取命令输出定位失败原因回到编辑阶段。这五个阶段形成一个循环直到测试通过或 Agent 决定向你提问。好的 Agent 工具会把每个阶段的操作和结果展示在界面上你不需要盲猜它在干什么。这也意味着Agent 的“可见性”直接决定了它的可用性一个黑盒 Agent 你会不敢用一个每一步都留痕的 Agent 你才敢让它连跑十轮。2.3 Agent 的能力边界半年下来我对 Agent 边界最深刻的体会是它擅长“按明确要求执行”不擅长“替你做模糊决策”。不能把模糊需求变成业务逻辑如果任务描述写“优化一下登录”Agent 大概率会猜一个方向开始改。它猜得越快你 review 的成本越高。不能替你承担安全决策涉及权限校验、加密、支付之类的逻辑Agent 可以写但最终审查责任必须由人承担不能因为它“看起来对”就直接合入。长任务会漂移一个会话里塞太多任务Agent 会在后面忘记前面的约束。关键约束必须落在文档里而不是对话历史里。会自信地幻觉 API它可能写出并不存在的方法名或者用错依赖的版本。这是当前所有代码生成模型的通病只能靠测试和 review 兜底。一句话总结Agent 像一位学习能力很强但经验不足的同事。你能给它多清晰的指令它就能给你多稳定的产出。3. Claude Code 的安装与 VS Code 集成3.1 环境准备以目前社区讨论最多的 Claude Code 为例安装前的环境要求并不高操作系统macOS 或 Linux 均可Windows 用户建议使用 WSL2。Node.js需要 18 或更高版本具体以官方安装要求为准。包管理器npm用来安装 CLI。Git仓库操作和 diff review 需要。账号Anthropic 账号或可用的 API Key也可以在首次启动时用官方登录流程完成认证。如果本机已经有 Node.js可以在终端里先确认版本node -v npm -v3.2 安装 Claude Code CLI使用 npm 全局安装是常见的安装方式npm install -g anthropic-ai/claude-code安装完成后在任意项目目录里输入claude即可启动。首次启动时会走一遍登录或 API Key 配置流程。如果你使用 API Key也可以通过环境变量传入export ANTHROPIC_API_KEY你的API Key需要提醒的是模型名称和账号套餐对应的可用模型可能在不同时期有差异不要照抄网上的命令参数以你当前账号在官方界面里能看到的信息为准。最简单的验证方式是启动后输入/status这个命令可以查看当前会话的模型、上下文字数消耗和会话模式。3.3 VS Code 集成配置很多人在搜索“vscode 配置 claude code”说明大家最习惯的场景还是在编辑器里用 Agent。在 VS Code 里接入 Agent 有两条路线第一条是直接在 VS Code 的集成终端里运行claude。这样做的好处是 Agent 天然继承了当前工作目录、Git 状态和终端环境非常适合在真实仓库里操作。第二条是安装官方 VS Code 扩展。安装后在活动栏会出现对应的图标可以新建会话、查看权限请求、检查已生成的 diff。它和终端里的 CLI 共享同一套核心能力只是界面更贴合编辑器习惯。无论哪条路线真正影响体验的是仓库级的权限配置。建议在项目根目录创建.claude/settings.json把高频命令放进允许列表把敏感文件放进拒绝列表{ permissions: { allow: [ Bash(npm run test), Bash(npm run lint), Bash(git diff), Read(README.md), Read(src/**) ], deny: [ Edit(**/.env), Bash(rm -rf **), Edit(secret/**) ] } }不同版本的配置字段可能会有调整以你安装版本的官方文档为准。但“允许安全命令、拒绝敏感路径”的原则是通用的。配置完之后再在 VS Code 里新建一个会话Agent 才会在既定的权限范围内干活而不是每步都弹权限窗口。3.4 会话启动与退出在项目根目录启动会话时建议保证仓库是干净的至少你要知道当前有没有未提交的改动cd your-project git status claude会话中常用的斜杠命令包括/clear清空上下文、/model切换模型、/status查看会话状态。退出会话直接输入/exit即可。4. 核心工作流让 Agent 稳定产出的四个步骤工具装上只是第一步。真正让 Agent 从“偶尔能帮上忙”变成“可依赖的编码协作者”靠的是一套稳定的工作流。4.1 让仓库成为 Agent 的“可读上下文”Agent 第一次进入项目时对仓库是陌生的。它需要通过 README、目录结构、测试文件来建立认知。如果你的仓库 README 是空的入口不清晰Agent 就会花大量时间在错误的位置找代码。更高效的做法是在仓库根部维护一份项目说明文档。Claude Code 这类工具通常会在每次会话时自动读取约定的说明文件。在文档里写清楚项目的技术栈和运行方式。入口文件和核心目录的作用。常用的 npm 脚本比如测试、构建、lint 命令。代码规范和命名约定。禁止修改的目录或配置文件。这份文档不仅是给 Agent 看的也是给新同事看的维护成本很低收益却很大。4.2 用“任务说明书”代替一句话指令一句话指令是最低效的 Agent 用法。“帮我优化订单模块”这种描述Agent 只能猜。实践中我习惯用一个固定的任务模板背景订单模块目前使用同步接口高峰期有超时风险。 技术栈Node.js Express PostgreSQL。 相关入口src/routes/order.jssrc/services/orderService.js。 任务将订单状态查询改为支持简单的 TTL 缓存缓存时间 30 秒。 验收标准 - 单元测试覆盖命中缓存和缓存过期两个场景。 - 不修改订单创建和支付相关逻辑。 - 不允许引入新的核心依赖。 禁止改动src/services/paymentService.js。这个模板的核心是“约束前置”。验收标准解决了“做到什么程度算完成”禁止改动解决了“Agent 擅自扩大修改范围”的问题。在实际项目中任务描述越具体Agent 的返工次数越少。4.3 先要计划再允许执行不要让 Agent 直接开始改文件。在会话里先发出指令请先读取相关文件给出实现计划。计划必须包含 1. 要读取哪些文件。 2. 计划创建或修改哪些文件。 3. 测试用例的设计思路。 4. 潜在风险点。 确认计划后再动手。这一步可以过滤掉大量“方向错误”的修改。如果 Agent 的计划里出现了你不认可的设计直接指出来让它重新规划。计划阶段的时间成本远远低于修改完文件再 review 的时间成本。4.4 测试先行用失败结果驱动修正计划确认后让 Agent 先写测试再写实现。这听起来有点反直觉但在 Agent 模式里效果很好请先为上述需求补充测试用例并运行测试看到失败。 然后根据失败结果实现功能直到测试全部通过。测试先行有双重价值。第一测试文件本身是对需求的二次确认第二Agent 在“看到测试失败再修复”的循环里会减少凭空发挥的概率。如果 Agent 直接写出了大量实现但测试文件几乎没覆盖关键分支这类代码反而更危险因为它看起来能跑实际上没有验证过边界条件。5. 完整示例让 Agent 完成一个真实小任务为了说明实际操作这里用一个最小 Express 项目演示“任务说明书 测试先行 Agent 迭代”的完整链路。5.1 项目现状项目目录结构如下my-app/ ├── package.json ├── src/ │ └── app.js └── test/ └── app.test.js现有src/app.js是一个简单的 Express 应用// src/app.js const express require(express); const app express(); app.get(/hello, (req, res) { res.json({ ok: true, pid: process.pid }); }); app.listen(3000);5.2 向 Agent 提出任务在项目目录启动claude输入背景当前 Express 应用没有任何请求日志线上排查问题很困难。 任务在 src/middleware/requestLog.js 中新增一个请求日志中间件。 要求 - 记录 method、path、status、耗时毫秒。 - 不记录请求体避免泄露敏感数据。 - 日志输出为 JSON 单行使用 console.log。 - 在 src/app.js 中全局启用。 验收标准 - test/requestLog.test.js 中补充测试覆盖正常请求和 404 两个场景。 - 使用 node --test 运行测试全部通过。 禁止改动test/app.test.js。5.3 Agent 产出的实现一次典型的 Agent 产出大致包含三个文件。中间件实现// src/middleware/requestLog.js function requestLog() { return function (req, res, next) { const start process.hrtime.bigint(); res.on(finish, function () { const durationNs process.hrtime.bigint() - start; const durationMs Number(durationNs) / 1e6; const line { time: new Date().toISOString(), method: req.method, path: req.originalUrl, status: res.statusCode, durationMs: Number(durationMs.toFixed(2)) }; console.log(JSON.stringify(line)); }); next(); }; } module.exports requestLog;改造后的应用入口// src/app.js const express require(express); const requestLog require(./middleware/requestLog); const app express(); app.use(requestLog()); app.get(/hello, (req, res) { res.json({ ok: true, pid: process.pid }); }); module.exports app; if (require.main module) { const port process.env.PORT || 3000; app.listen(port, () { console.log(listening on ${port}); }); }对应的测试文件// test/requestLog.test.js const test require(node:test); const assert require(node:assert/strict); const http require(http); const requestLog require(../src/middleware/requestLog); const app require(../src/app); function withServer(expressApp) { return new Promise((resolve) { const server expressApp.listen(0, () { resolve({ server, url: http://127.0.0.1:${server.address().port} }); }); }); } test(requestLog 输出结构化日志, async () { const appWithLog (req, res, next) { next(); }; // 使用插桩方式捕获 console.log 输出 const logs []; const oldLog console.log; console.log (line) logs.push(line); const { server, url } await withServer(app); const res await fetch(${url}/hello); await new Promise((resolve) server.close(resolve)); console.log oldLog; assert.equal(res.status, 200); assert.equal(logs.length, 1); const parsed JSON.parse(logs[0]); assert.equal(parsed.method, GET); assert.equal(parsed.path, /hello); assert.equal(parsed.status, 200); assert.ok(parsed.durationMs 0); });这个测试示例里其实还有一个问题appWithLog变量没有用上这是 Agent 在生成代码时留下的小瑕疵。它不影响测试结果但在 review 时应该被指出来。Agent 模式的一个常态是它产出的代码大部分可用但总有少量“不优雅的残留”review 的价值就在这里。5.4 运行与验证在项目根目录执行npm install express node --test预期输出中requestLog.test.js的测试应该通过。然后启动应用做一次手动验证PORT3000 node src/app.js curl -s http://127.0.0.1:3000/hello应用终端会打印一条日志{time:2025-01-01T12:00:00.000Z,method:GET,path:/hello,status:200,durationMs:0.85}到这里这个最小任务就跑通了。6. 运行结果与效果验证如何判断 Agent 干得好不好很多用户做完一个任务后只会看“测试过没过”这在 Agent 模式下远远不够。完整的验证序列应该是测试是否真的跑了。Agent 可能只生成了测试文件但没有真正运行。你需要看到node --test的真实输出而不是它告诉你“测试应该通过”。diff 范围是否可控。执行git diff --stat确认改动文件数量与任务预期一致。如果 Agent 顺手改了三个无关文件立刻让它还原。关键分支是否有测试覆盖。不要只看覆盖率数字而是问自己请求成功、请求失败、参数异常这三个分支测试里有没有命令是否在正确目录执行。Agent 有时会在错误的路径下运行命令导致测试通过是假象。依赖是否被不必要地引入。检查package.json的 diff新增依赖必须说明理由。如果任务中有任何一项验证不通过正确的做法不是自己上手修而是把失败信息完整贴回会话要求 Agent 解释根因后再改。最忌讳的是“Agent 改一版你手动修三处”这样你会永远离不开手动兜底。7. Agent 开发常见问题与排查方法实际使用半年下面这些问题是出现频率最高的按现象、原因、排查、解决的顺序列出来问题现象可能原因排查方式解决方案Agent 修改范围超出任务预期任务描述缺少“禁止改动”约束执行git diff --stat查看改动文件列表在任务模板中增加禁止改动目录必要时回滚后重新执行代码越改越乱陷入修复循环根因定位错误缺少失败信息回看最近几次命令的报错输出把完整报错贴回会话要求“先说明根因再修改”无效则新开会话前面说好的约束后面被遗忘上下文过长关键约束被稀释查看会话上下文长度将关键约束写入仓库说明文档新开会话时重新引用写出了不存在的 API 或方法模型幻觉对依赖版本不了解看运行报错检查依赖版本要求 Agent 先查官方文档或读取本地依赖类型声明禁止凭记忆猜 API权限弹窗频繁或命令被拒绝权限配置过严查看会话中的权限请求记录在 settings.json 里按需 allow 安全命令不要全局放行测试通过但集成后失败环境差异测试覆盖不足对比本地环境与目标环境补充集成测试在更接近生产的环境里重跑登录或 API Key 认证失败凭据过期或账号额度不足查看claude启动时的输出重新登录或检查账号订阅与 API Key 状态确认网络能正常访问服务所在域排查时建议遵循一个固定顺序先看 Agent 最后几条操作输出再看当前 git 状态确认它到底改了什么然后手动重跑一次失败的命令拿到真实报错。大多数问题在“看到真实报错”的瞬间就能定位难的是 Agent 有时候会自己把报错“处理”掉让问题消失但根因还在。所以只要发现 Agent 开始用“应该是”来解释代码行为就要提高警惕让它给出可验证的证据。8. 最佳实践与工程建议8.1 把需求说明书当成一等公民在纯 Agent 模式里需求说明书就是源代码。任务描述的质量直接决定产出的质量。团队里可以沉淀一套任务描述模板至少包含背景、相关文件、任务、验收标准、禁止改动五段。模板一旦固定Agent 的产出质量会明显稳定。8.2 一个任务一个分支不要让 Agent 在一个会话里连续完成多个任务。更稳妥的做法是每个任务新建一个分支Agent 在分支上独立工作人 review 通过后再合并。这样既方便回滚也方便保留 Agent 的完整操作留痕。分支名可以直接用任务编号例如feat/order-cache。8.3 用测试当验收证据“Agent 说做完了”不等于“做完了”。所有任务都以测试结果为准。如果项目本身测试覆盖很差可以先让 Agent 补一个最小测试骨架再开始业务开发。把“先有测试再写实现”变成默认流程而不是可选项。8.4 权限最小化与敏感信息隔离Agent 能够执行命令这是一把双刃剑。生产环境、密钥文件、无备份数据这些场景尽量别让 Agent 触碰。配置层面建议把.env、密钥目录、数据库凭据文件全部加入 deny 列表。同时不要在对话里粘贴真实的密钥、Token 或敏感客户数据因为你无法完全控制模型日志的存储策略。8.5 明确哪些场景不适合 Agent不是所有代码都适合交给 Agent。涉及支付、权限、加密等安全敏感逻辑必须人工逐行 review且最好由有经验的人把关。需求本身还没想清楚的探索性任务也容易让 Agent 走进错误方向。还有一类场景是“只改一行”的紧急修复直接手改通常比和 Agent 讨论更快。工具是加速器不是所有流程都要硬套。8.6 团队落地建议团队引入 Agent 时最容易踩的坑是“每个人各玩各的”。建议从三件事开始统一第一统一使用同一款 Agent 工具和相对固定的模型版本第二统一任务说明书模板第三统一 review 规则比如测试必须是真实运行的、diff 必须在合并前人工确认、依赖变更必须说明理由。在此基础上再逐步把 Agent 的常见失败案例沉淀成本团队的排查手册。9. 总结与后续学习方向六个月“只用 Agent 写代码”的模式最终改变的不是代码量而是整个开发的注意力结构。人在这个模式里真正花时间的地方变成了需求定义、计划评审、diff review 和验收验证。Agent 能不能成为可靠的协作者很大程度上取决于你愿不愿意把这些前置工作做扎实。如果你还没有真正跑通过一个 Agent 任务下一步可以这样开始挑一个你非常熟悉的小需求用本文第五节的任务模板写清楚让 Agent 实现并配套测试然后重点观察它读了你哪些文件、执行了哪些命令、在哪个环节开始偏离你的预期。第一次跑通后你会发现真正的学习关卡不在安装而在“如何把一个模糊想法翻译成 Agent 能执行的精确指令”。建议收藏这篇文章之后在 VS Code 里被 Agent 改崩代码时再回来看第七节和第八节。祝你的第一个纯 Agent 任务顺利通过 review。
阅读完成 · 觉得有帮助？
