Claude Code 工程化实战（一）：Claude Code 工程化全景：从 AI Coder 到 Agent Harness

Agent Harness 工程控制室

这张图把 Agent Harness 画成一间工程控制室：模型在中央理解目标，Tools、Memory、Permissions、Hooks、MCP 与 SDK 分布在不同屏幕上，分别承担行动、长期事实、边界、验收和外部连接。重点是：Claude Code 的价值不只是“能写代码”，而是把模型放进一个可观察、可约束、可复用、可交付的工程运行环境里。

一、从“会写代码”到“能交付变更”

早期使用 AI 编程工具时，很多人会把它当成一个更快的补全器：给一段需求，它生成一个函数；给一个报错，它解释原因；给一份代码，它帮忙重构。这个阶段的体验很直接，但很快会遇到三个问题。

第一，模型不知道你的项目真实边界。它可能写出语法正确的代码，却不符合现有目录结构、权限模型、异常处理规范和测试习惯。第二，模型缺少稳定的行动路径。它可以“猜”应该读哪些文件，但不一定知道先看路由、再看服务、再看测试、最后跑验证。第三，模型的输出缺少工程证据。一个回答看起来合理，不代表它真的通过了测试、没有破坏接口、没有漏掉迁移脚本。

Agent Harness 要解决的正是这三类问题。Harness 不是模型本身，而是模型周围的一层工程外骨骼：它把项目事实、工具能力、执行约束、自动检查、外部系统连接和协作单元组织起来，让模型不再只是“说出答案”，而是能围绕一个目标完成搜索、分析、修改、验证和汇报。

换成工程里的说法，AI Coder 像一个能力很强的执行器，Agent Harness 则像一套带规则、工具、记忆、检查和复盘的运行系统。单点能力可以解决一两个简单任务，但复杂项目靠的是稳定体系。

二、Harness 的核心：把智能放进工程闭环

一个成熟的 Agent Harness 通常包含五个关键能力。

上下文入口负责告诉模型项目长期事实。比如服务启动方式、数据库迁移约束、测试命令、代码风格、发布禁区、常见故障排查路径。没有这层入口，模型每次进入项目都像第一次上场，必须从零猜规则。

工具层负责把“想法”变成“行动”。读文件、搜索代码、修改文件、运行测试、查看 Git diff、请求浏览器验证、连接 GitHub 或内部系统，这些都不是语言模型天然拥有的能力，而是 Harness 给它的手脚。

权限层负责限制危险动作。读文件和删除生产数据的风险完全不同，搜索代码和执行 rm -rf 也不是一个级别。权限层的作用不是让 Agent 变笨，而是让它在正确的边界内行动。

检查层负责把主观判断变成客观证据。Hooks、格式化、测试、lint、类型检查、截图验证、构建检查都属于这个层面。它们像裁判和技术统计，不靠感觉判断“这球进没进”，而是用结果说话。

扩展层负责把 Agent 接入更大的工程生态。MCP 可以把数据库、文档、Issue、CI、监控等外部系统接进来；SDK 可以把 Agent 嵌入团队自己的平台；Plugins 可以把一组 Commands、Skills、Agents、Hooks 打包给多人复用。

这五层合在一起，才构成一个完整的闭环：理解目标，收集证据，执行变更，检查结果，沉淀经验。

三、为什么“上下文 + 工具 + 验证”比单纯提示词更重要

很多失败的 AI 编程实践都败在一个误区：以为只要提示词写得足够长，模型就能稳定完成复杂任务。提示词当然重要，但提示词不是工程系统。

假设你让 Agent 修复一个登录 Bug。如果只给一句“登录失败，请修复”，模型可能会先猜测是密码校验问题，再猜测是 token 过期问题，也可能直接改前端表单。它能写出许多看似合理的解释，却不一定触碰到真正的问题。

如果 Harness 设计得好，流程会完全不同：

