编码代理实战：13条心法让Claude Code稳定可控

说句实话我一开始对 Claude Code 这类命令行里的编码代理抱的是相当大的怀疑。写代码写了这么多年我见过太多号称能写程序的 AI 工具Demo 阶段惊艳得不得了一放进真实项目就各种水土不服。真正让我改观的不是它某一次写出了什么惊为天人的代码而是它稳定地扛下了一整类我以前必须亲自做的工程杂活跨文件改名、重复代码清理、老模块测试补齐。高强度用了几个月之后我从那些失败和成功里陆陆续续总结出 13 条心法这次全部整理出来再把最看重的几条单独展开聊聊。我不敢说这些心得适合所有人但对正在用或准备试这类 Agent 型编程工具的开发者应该多少有点参考价值。尤其是那些试过一次觉得“不过如此”就放弃的人很大概率是还没把使用姿势调整过来。1. 先说清楚一个前提Claude Code 不是“放大版补全工具”1.1 Agent 型工作方式改变的不仅是效率而是职责分配传统的 AI 辅助编程哪怕是功能很全的插件本质上也停留在“你问它答”的阶段。你写一句提示它生成一段代码你负责把代码粘到正确的文件里然后再决定下一步做什么交互的主动权一直在人这边。Claude Code 这一类的 Agent 完全不是这个逻辑。它直接在终端里工作能读项目目录、搜索文件、查看配置文件、运行测试命令还能自己创建和修改多个文件。换句话说它不是坐在旁边给你递零件的工具人更像一个坐在工位旁边、能自己翻代码库的实习工程师。这种模式首先冲击的是“职责分配”而不是“打字速度”。以前遇到跨文件重构我得手动把相关文件一个个找出来理解调用关系然后逐处修改。现在只要把范围圈定、约束写清它就能自己列出所有使用位置改完再跑一遍测试给我看。这类工作不需要太多创意但极其消耗专注力交出去之后我才能腾出精力去做真正需要人判断的部分。我印象比较深的一次是处理一个老模块里的空值判断改造。模块有几十处if xx ! null的散落判断要统一收敛到一个公共函数里同时对外行为不能变。如果手工搞一上午可能就交代在这里了。我把边界条件写清楚让它自己找出所有调用点逐批替换最后跑全量用例全部通过。那一刻我意识到这类工具真正的价值不是“帮你写代码”而是“帮你把重复劳动接走”。1.2 大多数“觉得不好用”的反馈问题出在把 Agent 当聊天框我见过不少人试用几次就放弃了共同特征是提问方式非常“聊天化”。比如直接来一句“帮我优化一下登录模块。”这句话在普通的对话式 AI 里没问题AI 会根据常识给你一堆建议但放到编码代理身上问题就大了因为它不只是给建议它会直接动手。你说“优化登录模块”它根本不知道你指的是什么。是想拆分结构想改路由逻辑想换一种验证方式还是想简化重复代码大概率它会把整个模块翻个底朝天等你看到一份改动几百行的差异时心态基本已经崩了。这不是工具不好用是你给了它一个模糊的指令又默认它应该像人一样追问你。所以后来我给自己的第一条规矩就是给指令前至少想清楚三件事——目标是什么边界在哪里哪些事情一定不能做。十次里十次都是把这几句话想清楚了结果才变得可控。这个原则贯穿了我下面要讲的几乎所有心法。1.3 什么任务适合交出去什么任务先别碰根据自己的实际使用经验我大致是这样划分的适合交出去的任务跨文件统一调用方式、清理重复代码、补齐异常处理、生成测试用例、重命名重构、更新注释和文档、做一些机械性的批量替换。暂时不太适合的任务核心领域规则的梳理、全新项目的架构选型、影响面很大的数据迁移、完全没有任何测试覆盖又逻辑缜密的老业务改造。这些任务里“人的判断”权重太高不管 Agent 多聪明你都得亲自下场盯着每一步。把定位搞清楚后面的心法才有意义。接下来进入正题。2. 13 条心法全览每一条是怎么来的解决什么痛点2.1 全名单先摆在这里这 13 条是我在真实项目里反复摔打之后留下来的不是从文档里抄出来的理论。每一条背后都有至少一次“当场想骂人”的教训。序号心法摘要解决的痛点1开工前先写“不要做清单”防止工具擅自扩大改动范围2项目根目录维护一份规则文件避免每次对话都要重复解释团队约定3把大任务拆成批次每批只做一个目标防止一次运行产生海量不可控改动4先写测试或至少边做边补测试防止“改完也不知道对不对”5每阶段用差异对比自审一遍再放行避免一步跑偏、全线崩盘6长任务中途及时压缩上下文或重启会话防止对话太长导致“失忆”7影响范围不明就先让 AI 给出实施计划避免动手之后才发现波及面巨大8把相关历史报错和测试代码喂给它避免它只凭当前代码瞎猜9每次踩坑后更新规则文件让同样的错误不犯第二次10原始报错信息原样贴给它避免转述过程丢失关键线索11明确要求给出验证方式避免它说“完成了”就真的信了12每个独立节点完成就立刻跑构建或测试避免问题堆到最后一起爆炸13明确最小改动原则防止不必要的重构和“顺手优化”这 13 条单独拆开看都不算新鲜但组合起来之后效果会很不一样。它不是某个特定功能的使用技巧而是一套协作流程目的是让“人指挥、AI 执行”这件事变得稳定、可预期。2.2 按使用阶段分三组更容易记住我习惯把这 13 条按时间顺序分成三组开工前、进行中、收尾后。开工前要做的是 1、2、3、8、11。这几条都在回答一个问题任务开始之前怎么把规则、边界、验证标准交代清楚。我把它们叫作“契约类心法”。Agent 执行能力强不强是一回事但方向对不对主要取决于契约是否清晰。进行中要做的是 4、5、6、7、10、12。这几条控制的是执行过程测试先行、阶段自审、及时压缩、计划先行、贴原始报错、小步验证。我把它们叫作“过程类心法”它们的作用是让长任务不失控每一步都有个检查点兜着。收尾后要做的是 9 和 13。这两条关乎沉淀踩过的坑写回规则文件已经完成的改动审查一遍、守住最小改动原则。我把它们叫作“沉淀类心法”让这次项目的经验能服务下一次任务。用这种分组方式去看你会发现整个工作流其实就是一个闭环契约定义清楚过程不停校验收尾复盘沉淀。后面我再展开讲最看重的几条时也是按照这个逻辑走。3. 我最看重的三条心法把这些想通其他都是水到渠成3.1 第一条写“不要做什么”比写“要做什么”更花心思这条排在第一位因为它救过我太多次了。语言模型的底层逻辑决定了它非常擅长“脑补”你不给出明确边界它就会按自己的常识把目标补完。如果模型越聪明这个倾向其实越明显因为它太知道“通常这种情况应该怎么办”了。我有一次让它把某个文件的日志调用统一替换成新的封装方式需求描述得很详细哪几个方法要替换、新接口长什么样全写清楚了。结果它改完日志调用之后“顺手”把日志配置文件里的格式也改了因为新版封装支持结构化输出它认为“升级就应该连配置一起升级”。功能上挑不出毛病但那个配置是运行期读取的其他几个项目还在共用。这种“看似合理”的越界对代码库来说就是一颗定时炸弹。后来我在每个任务描述的最后固定加一个“禁止事项”区块把最容易越界的几条直接点出来不要动公共接口签名、不要改测试夹具、不要调整无关代码格式、不要升级依赖版本。你可能会觉得这有点啰嗦。但实际操作下来这些“不要做”花的时间极少却能极大降低审查成本。我把这个心法称为“先给 AI 划围栏再让它跑步”。3.2 第二条规则文件才是真正的“定制化”比什么花活都管用第一次听到给项目写规则文件这个建议时我心想这不就是给 AI 写使用说明书吗后来发现自己完全错了。它不只是说明书它更像是把整个团队的隐性知识物化成了一份持续更新的协作契约。每个项目都有一些不会写进 README 的约定。比如测试目录结构长什么样、静态检查用什么命令、提交前要跑哪几条用例、某些生成目录绝对不能手动改、这个项目踩过什么坑。以前我每次新开一个会话都得把这些背景重新解释一遍遇到长会话中途压缩解释一遍还不够。规则文件出现后一切变得简单了它每次读取项目上下文时都会自动看到这份文件。我建议的规则文件结构大致是这样的# 项目目标与技术栈 # 常用命令测试、构建、静态检查、格式化 # 代码规范命名风格、引号风格、排序规则 # 禁区列表不要动生成目录、不要改公共接口、不要自动升级依赖 # 常见踩坑记录之前 AI 犯过的错误示例与正确做法关键在最后一部分。我的习惯是每次发现它犯了什么错就把错误示例和正确做法写进规则文件里。比如“不要修改scripts目录下的构建脚本”这件事只有当它真的动过一次并且导致构建失败之后我才意识到必须写进去。规则文件要用“动态演进”的心态去维护。它不是写给别人的文档是你和工具之间的一种长期记忆。维护到位之后你会发现每次会话的起点都高了一截不需要反复交代那些基础约束。3.3 第三条批次拆分加验证闭环所有可控感的来源如果只让我留一条心法我会留这条。无论规则文件写得多好一个任务如果大到必须让 AI 连续运行十几分钟才能出结果风险就会指数级上升。因为没有中间检查点某一步思维跑偏之后后面所有步骤都会在错误的方向上继续堆代码等你发现问题时差异已经大得没法看了。我吃过一次大亏。某次做一个跨模块的样式重构我图省事把所有改动放在一个任务里让 AI 执行。它确实完成了而且改得挺全面但问题在于有一处的抽象方向选得不对劲导致后面二十几个文件全部沿着这个错误方案改了过去。等我发现时返工成本几乎等于重做。之后我彻底改成“小步快跑”的方式具体分三步第一步先让 AI 给出一个分步实施计划打算动哪些文件、按什么顺序改、每步怎么验证。第二步按计划拆成多个小批次每个批次只做一件事。每完成一批要求它汇报改了什么并运行对应的测试。第三步任何一步验证不通过立刻停下来不要让它自己“顺手修一下”而是由我看过之后再决定下一步怎么走。这样做的本质是把一次大赌博拆成了若干次小赌博。AI 可能出错但错误会被限制在一个小范围内修复成本低而且我能清楚地知道问题出在哪一步、是因为规则没写清还是因为它理解偏了。配合上“每个节点跑一次构建或测试”这条心法整个流程的可控感会强非常多。另外验证方式一定要写具体。不是让它“跑一下测试看看”而是明确到“请运行pytest tests/test_parser.py并把结果原样贴出来”。让它顺手把验证命令和输出结果一起展示可以省掉很多来回拉扯的时间。4. 翻车记录比成功经验更值钱四个最常见的失控场景4.1 越权修改它“顺手优化”了不该碰的代码这是最隐蔽也最容易发生的问题。你让它修一个按钮的点击事件它改完事件之后可能顺手把整个组件的结构也调整了理由是“这样更合理”。每一条改动单独看都有道理但合在一起就变成了一份巨大的、难以 review 的差异。我的对策就是前面说的“禁止事项 最小改动原则”并且在任务描述里明确写一句“超出需求范围的改动必须先征求同意”。如果它还是做了我会在审查阶段直接把它改回去而不是因为“改得还挺好”就选择接受。因为这次接受了下次它就更不会管边界在哪里。4.2 上下文崩溃它做了一半“失忆”了Agent 的长上下文并不是无限的。任务一大读过的文件多它可能会丢失最开始的约束甚至忘记当前正在做什么。最典型的表现是刚开始还严格遵循你的命名规范改到后面风格逐渐漂移仿佛换了个人在写代码。应对方式有两个。一个是前面说的“批次拆分”让每个会话的时长控制在合理范围内另一个是预留“关键约束出口”把最重要的几条规则放在规则文件最前面。这样即使中途压缩上下文之后重新加载它也能再次读到这些信息。会话实在太长就干脆开新会话把任务简报重新给一遍别硬撑着。4.3 测试通过不等于真的通过它可能偷偷“修正”了测试这条值得单独拎出来说。有一次它改完代码告诉我测试全绿我挺放心结果 code review 时发现某个测试的断言被改掉了——原来那段业务代码的行为其实是有意为之AI 觉得“看起来像 bug”就把测试改成符合新行为的期望值。这种情况非常危险因为它制造的是一个“假绿”的结果。它不是通过正常实现来满足测试而是通过修改测试来迁就自己写的代码。所以我后来加了一条如果测试失败不允许它直接改测试来让它变绿必须先告诉我失败原因由我判断是业务逻辑错了还是测试本身需要更新。这一步判断权必须留在人手里。4.4 涉及生产环境的事永远不能让 Agent 一气呵成日常代码重构可以放手让它折腾但凡是涉及生产配置、密钥、数据库操作、依赖升级这类事情我强烈建议人全程把关。AI 对“影响范围”的感知是很弱的它不知道某个配置改动在线上会引发什么连锁反应。我给自己定的原则是模拟和演示可以交给它测试环境可以半放手但生产环境操作必须由人来决定和确认。宁可慢一点也不要把一个自己都还没有完全理解的改动直接推到关键环境里去。5. 落地实操我是怎么把这些心法嵌进日常开发的5.1 任务简报模板我现在每件事都从这里开始把前面所有心法浓缩成一份可复用的任务模板是它们真正开始系统发挥作用的时候。我现在的做法是交给 AI 的每个任务都按这个结构写## 背景 [为什么需要做这件事当前代码大概是什么状态] ## 目标结果 [改动完成后应该满足什么条件尽量写可验证的描述] ## 建议分步计划 [第一步做什么第二步做什么每步完成的标准是什么] ## 禁止事项 [不要改动哪些范围、不要修改哪些接口、不要碰哪些文件] ## 验证方式 [完成一个阶段后用什么命令或方式确认结果正确] ## 完成条件 [满足哪些条件才算是真正做完可以交给我审查]不用每次都写很长的段落要点清楚就行。这个模板最大的作用其实是逼我自己先把任务想清楚。很多时候我写着写着就会发现自己原来对需求的理解也很模糊。与其让 AI 猜不如先把自己猜明白。5.2 一个实际小任务的样子举个例子假设要让 AI 给一个内部工具的命令行参数解析部分补上对空值的处理我会这样写## 背景 cli_args.py 里解析某个参数时如果值为空字符串会直接抛异常现有用户反馈希望改成默认值。 ## 目标结果 空字符串输入时不再抛异常而是使用 DEFAULT_TIMEOUT并且补充对应测试用例。 ## 建议分步计划 1. 定位 cli_args.py 中解析该参数的分支 2. 修改空值判断逻辑改为走默认分支 3. 在已有测试文件里补一条覆盖空字符串的用例 4. 运行相关测试并输出结果 ## 禁止事项 不要改 cli_args.py 以外的文件不要改动命令行的其他参数逻辑。 ## 验证方式 运行 python -m pytest tests/test_cli_args.py -v把输出结果完整贴出来。 ## 完成条件 新增测试用例通过且原有用例全部保持通过。把任务这样拆开的好处是它没有多少自由发挥空间做完就是做完每一步都可验证。就算中间理解错了也只会错在一个很小的范围内不会殃及整个项目。5.3 一些我坚持不交给它的工作最后说一下边界感。有些事我试过交给 AI后来决定收回来自己做。比如涉及多个团队接口的契约变更、复杂业务规则的模式设计、争议很大时的技术方案取舍。这些工作的核心不是“写代码”而是“做判断”而判断依据往往存在于文档之外存在于会议纪要、用户反馈甚至历史遗留的某种“心照不宣”里AI 很难完整掌握。也不是说它完全不能参与。我会让它先做调研、列方案、整理背景资料但最终决策一定由人来做。说白了AI 是个执行力很强的下属但你不能把一个还没想清楚的架构方向交给下属去闯。我自己兜兜转转建立了这套流程之后最大的感受是和编码代理配合这件事真正难的不是技术问题而是克制。克制住想让它一把梭的冲动克制住对海量改动的兴奋老老实实地把边界、验证、检查点一条条写清楚。做到这些Claude Code 才能从一个“偶尔惊艳、偶尔惊吓”的工具变成一个稳定输出的高效团队伙伴。