最近小半年我把日常编码的主战场从网页对话框搬到了终端里的Claude Code并且围绕它摸索出一套自己的Harness Engineering方法。简单说就是在AI编程工具外面建立一整套缰绳系统让这个能力很强的模型按我的项目规范去干活。社区里有人管它叫Claw Code我觉得这个昵称挺传神——它确实像一只爪子先把代码库里的关键信息抓取进上下文然后精准落在该动手的那个文件上。这篇博客不打算复读官方文档我想分享的是三件事Claude Code这类终端编程工具真正改变了什么为什么工具越强驾驭工程Harness Engineering反倒越关键以及我在真实项目里沉淀下来的配置方案、工作流习惯和踩坑经验。适合已经在用或准备用这类工具的开发者也适合刚听说AI写代码、想弄明白这玩意儿到底是怎么工作的初级程序员。1. 从对话框编程到终端编程变化的不是入口而是权限1.1 网页版助手的隐形天花板很多人第一次接触AI写代码都是从网页对话框开始的。用一段时间你就会发现一个共同问题对话是典型的一问一答AI只能基于你贴进去的那一小段代码做判断。它不知道你的项目里还有哪些文件不知道你最近改过什么更没能力验证自己给出的方案能不能编译。这带来三个很实际的麻烦。第一上下文割裂。每次新开对话都是重新开始你得反复描述项目背景、技术栈、目录结构。第二信息损耗。把代码从编辑器复制到网页对话框缩进、注释、类型信息都可能变形走样模型容易被误导。第三也是最重要的一点网页对话框里的模型没有行动能力。它发现一个函数签名对不上不能自己去工程里定位和修改只能告诉你你应该改这里然后剩下的事情还是得你自己来。1.2 终端里多了一个会动手的协作者Claude Code这类工具把AI放进了终端本质变化是模型不再只是聊天对象而变成了一个带工具集的Agent。它有了一整套手脚能读文件、搜索代码、精确编辑文件、执行shell命令、运行测试并读取结果。这构成了一个完整闭环你给它一个目标它自己去读相关源码自己定位问题自己修改文件改完自己跑测试不行就再改一轮。我实际经历过的一个例子是重构一个老项目里的核心模块。那个模块被几十个服务引用调用链非常深。过去让我自己来从梳理调用关系、列改动清单到改完跑全量测试保守估计得大半天。这次我只在终端里给了一个目标描述它花几分钟把整个模块的引用关系摸了一遍然后在一个会话里连续改了十几个文件每改完一批就自动运行对应测试有失败当场修正。我最后做的主要工作是人工review那十几处变更。1.3 Claw Code这个昵称为什么贴切社区里有人把Claude Code称为Claw Code。刚开始我以为就是打字省事后来想明白了这个昵称其实描述得非常准确。Claw是爪子它的工作方式确实是抓取——但它不是把整个代码库一股脑塞进上下文的那样token消耗谁也扛不住。它用自己的方式扫描代码库结构先用全局搜索定位到可疑符号再看引用列表然后按需把最相关的文件内容抓进上下文。这个过程很像资深程序员查代码的习惯先grep搜一遍符号定义再翻引用列表最后用编辑器跳到具体行号。它把这个习惯显式化了。所以它能处理比单次输入容量大得多的工程就是因为上下文是按需加载的不是全量灌入的。2. 核心运行机制拆解感知、决策、行动的死循环2.1 一次工具调用背后发生了什么如果你启动工具后说帮我修一下登录接口的500错误它并不会调用某个修bug的函数。真实情况是它内部在跑一个循环先理解你的指令结合当前会话的历史记录形成对任务的判断决定第一步行动比如用搜索工具定位登录接口所在的文件调用工具观察返回结果根据结果决定下一步如果找到了疑似问题就打开文件查看细节确认根因后用编辑工具修改代码调用shell命令运行相关测试观察测试输出如果测试失败回到第4步继续。这和人类程序员的调试路径高度一致定位、阅读、修改、验证。区别在于它的迭代速度比人快得多。你坐在终端前面看到的是一串工具调用输出它会告诉你正在搜什么、命中了哪个文件、改掉了哪段代码、测试结果如何。如果觉得跑偏了随时可以打断让它停下来重新解释。2.2 工具集的设计逻辑我把它内置的工具大致分成三类。第一类是侦查工具负责找信息包括全局搜索、按文件名匹配、按目录列举文件、读取文件指定内容。第二类是编辑工具负责改东西可以对文件做精确定位替换、在指定位置插入代码块。第三类是执行工具负责跑命令比如构建、测试、查看git状态。这套工具集设计逻辑是最小必要权限每个工具只做一件事但组合起来覆盖了绝大部分开发场景。值得一提的是编辑动作不是重写整个文件而是定位一段文本替换成新内容。这意味着改一个小函数时它不会把整个文件格式化得面目全非diff的可读性比整文件重写好很多code review的时候也能很快确认改动范围。2.3 上下文为什么比网页对话框耐用网页对话框的上下文往往聊个几百行就乱套了Claude Code却可以支撑几个小时的连续工作。关键决策在于它不把内容无限堆在可见上下文里而是依赖检索工具按需获取。你让它检查一个明显没见过的文件时它会先调用读取工具进来再把关键行纳入上下文。整个会话看起来是连续的但它内部始终保持任务相关的最精炼信息。这是它能处理大型工程的核心原因。当然这里说的耐用是有限度的如果硬把一个超大任务拖在同一个会话里后期照样会失忆这点放到第5章细讲。3. Harness Engineering真正拉开差距的是对模型的驾驭3.1 先搞清楚Harness是什么意思很多人把AI编程的产出全归功于模型本身。但用久了你会发现一个反直觉的结论模型能力是地基但决定你生产效率高低的是套在模型外面的那套缰绳系统——Harness。你可以把模型想象成一匹力量很强但方向感不太稳定的马。缰绳决定它往哪跑、跑多远该停、哪些路不能走。所谓Harness Engineering就是系统化地做好三件事方向控制让模型知道当前项目是什么、目标是什么边界控制让模型知道哪些能做、哪些绝对不能做信息控制让模型看到正确的上下文而不是被无关信息带偏。一个项目里用同一个模型有人觉得惊艳有人觉得是人工智障差异往往就在这套缰绳上面。3.2 方向控制把项目背景写进它的启动记忆方向控制最直接的手段是在项目根目录放一个规则文件工具每次在这个项目里启动时都会自动读取。我的习惯是至少包含四段内容项目一句话简介、技术栈和关键依赖、目录结构约定、常用命令。一个典型的写法是# 项目简介 这是一个面向移动端的内容发布系统核心模块包括账号体系、内容审核、推送服务。 # 技术栈 - 后端Java Spring Boot构建工具Maven - 数据库MySQLORM用MyBatis - 前端Vue 3 Vite # 目录约定 - src/main/java业务代码按模块分包 - src/main/resources配置和静态资源 - 测试代码放在 src/test/java与被测类同包 # 常用命令 - 编译mvn compile - 运行单元测试mvn test - 启动本地服务mvn spring-boot:run有了这些信息它生成的代码结构自然就符合你的工程习惯。最明显的变化是没有规则文件时它经常把工具类丢到随便一个包下面有了目录约定之后它知道工具类放哪、测试类放哪生成的工程结构和团队规范基本一致。3.3 边界控制把不能做的事写清楚方向控制负责引路边界控制负责刹车。边界规则写得越具体越好不要用抽象的别乱来。我会明确告诉它不要删除或重命名跟当前任务无关的存量文件不要修改数据库迁移脚本除非明确授权不要大范围重构公共接口除非任务描述里明确提到不要在没有运行测试的情况下声称任务已完成不要把日志打到控制台以外的地方除非项目已有日志规范。单独看每一条都像废话但它对这类规则执行得很彻底。原因是规则文件提供了显式的参考基线比口头上说一句注意安全具体得多。抽象的限制容易让它自由发挥具体边界才能显著收敛行为。3.4 信息控制决定它看到什么的是检索策略信息控制是Harness Engineering里最需要技巧的部分因为上下文容量有限不可能把整个仓库都喂进去。我的原则是让它先用检索定位再看具体内容。与其让它从头到尾读一个大文件不如让它先搜符号定位再读取指定行区间。如果某些目录跟任务无关我会直接在对话里说不用看assets目录和当前任务没关系帮它排除干扰。这一步是人与AI配合的关键对项目最了解的人仍然是你你负责指路它负责跑。4. 可以照抄的配置方案规则文件、参数与协作流程4.1 一套适合大多数工程的全局配置除了项目根目录的规则文件工具通常还支持全局配置放在用户主目录下适合放跟具体项目无关的通用规则。我把全局配置当作所有项目的底线要求来写# 通用工作规范 - 涉及多条修改时先列出改动计划等确认后再执行 - 每完成一个子任务用测试或日志给出验证证据 - 不要自己执行可能产生破坏性后果的命令标记为【危险】等待人工决定 - 编码风格优先遵循当前项目已有约定冲突时以存量代码为准 - 不要使用方法名、类名这类无意义的示例命名 - 提交信息用简洁的祈使句例如修复登录接口空指针异常。这几条里最实用的是第一条和第三条。第一条先列计划再动手能避免它一口气改出十几个文件、最后发现方向错了的惨剧。第三条危险命令等人工确认涉及删除命令、推送命令、清库命令时我会要求它停下来等我点头。4.2 项目级规则文件怎么写更贴近实际项目级配置比全局配置要细每个仓库情况不同需要单独维护。建议至少覆盖五块项目简介与架构说明、技术栈与环境、目录结构约定、常用命令、自动化测试要求。自动化测试要求单独成段非常必要。如果项目测试体系完善就写明任何修改都必须运行对应测试并在结果中展示测试输出。如果项目还没有测试就写明不用强行补测试但必须用编译结果和日志输出说明改动没有破坏现状。这是最容易忽略、但价值极高的一行配置。4.3 几个关键参数的实测心得有几项参数我反复调过影响很大具体名称以你正在用的版本为准参数维度我的推荐原因每轮最大工具调用次数保持默认到中等不要设太小设太小会频繁停下问人打断迭代节奏自动执行测试命令允许但禁止安装类命令测试是验证手段安装依赖容易污染环境会话压缩与恢复策略长任务主动开新会话保留摘要防止上下文累积导致决策漂移并行文件搜索数量保持默认并行太多会抓进无关文件降低检索质量参数默认值大多合理不要一上来就把力量拉满。我踩过的坑就是刚接触时把自动执行上限调得特别高结果它一次性改了几十个文件review成本直接爆掉。5. 避坑实录上下文爆炸、权限外溢与虚假完成5.1 上下文爆炸做到一半它突然失忆这是最高频的问题。一个会话连续用两个小时后你会明显感到它开始忘记早先的决策甚至出现重复劳动。根因是上下文窗口内的信息一直在累积早期关键决策被新信息不断挤占模型从里面取到准确信息的概率越来越低。我的对策是主动拆分任务。一个大重构拆成三到四个阶段每个阶段单独开会话把上一阶段的输出摘要作为新会话的启动信息。摘要里写清楚已完成的改动清单 仍未解决的问题而不是贴大段代码。实测下来这个习惯让会话中断错误率降得很明显。5.2 权限外溢误改无关文件和危险命令另一个高频坑是它改着改着就越界。比如你让它修A模块的bug它会顺手把B模块的公共接口改了理由通常是顺便优化或发现潜在问题。对这类行为规则文件里写清边界最有效。但如果来不及写规则文件临时在对话里喊停也来得及它会立刻停下来重新说明。更麻烦的是危险命令。我遇到过它想执行数据清理命令的情况——虽然意图是正经的但那条命令一旦直接跑可能清掉重要的业务表。从那次之后我在全局配置里锁死了一类命令的自动执行权限任何涉及删除、清空、强推、生产环境变更的操作必须先输出将要执行的完整命令等人工确认。5.3 虚假完成它说做完了代码其实还没过编译所谓虚假完成就是它告诉你已修复测试应该能通过但你跑一遍还是报错。这种现象背后是模型倾向给出让你满意的结论而不是对结果做严格的事实核查。它并不想骗你只是语言模型天然倾向于补全一个合理的故事。解决办法只有一个把必须展示验证证据变成硬性规则。我要求所有完成必须附带测试输出、编译输出或者能证明行为变化的日志片段。强制实施之后虚假完成出现的频率大幅下降因为为了提供证据它不得不真的去跑一遍命令。5.4 一个真实问题的完整排查链路我放一个具体案例你可以直接复用这套思路。现象它在一个前端项目里修改了按钮组件的样式类说自己已经完成但页面上没有任何变化。排查过程先让它展示修改过的文件diff确认改动确实存在发现改的是源码文件里的样式类名但构建产物没有重新编译让它执行构建命令再看构建日志构建报错错误指向另一个无关目录下的资源引用缺失原来它改样式文件时动了依赖引入顺序破坏了编译链强制它把改动回退到只保留样式类名修改重新构建问题消失。这个案例里每个真相都是靠追问证据挖出来的。把证据链作为工作流的硬性要求大部分诡异的bug都能快速定位。这也是Harness Engineering里验证闭环环节的威力。6. 成本、效率与团队协作让这套方法持续产生价值6.1 控制资源消耗的三个小习惯很多人担心这类工具消耗太大但实测下来大部分浪费来自低质量的上下文检索而不是模型本身跑得多。我总结出三个最有效的省钱习惯。第一在规则文件里引导它优先用搜索定位再读取目标文件的指定区间减少无意义的全文读取。第二会话开始时就告诉它哪些目录不需要管比如node_modules、构建产物、生成类文档避免它浪费时间在这些目录里翻找。第三完成一个里程碑后主动开新会话别让上一阶段的讨论继续占用新任务的上下文。6.2 人机分工哪些活适合交给它哪些必须自己来用下来的体会是它特别擅长有明确验证标准的机械工作比如模块重构、补齐单元测试、修复重复出现的编译错误。它不太适合目标模糊、依赖大量业务判断的任务比如从一句含糊的需求推导整个模块的设计。这类问题一旦缺少边界它给出看似合理但实际走偏方案的概率并不低。我的分工原则架构和边界我来定代码骨架和重复性修改交给它测试用例它能承担大部分但关键路径上的测试必须由我亲自设计。把它的能力限制在有标准答案的区域里出错概率会小很多。另外一个很实用的小场景是提交信息生成它改完代码之后让它先做一次改动总结再基于总结生成提交信息往往比我自己敲git diff说明快得多。6.3 团队使用时的规则演进团队协作时规则文件需要持续维护。每次出现不该发生的越界行为都应该回到规则文件里补一条。半个月做一次复盘把大家遇到的共性问题跟规则文件对照该补的补、该删的删。规则文件会越来越贴合团队工程习惯而不是一开始就要求面面俱到。另外要提醒一句团队新人不要一开始就加载全部规则。从默认状态起步等习惯了工具的运行方式再逐步叠加约束否则规则太多反而干扰它对简单任务的处理。最后分享一个对我帮助最大的小技巧每次开会话之前花十秒钟在对话开头写清楚当前任务的完成标准是什么。比如这个任务完成的定义是所有新增测试通过旧用例无回归。这十秒钟的投入比我在会话结束后做全量review省下的时间多得多。Claude Code或者说Claw Code这类工具的价值不在于替你写代码而在于省掉定位、遍历、验证这些环节里的大量琐碎时间。要真正用好它靠的不是模型本身而是Harness Engineering——那一套把方向、边界、信息和工作流约束到位的工程习惯。工具会迭代这套驾驭思路会一直有用。