先读取项目记忆，知道这个项目使用 OAuth 回调、会话写入 Redis、前端通过 /api/session 获取登录态。
再搜索近期修改和失败测试，定位到回调路由与会话服务。
然后读取相关文件，而不是把全项目塞进上下文。
接着提出最小修改，并说明为什么只改这一处。
修改后运行单元测试、集成测试和登录路径验证。
如果测试失败，回到证据层继续分析，而不是扩大改动范围。
最后输出变更摘要、验证结果和残留风险。

这个过程看起来像“模型在写代码”，实际上是 Harness 在组织一个工程闭环。模型负责推理和选择下一步，Harness 负责提供正确的工具、边界和证据。

四、Agentic Loop：一次有效行动不是一次回答

Agent 的工作方式更接近循环，而不是一次性问答。一个典型循环包括四步：观察、计划、行动、评价。

观察不是随便读文件，而是围绕目标找证据。比如看到报错 Cannot read properties of undefined，不应该立刻搜索全仓库所有 undefined，而应该先确定它发生在哪个请求、哪个组件、哪个测试场景。

计划不是写一个宏大的 Todo，而是把未知变成可验证的小问题。比如“确认登录态从服务端写入了吗”“确认前端拿到的 session shape 是否变了”“确认失败是否只在移动端发生”。每个问题都应该能通过读文件、跑命令或看日志回答。

行动是调用工具完成具体工作。这里要强调“最小可逆”：先读，后改；先小范围验证，后扩大范围；先修复根因，后清理旁枝。好的 Agent 不应该一上来就全局重构。

评价是把行动结果重新放回目标里检查。测试通过不等于问题解决，截图没报错不等于用户路径正确，类型检查通过不等于边界条件完整。评价阶段要问的是：当前证据是否足以证明目标已经达成？

这个循环的质量，决定了 Agent 是一个可靠搭档，还是一个会高速制造不确定性的生成器。

五、一个完整案例：修复登录后跳回首页的问题

设想一个真实需求：用户从 /checkout 被重定向到登录页，登录成功后应该回到结算页，但现在总是回到首页。

如果让普通补全工具处理，它很可能会改登录表单，把 redirect 参数硬塞进 URL。这个方案也许能在当前页面奏效，却可能破坏 OAuth、短信登录和第三方登录。

Agent Harness 的处理方式应该更稳。

第一步，读取项目记忆。记忆里如果写着“登录来源页由 returnTo query 统一处理，白名单由 auth/redirect.ts 控制”，模型就不会随便发明一个 redirectUrl 参数。

第二步，搜索入口。它会查找 returnTo、redirect、checkout、callback，确认登录流程经过哪些模块。此时 Tools 像工程导航，帮助模型快速找到相关入口，而不是在仓库里盲目搜索。

第三步，建立假设。比如：

登录页接收到了 returnTo，但提交时丢失。
OAuth 回调拿到了 state，但解析后没有写入 session。
白名单误判 /checkout 为不安全路径。
前端登录成功后统一跳首页，覆盖了服务端返回值。

第四步，逐个验证。读代码、跑相关测试、必要时补一个回归测试。Harness 的优势在这里很明显：模型不只是“觉得”哪个原因最像，而是用工具把假设排除掉。

第五步，做最小修复。假设根因是登录表单提交时没有保留 returnTo，那么修改应集中在表单 submit 逻辑和相关测试上，而不是重写整个 auth 模块。

第六步，跑验证。至少包括相关单元测试、登录流程测试、lint 或类型检查。如果项目有浏览器验证能力，还应该跑一遍从结算页到登录再返回的路径。

第七步，交付说明。一个好的交付不是“修好了”，而是包含：改了哪里、为什么这样改、验证了什么、还有什么风险。比如“第三方 OAuth 的 state 流程未改动，只验证了用户名密码登录；若要覆盖 OAuth，需要补端到端测试”。

这就是 Agent Harness 与单纯代码生成的差别：它把问题变成一个有证据链的工程过程。

六、Memory：长期事实不是聊天记录

