三招驯服Claude Code：从人工智障到代码智能持续进化

1. 先别急着骂“人工智障”先搞清它为什么“智障”用 Claude Code 写了几个月项目我最大的体会是绝大部分“人工智障”时刻问题不在模型而在使用姿势。刚上手那阵子我也没少踩坑——让它改一个函数它能把注释、相邻方法、另一个文件全部顺手改一遍让它写个模块第一版看着挺完整一跑用例全是边界问题最崩溃的是昨天刚叮嘱过的项目规范今天它就像失忆一样。这不是我一个人遇到的情况。办公室里几个同事初次试用这类编程助手时都得出了类似的结论“这就是个话多一点的补全插件。”直到后来我花了一段时间专门研究它的工作方式才意识到Claude Code 本质上不是“一个聪明的自动编程器”而是一个“知识渊博但对你项目一无所知的新同事”。它脑子里装着海量通用知识却不知道你的目录结构不知道你们的编码规范不知道哪些模块是碰都不能碰的老古董。下面这三招不是什么提示词魔法也不是突然让它开窍的咒语而是三条我从多次翻车现场里总结出来的工程原则把背景知识沉淀成项目里的文件让它每次都能读到把大任务拆成边界清晰、可验收的小契约把“对不对”的裁判权交给测试和静态检查而不是肉眼。这三招合起来才能真正让 Claude Code 从“偶尔聪明的玩具”进化成“能持续交付的团队成员”。不管你是刚下载完工具的新手还是在团队里推广它、正被各种迷之行为折腾的老手这套方法都值得一试。下面我从问题根源讲起再逐招拆解最后给一个完整的实战流程和排障手册。1.1 它缺的不是智商而是背景知识先做一个实验。你把 Claude Code 打开什么都不说直接让它“优化一下项目里那个订单模块的查询效率”。它的内心状态大概是这样订单模块在哪儿用的什么数据库查询慢是慢在 SQL 还是慢在 N1还是索引没建它完全不知道但它又不会一直追问于是它凭通用经验推测既然你说优化查询效率那我给你把整个查询流程重写一遍吧。结果就是它改了一大堆不该改的东西还理直气壮地告诉你它优化了什么。这不是它蠢而是你把一个信息严重不足的问题丢给了它。它只能按照自己见过的通用模式来推测而通用模式放在你的具体项目里大概率就是灾难。我后来把这类问题统一归为“背景知识缺失”。解决方式不是每次都把项目背景在对话里重新讲一遍——那样既累又容易漏而且换一个会话你之前讲的东西全都没了。正确做法是让背景知识独立于“对话”存在成为项目里的一部分。这也正是第一招 CLAUDE.md 方案要解决的问题。1.2 记忆机制为什么上轮说完这轮就忘很多人第一次被气到往往是这种情况上一轮对话里我刚告诉它“这个服务不能直接改数据库必须走消息队列”它答得特别好还承认记住了。下一轮接着让它做点别的它又直接写了一段操作数据库的代码。原因在于它的记忆机制。对话里的内容属于上下文窗口你可以把它理解成一张有限宽度的便签纸每轮对话都会往这张纸上写新内容当内容积累到上限或者你开启新会话时早前的便签就被挤掉了。所以它在同一段对话里确实能记住一些事情但跨对话之后它对你项目的一整套规则没有任何持久记忆。所以靠“在对话里口头叮嘱”是不可靠的。真正可靠的是把规则写进它每次启动对话都会自动加载的文件里。这样不管换了多少轮对话它都会在第一时间读到相同的背景信息。这个文件就是接下来要重点讲的 CLAUDE.md。1.3 正确姿势把它当成一个“必须带说明书的新成员”我后来在团队里分享了一个比喻Claude Code 不是外包团队而是一个刚入职、能力很强但什么都不熟的新成员。你招了一个新人会给他什么项目文档、规范链接、代码结构说明、常见坑位提醒。你肯定不会指望他第一天就懂你们所谓“其实大家都知道”的潜规则。当我把这个视角转过来之后所有“智障行为”都有了合理的解释也有了对应的治理方案。这三招本质上就是一套“新人入职培训体系”第一招是发给他《项目手册》第二招是给他发清晰的任务单第三招是让他做完必须过自动化检查才能提交。下面是第一招。2. 第一招用 CLAUDE.md 把项目“宪法”焊进文件里2.1 什么是 CLAUDE.md为什么要建它CLAUDE.md 是 Claude Code 在项目里会自动读取的说明文件。名字里的 CLAUDE 指的是这个工具自身md 表示它是 Markdown 格式。你可以把它理解成项目的“宪法”它不参与业务逻辑不写任何代码但每次 Claude Code 启动、每次在项目里执行操作时它都会把这份文档当作最基础的背景来读。为什么不是 README因为 README 是给人看的往往夹杂了大量与编码无关的安装步骤、宣传文案和使用说明。CLAUDE.md 是专门写给模型看的它的内容应该围绕“如何在本项目中正确工作”来写。这两件事完全不同。我在项目里建了 CLAUDE.md 之后最直观的变化是Claude Code 不再把项目结构猜来猜去了不会随手乱建目录遇到老模块时会主动提醒“该模块不宜大规模改动”。这效果不是我一条条在对话里吼出来的而是因为它每次都会读到所以表现才稳定。注意不同版本的 Claude Code 对自定义说明文件的命名和加载规则可能稍有差异建议先看一眼工具文档确认它支持的文件名和放置位置。多数情况下项目根目录下的 CLAUDE.md 是默认会被加载的。2.2 一份能直接改的 CLAUDE.md 模板写这个文件不需要特别复杂的格式核心是“短句、具体、可执行”。我一般按下面几个区块来组织# 项目概述 - 这是一个订单管理服务主要负责订单创建、支付回调、库存扣减。 - 技术栈后端使用某框架前端是某页面应用数据库用某关系型数据库。 - 仓库根目录下 src/ 是主代码src/old 是历史遗留模块尽量不碰。 # 编码规范 - 新增文件必须写模块级注释说明职责。 - 函数超过 50 行必须拆分。 - 禁止在业务代码里直接拼 SQL统一走数据访问层。 - 错误信息统一用中文日志用结构化 JSON。 # 架构约束 - 订单模块只能通过消息队列通知库存模块禁止直接调用库存服务的内部方法。 - 老的 src/old/ 目录依赖很乱如无特别需求不要改动。 - 对外接口的返回结构保持 { code, data, message }新接口必须一致。 # 工作流约定 - 每次改动前先列出影响范围。 - 提交代码前必须跑 npm run lint 和 npm run test。 - 如果需求涉及数据库变更必须先在文档里记录变更原因。这里需要特别注意写的时候别用“要优雅”“要健壮”“尽量保持高质量”这种无法检验的句子。模型虽然能理解但它很难判断自己做没做到写了等于没写。要用“必须……”“禁止……”“超过……就……”这样的可检验规则。2.3 写规则时的三条原则具体、可检验、分优先级第一具体。不要写“注意性能”要写“列表页接口单次查询必须走分页不允许一次性查出全部数据”。不要写“保持代码整洁”要写“公共函数需要加说明注释解释参数含义、返回值和可能抛出的错误”。第二可检验。好的规则是能被一个旁观者判断对错的。比如“禁止在循环里发起网络请求”这句话可以拿代码去对照检查。而“代码要清晰”这类表述每个人都有不同理解模型更没法稳定执行。你写进 CLAUDE.md 的每一条规则都应该能在 review 时被硬性检查。第三分优先级。文件里如果每一条都是强约束模型反而不知道优先照顾哪条。我通常把它分成“必须遵守”和“可以打破但要说明”两个级别。比如“必须遵守禁止直接改数据库表结构”是红线而“可以打破但要说明如果新增文件过多可以适当调整目录但需要在改动说明里解释”则是有条件的灵活性。2.4 常见的坑规则写了却不生效有次我把 CLAUDE.md 写得非常完整但实际用的时候Claude Code 还是我行我素。排查下来发现我把文件放到了子目录而它在项目根目录启动时根本不会主动加载那个子目录里的说明。后来我把文件移到根目录问题立刻解决。另一个坑是“规则太多导致互相打架”。比如一条说“所有网络请求必须封装成统一服务”另一条又说“按业务模块自由组织代码”模型可能会为了满足其中一条而违背另一条。解决办法是定期做减法只保留真正重要、与项目强相关的规则。还有一点特别容易踩CLAUDE.md 写完后在同一个已有会话里继续对话模型不一定立即按新文件执行。稳妥做法是保存文件后新开一个会话再测试。这也就回到了前面的观点——它是每次“入职”时读规则规则变了得让它重新入职一次。3. 第二招把大任务拆成“可验收的小契约”3.1 模糊指令是“智障行为”的第一来源第一招解决了“它不知道项目规则”的问题但还有一件事没解决即便它知道规则你让它做一件大而模糊的事它还是容易跑偏。“帮我优化一下登录逻辑”这种话如果对着真实的新同事说对方大概率得追着你问半天优化是指安全还是性能能改接口吗要不要兼容旧版本Claude Code 通常不会一直追问它会直接给你一个它认为最合理的方案。问题在于它认为的最合理和你脑子里的最合理往往不是一回事。与其事后骂它智障不如事前把任务写成一份合同。任务越模糊它的自由发挥空间越大最后偏离预期的概率也就越大。3.2 任务说明书三要素目标、边界、验收标准我现在给 Claude Code 派活基本都会包含三个部分目标这一段要实现什么效果服务谁解决什么问题。拒绝用“优化”“完善”“提升”这类无量化词。边界允许改哪些文件禁止改哪些文件是否允许动公共接口、数据库结构依赖是否可以新增。验收标准怎么判断完成了。尽量写成能命令式验证的比如“新增测试应覆盖三个用例”“所有现有测试不得失败”。这三个要素缺一个都容易出问题。没有目标它不知道方向没有边界它容易手贱没有验收标准它会觉得自己写完了但你觉得没写完。等你俩对“完成”的定义不一致时来回拉扯就已经开始了。3.3 实操示例从“改搜索页”到完整任务包举个例子。你说“把搜索页改好用点”它大概会给你重写一版前端、加一堆动画、还可能顺手改接口。但如果我按三要素写任务包目标优化当前商品搜索页让用户输入关键词后能在 1 秒内看到结果。 边界 - 只改 src/pages/search 下的前端代码。 - 禁止改动后端接口路径与返回结构。 - 可新增本地缓存逻辑但不得依赖新增第三方库。 验收 - 输入关键词后请求带防抖500ms 内只发一次请求。 - 空结果时有提示文案加载中有 loading 状态。 - 现有前端测试全部通过。这样一套写下来模型基本不会跑偏。它知道代码范围在哪里知道最后要过什么检查也知道哪些事情不能做。它甚至可以自己先生成一个检查清单按清单逐步执行——这比一句模糊的“改搜索页”靠谱十倍。收到任务包后你只需要确认它理解无误剩下的就交给它按步骤推进。3.4 动手前先让 Claude Code 复述计划我还养成了一个习惯把任务说明书丢给它之后不让它立刻写代码先让它输出一份执行计划。这个计划里要有影响到的文件清单、每步的改动内容、预计如何验证、有哪些风险点。等它复述完我再扫一眼发现不对劲的地方可以直接纠正避免改到一半才发现方向错了。这一步最大的价值不是省时间而是花小钱办大事。让它口头列计划几乎不消耗什么成本却能帮你过滤掉大量理解偏差。如果它连计划都写不清楚那说明任务说明书本身还要再改。记住模型不是不聪明而是太容易表现得像很聪明——它很擅长用流畅的表达掩盖理解上的空洞。4. 第三招用自动化反馈建“持续进化闭环”4.1 别信“看起来对”要让代码自己说话前两招能让 Claude Code“好好干活”但“好好干活”和“干得对”之间还有一段距离。代码是人写的也好模型写的也罢最终都得被机器验证。肉眼扫一遍觉得代码挺像样这种评判方式在和模型协作时会放大风险——因为模型的代码往往看起来特别像样。我有一次让它实现一个并发场景下的数据同步逻辑它生成的代码读起来逻辑完整注释还写得特别漂亮。放到测试环境一跑两个并发请求同时到达时直接出现重复写入。问题不难预料它没有考虑幂等。但你看代码的时候很难从表面看出这个问题。所以第三招的核心思路是把“对不对”的判断从人类肉眼转移到自动化工具。让测试、lint、类型检查这些本来就会用在开发流程里的手段成为和 Claude Code 协作时的强制关卡。4.2 最小闭环改、测、修、再测和 Claude Code 协作时我给它定了一条硬性要求改完代码必须自己跑测试测试挂了就自己修修完再跑直到全绿然后才准向我汇报。听起来是常识但很多人的用法是让它改完复制代码贴到编辑器里自己手动跑测试挂了再把报错贴回去让它修。这样也能工作但来回次数多而且模型在对话中看到的报错信息往往是截断的、不完整的修起来也费劲。更好的方式是让它在执行过程中自己调用测试命令。如果你用的工具支持执行 shell 命令可以在任务说明里加一句“每改完一个小步骤运行测试确认没有引入回归”。它就会把跑测试当成工作流程的一部分而不是最后交差时才做的一个动作。4.3 把 lint、类型检查、测试串进验收流程单独跑测试还不够我一般会在验收标准里叠加两层检查静态检查包括 lint 规则、类型检查、格式检查。模型写的代码很容易有隐藏的不规范比如未使用的变量、错误的类型标注、忽略异常这类问题静态检查一下就能抓出来。行为验证跑既有测试或者让它为新改动补测试。行为验证回答的是“功能对不对”静态检查回答的是“代码规不规范”。两者缺一不可。实操里我会在 CLAUDE.md 的工作流约定里明确写好提交前必须执行哪几条命令。比如npm run lint npm run typecheck npm run test并且在验收标准里写明“以上三条命令必须全部通过”。这样它每次改动都会主动跑一遍而不是等你去挑错。这套闭环跑顺之后你会发现它产出的质量会稳定很多因为“自检”已经成了它的工作习惯。4.4 进阶让 Claude Code 先写测试再写实现如果项目里测试覆盖本来就好我还会用一招更激进的让它先写测试再写实现也就是把 TDD 的工作方式交给它。具体做起来很简单在任务说明书里写清楚“第一步为需求补测试用例第二步运行测试确认失败第三步实现功能第四步运行测试确认通过”。这一套流程跑下来代码质量比我直接让它写实现要高不少。原因也好理解当它先写测试时它必须把需求理解成一组可验证的行为而不是一堆飘忽的“我觉得应该这样”。当然这个方式对测试基建有一定要求。如果你的项目到现在还没有任何自动化测试那就别急着让模型写测试先把最小闭环搭起来从“跑现有测试”开始。5. 三招合体的完整实战记录5.1 一次真实的“烂代码翻新”任务纸上谈兵说了这么多我拿一个简化版但真实发生过的任务把三招串起来走一遍。任务背景是项目里有一个遗留的数据导出模块代码又长又乱每次加一个字段都要改半天而且经常出现改坏其他导出的情况。需求是“重构这个模块让后续加字段更容易但现有导出结果不能变”。如果按旧习惯我会直接跟 Claude Code 说“重构一下导出模块”。现在我会先按第一招检查项目背景有没有写清楚然后把任务按第二招写成契约最后按第三招定好验收闭环。5.2 按三招执行的完整过程第一步我在 CLAUDE.md 里补了该模块的背景说明这个模块在 src/export被三个调度任务依赖输出格式有严格兼容要求禁止修改输出字段名最多只能内部重排代码。第二步我写任务说明书目标重构 src/export 模块让新增导出字段时不需要复制粘贴大量代码。 边界 - 只改 src/export 下的文件。 - 禁止改动任何导出结果字段名和顺序。 - 不得改变现有对外函数签名。 验收 - 现有 20 个导出相关测试全部通过。 - 新写 2 个测试验证新增一个字段只需在配置里加一行。 - 跑完 lint 和类型检查无新增错误。第三步我先让它输出执行计划。它给出的思路是“把每个导出字段定义抽成配置用统一渲染函数处理”方向正确且说清了不会动函数签名。我确认后让它开始执行。第四步它每完成一小步就自己跑一次测试。中间遇到过两次失败一次是枚举字段顺序变了一次是日期格式在旧逻辑里是特殊处理、新逻辑里漏了。它根据测试报错自己定位、修复最后所有测试通过。整个过程大概是我以前手动带它折腾的三分之一时间而且最终改动非常克制没有夹带任何无关内容。这正是我所期望的“代码智能的持续进化”。5.3 效果从“改了近千行”到“一张 diff 解决”我把这次实战和以前对比了一下。以前让它重构它经常一口气生成几百上千行的新代码看着大气磅礴但 review 成本极高没人敢合。现在有了背景文件、任务契约和自动验证三层保险它产出的改动是精准、最小化、可审计的。改了什么、为什么改在每一步都能追溯。说白了所谓持续进化并不是模型一夜之间变聪明了而是我们通过制度设计让每一次协作都在向正确的方向收敛。重复几次之后你会发现它的产出质量稳定提升因为你的 CLAUDE.md 越来越贴合项目任务模板越来越顺手自动反馈闭环越来越快。6. 常见问题速查与排查技巧6.1 高频问题速查表症状、原因、解法我在下面整理了这段时间高频遇到的问题做成一张速查表方便你直接对照症状常见原因优先解法改动范围失控乱改无关文件缺少边界约束任务说明书里写清“只改哪些路径禁止动哪些路径”昨天说过的规则今天又违反规则只存在于对话里未被持久化把规则写进 CLAUDE.md并新开会话大任务做一半开始东拉西扯任务太大、上下文太长拆分成小任务每个任务一个验收标准代码看着合理测试一跑就挂没有自动化反馈闭环强制它自己跑测试挂了自己修写了规则但不生效CLAUDE.md 位置不对或优先级混乱检查文件加载位置削减互相冲突的规则它每次都要你手把手纠错任务目标不够量化把“优化”“完善”改成可验证的行为描述6.2 经验补充那些文档里不会写的事有几个点是我踩过坑之后才真正理解的。一是“规则和任务要分离”CLAUDE.md 放长期规则任务说明书放临时要求。别把临时任务塞进长期规则里不然文件会越来越臃肿、失去约束力。二是“每次只验证一件事”一次验收标准里不要堆十个条件条件越多它越容易顾此失彼。把大的改动拆成多个可验证的小步骤每步一个到两个验收条件推起来特别顺。三是“把模型当成需要复习的队友”模型不会因为昨天跑通了今天就一直对。每周看看 CLAUDE.md把团队规约的新变化补进去把不再适用的规则删掉这个文件要当作活文档维护。6.3 这套方法的边界与适用情况最后说点实在的。这套方法并不是万能药。如果你的需求本身极其模糊连你都说不清要什么那模型再会拆任务也没用如果你的项目完全没有测试和静态检查第三招会很难落地建议先把最小的测试框架搭起来再谈驯服代码智能。它最适合的场景是“需求清楚、改动面可控、有自动化验证”这一类工程任务。在这些场景下三招组合拳可以让 Claude Code 稳定输出并且每一次协作都在沉淀知识、完善流程形成真正意义上的持续进化。6.4 最后一点个人体会用这套方法几个月我最大的改变不是更信任它了而是更懂怎么分配工作了。凡是背景知识清楚、验收标准量化、反馈闭环存在的任务我敢放手让它连续干凡是信息模糊、设计决策未定的活我会先自己把方案想明白再变成契约交给它。说白了Claude Code 值不值得用不取决于它本身有多聪明而取决于我们有没有给它一个可以持续进化的协作环境。这三招就是让我从“被人工智障气死”到“让代码智能持续进化”的关键转变。如果你也在用类似工具建议从今天开始先建一个 CLAUDE.md再拆一个任务试试你会发现它比你想象中靠谱得多。