Memory 经常被误用成“把所有东西都记下来”。这会让上下文越来越吵，模型越看越迷糊。真正有效的 Memory 应该像项目索引，只保留长期有效、能改变决策的信息。

适合写入 Memory 的内容包括：

项目启动、测试、构建和发布命令。
关键目录与模块边界。
业务规则中容易被误改的部分。
团队固定约束，比如“不要改生成文件”“数据库迁移必须向后兼容”。
已经验证过的排查路径，比如“登录问题先看 session service，再看 callback route”。

不适合写入 Memory 的内容包括一次性报错、临时日志、过期分支状态、没有结论的猜测，以及任何模型下次不该依赖的信息。项目索引越简洁，越能帮助 Agent 快速决策。

七、Hooks：把质量要求变成默认动作

Hooks 是 Harness 里很容易被低估的一层。很多团队把质量要求写在文档里，但文档不会自动拦住错误。Hooks 的价值是把关键规则放进执行路径。

例如，在 Agent 修改 TypeScript 文件后自动运行 npm run lint -- --fix，在修改数据库迁移时提醒必须补回滚说明，在提交前强制跑受影响测试，在最终汇报前检查 Git diff 中是否包含 .env 或密钥。这些动作本身不复杂，但一旦自动化，就能显著降低“模型忘了做”的概率。

Hooks 不应该变成一堵无法理解的墙。好的 Hooks 要给出明确反馈：为什么拦截、怎么修复、是否允许人工确认后继续。这样 Agent 才能把它当成裁判，而不是当成随机失败。

八、MCP 与 SDK：从本地助手走向工程网络

当 Agent 只在本地仓库里读写文件时，它能解决代码层问题；当它能安全连接外部系统时，它才开始参与完整研发流程。

MCP 更适合把外部资源作为工具接入，比如读 GitHub Issue、查设计文档、看数据库 schema、取监控指标。关键是权限要最小化：能读就不要给写，能限定仓库就不要给全组织权限，能审计就必须记录。

SDK 更适合把 Agent 能力嵌入团队自己的系统。比如在内部研发平台里提供“分析这个 PR 的风险”“根据失败日志生成修复建议”“为这个服务生成接入手册”。SDK 需要考虑输入输出 schema、错误处理、流式返回、成本预算、并发控制和用户身份。

二者共同指向一个方向：Agent 不再只是个人命令行里的助手，而是可以成为工程平台的一部分。

九、判断一个 Harness 是否成熟

可以用六个问题快速评估一套 Agent Harness 的工程成熟度。

第一，它是否知道项目边界？如果每次都要用户重复解释目录结构和测试命令，说明上下文入口不足。

第二，它是否能做证据驱动的行动？如果总是在猜，而不是读文件、跑测试、看日志，说明工具层或工作流不足。

第三，它是否有权限分级？如果读文件、删文件、连数据库都没有差异化处理，说明风险边界不足。

第四，它是否能自动验证？如果最终只给自然语言结论，没有测试、构建或截图证据，说明交付闭环不足。

第五，它是否能复用经验？如果同类任务每次都从零开始，说明 Memory、Skills 或 Plugins 没有设计好。

第六，它是否能融入团队流程？如果只能靠个人手动触发，无法进入 PR、CI、文档和发布系统，说明平台化还没开始。

十、落地建议：先把一个路径打穿

不要一开始就试图把所有研发流程都交给 Agent。更稳的做法是选择一个高频、低风险、可验证的路径，先把闭环打穿。

比如选择“修复前端 lint 与类型错误”。你需要准备项目记忆，写清楚命令和目录；给 Agent 文件读写和测试权限，但限制危险 Bash；配置修改后自动格式化；要求最终输出 diff 摘要和验证结果。等这个路径稳定后，再扩展到单元测试修复、文档同步、PR 风险分析。

Agent Harness 的建设不是为了炫耀模型能做多少事，而是为了让它在复杂项目里持续做对事。模型能力越强越好；但没有规则、工具、检查和复盘，再强的模型也只能靠临场发挥。工程化的目标，是把这种发挥变成可重复的交付方式。