长文：Claude Code 实践 Harness 工程，开发效率翻几倍

大家好，我是双越。wangEditor 作者，前百度 滴滴 资深前端工程师，慕课网金牌讲师，PMP，前端面试派 作者。

我正致力于两个项目的开发和升级，感兴趣的可以私信我，加入项目小组。

• 【划水AI】 Node 全栈 AIGC 知识库，包括 AI 写作、多人协同编辑。复杂业务，真实上线。
• 【智语】 AI Agent 智能体项目。一个智能面试官，可以优化简历、模拟面试、解答题目等。

开始

最近看社区都在讨论 Harness 工程，但我感觉绝大部分文章写的都很抽象，看着每个字都认识，看完了不知道讲了啥。我之前也一直受困于此，得不到突破。

直到我有一次和一个同学聊天，他分享自己使用 harness 工程和 vibe coding 的区别：

当 AI 出错时，不是去纠正它，而是改进自己的提示、规则和约束。这是 harness engineering 的核心思想。

再后来我看到知乎的一篇文章，直接了当的写出了 Harness 在 Claude Code 中的几个体现：

• MCP 和 tool ，提供能力
• Hook ，提供约束
• Skill ，提供引导和流程
• Subagent ，提供独立的执行环境

我才对 harness 工程在 AI 编程领域的应用有了一个具体的认识，后来我就尝试在 Claude Code 去试用，发现效率真的可以提升几倍。

本文是我总结整理的详细实践过程，供同学参考。项目源代码链接 github.com/wangfupeng1...

创建一个项目

从 0 开始，初始化一个 nextjs 新项目。其他技术栈或框架也都没问题，对于 AI 都一样。

npx create-next-app@latest

用 claude code 打开项目，或用 vscode 打开并使用 CC 插件。没安装 CC 的可以参考我之前的文章。

初始化单元测试环境，安装 npm 插件，配置文件，命令。我交给 CC 操作，它选择了 jest

根据当前项目，初始化一个单元测试环境。
测试代码放在同目录下，以 xxx.test.ts 格式命名
并为首页 page.tsx 写一个单元测试，执行看是否报错

生成 CLAUDE.md

在 CC 执行 /init 命令先初始化一个 claude.md

再参考 andrej-karpathy-skills 的四原则，这是最近非常火爆的 AI 编程提示次，把它补充进来。

现在 claude.md 已经超过 100 行了，再有内容就需要扩展到其他文件中，如 rules/xxx

Skill

安装基础必备 skill

我先安装了一些基础的 skill ，可以被直接使用的 ，后续的边开发边补充。

react best practice vercel 官方出品

npx skills add vercel-labs/agent-skills ## 选择 react-best-practices 

frontend-design Anthropics 官方出品

npx skills add https://github.com/anthropics/skills/tree/main/skills/frontend-design 

skill-creator Anthropics 官方出品

npx skills add https://github.com/anthropics/skills/tree/main/skills/skill-creator 

UI 组件库 shadcn skill ui.shadcn.com/docs/skills

npx skills add shadcn/ui

PS. 还会安装 test review 相关的 skill ，下文会有介绍，你在此一并安装也没问题。

skill 尽量精简

我的观点：skill 如果没有具体的、直接的用途，就不要安装。尽量精简。

• 例如 docx pdf ppt 等 skill ，写代码用不到，先不安装
• 关于架构、逻辑、memory 相关的 skill ，过于高级抽象，看不到直接用途，先不安装
• LLM 和 agent 都在告诉发展中，现在常用的 skill 都被集成到 LLM 和 agent 中

MCP Server

安装基础必备 MCP server

先安装一些基础的，后续边开发边补充。GitHub Supabase Figma 等

Context7 用于更新文档版本的，社区推荐安装的，但我整个试用过程中还没发现明显的用途。你也可以先不安装，随后再安装也行。

另，它官网的安装命令，我一直卡在登录校验上，用老版本的安装命令可以成功

claude mcp add -s project context7 npx @upstash/context7-mcp

Playwright MCP server 后面要用的，必须安装。

claude mcp add -s project playwright npx @playwright/mcp@latest

和 Skill 一样，MCP server 也是先安装一些基础必备的，其他不确定的就先不安装。

例如 figma github supabase 我现在还用不到，就先不安，未来用到了再说。

关于 tool search

如果 MCP server 安装过多，会增加大量的 tool ，每次 AI 请求都携带，将极大的消耗 token ，所以 Claude Code 现在默认自带 tool search 机制，来动态搜索相关的 tool 而不是全部携带。

但是，目前的文档中，tool search 的使用也是有限制的，和我最相关的就是 model ，文档中只有 Sonnet 4 及其以后的模型才能支持。

我压根没有用 Claude 模型，我用的是国内的 MiniMax ，所以大概它不会支持。

所以更应该谨慎使用 MCP server ，不直接使用的不要随意安装。

Hook

基础必备 Hook

我在这个开源项目中 github.com/karanb192/c...

找到了几个常用的 hook：

• 阻止危险命令 block-dangerous-commands
• 保护隐私数据 protect-secrets

直接把它的源码拷贝下来，并配置自己的 .claude/settings.json 即可

创建自定义 Hook

我还想创建一个 Hook 来显示和警告 Context 使用情况，避免 Context window 过大，而导致 LLM 出现幻觉。

如何创建一个 hook 呢？第一步可以先搜索一下有没有相关的 skill ，在 CC 中输入

/find-skills create a claude-code custome hook

它找到了一个相关的 skill 而且还是 Anthropics 官方的，应该值得信赖，安装它

然后调用这个 skill 帮我创建 hook ，或者你直接输入 prompt 它会自己调用这个 skill

/hook-development 帮我创建一个 claude-code hook ，叫做 context-warning ，使用 PostToolUse 这个hook
用于显示和警告当前 AI 请求的 context 使用和剩余的百分比，并超过 80% 时给出明显警告
以便我知道合适压缩 context

现在已经有了基础的环境和工具，接下来该考虑流程了。

定义 dev-workflow

我是在 claude.ai 聊天，和它描述我的需求：

• 我想定义一个工作流，根据需求拆解任务、编码、CR 和测试
• 这几个任务分别用不同的 subagent 实现
• 这些步骤可以自动执行，除非核心的步骤人工干预

它给我设计了一个 skill ，标注了详细的流程图，下面也描述了每个步骤的规则。

其实这也不是它一开始就直接给我的答案，我和它讨论了很久、修改好几次才出来的。

这个设计中单元测试很重要，只有把测试头都到尾做好，才能验证闭环

• plan 时，就要输出验收标准、测试范围
• code 时，同时要写单元测试代码
• test 只管测试，不改代码内容。测试不通过交给 coder agent 去修改代码。

Subagent

有了上述的 skill 流程，我就让 claude.ai 继续帮我生成了 4 个 subagent 的提示提示词，下文有。

新建 subagent

运行 /agents 可查看当前 sub agent ，也可以创建新的 sub agent

创建的时候需要写入提示词（agent 功能介绍），还需要选择 tools ：all 或 read-only 等，剩下的 CC 自动帮你生成。

创建完成以后，你就可以在 .claude/agents 目录下看到创建的所有 subagent

planner

A development planning specialist. When given a feature request or bug 
fix, produces a structured plan including: Task Summary, Scope 
(in/out/assumptions), Implementation Tasks checklist with affected files, 
Unit Test Requirements per core module, Acceptance Criteria in 
Given/When/Then format, and Risks & Notes. Does not write any code.

注意：planner 中要包含：验收标准，和测试范围，以指导后续写单元测试和 E2E 测试。

tool 选择 read-only tools ，只读模式，只做规划，不编辑任何内容。

coder

A software implementation specialist. Implements features or fixes based 
on a provided plan. Writes unit tests for every module or function 
specified in the plan's Unit Test Requirements. When given a reviewer or 
tester failure report, fixes only the reported Critical Issues without 
touching unaffected code. Produces an Implementation Summary listing 
files created, files modified, unit tests written, and any deviations 
from the plan.

注意：写代码时一起写出单元测试，这样测试写的更精确更详细。

tools 选择 all tools ，编码阶段，给予最高编辑和执行权限。

忘了一些规则，继续告诉 CC 让它来修改：

@.claude/agents/coder.md  对于 coder agent 我想补充几个 git 相关的规则：
1. 不要在 main/master 分支开发，要在独立分支开发（以 feat/fix/test/refactor/chore/docs 开头的分支名称）且开发之前要保证 git status 干净无更改； 
2. 每次阶段性的改动都要及时 git commit 不要混在一起提交代码；

reviewer

A code review specialist. Reviews code changes for correctness against a 
provided plan, code quality, security, and error handling. Checks whether 
unit tests adequately cover the specified Unit Test Requirements --- missing 
tests are treated as Critical Issues. Produces a structured report with 
result (PASS or FAIL), Critical Issues, Warnings, Suggestions, and a Unit 
Test Assessment. Does not modify any code.

tools: read-only ，只读，代码走查

安装一个 review 相关的 skill github.com/obra/superp...

npx skills add obra/superpowers@requesting-code-review

tester

A software testing specialist. Validates implementations in three layers: 
first runs all existing unit tests, then verifies each Acceptance 
Criterion from the plan, then identifies and executes additional edge case 
and error handling tests not already covered. Produces a structured report 
with result (PASS or FAIL), unit test results, per-criterion AC 
validation, additional edge cases found, and an Overall Assessment. Does 
not modify any code.

tools: all tools 因为它需要执行测试命令，还可能会调用 playwright MCP server tools

安装了一个 test 相关的的 skill github.com/obra/superp...

npx skills add https://github.com/obra/superpowers/tree/main/skills/test-driven-development 

任务 1

调用 dev-workflow skill ，开发一个新功能。这也是我第一次试用这个工作流，看效果如何。

/dev-workflow 在首页开发一个 todo-list 功能

plan

claude code 根据 dev-workflow skill 流程，自动调用 planner agent 开始工作。

输出了计划 （包括验收标准和测试需求），你可以确认，也可以继续添加修改。

我在这里添加了修改意见，让它继续修改一下。

它修改以后，我觉得没问题，手动回复 confirmed 确认，执行下一步。

coding

它开始调用 coder agent 开始编码

写代码，构建，确保能构建成功。

写单元测试，执行单元测试 ，以确保写的没问题。

review

它自动调用 reviewer agent 进行代码走查，最后结果没问题。

test

上一步通过以后，它自动调用 tester 执行单元测试。

单元测试通过，又要调用 playwright 执行 E2E 测试，之前配置了 MCP server

它自动启动服务，自动测试网页功能

completion

测试通过，它自动总结任务。一共 10 多分钟，全程自动化执行，除了我确认 task plan 。

任务1 发现的问题

未执行 git 规则

即便我在 coder agent 文档中要求了，但是

• coder 依然在 main 分支写代码
• coder 没有及时提交 commit

在此又得拿出这句话：

当 AI 出错时，不是去纠正它，而是改进自己的提示、规则和约束。这是 harness engineering 的核心思想。

对此我做做出两个修改

第一，修改 dev-workflow skill ， PHASE2 增加引导

第二，自定义一个 Hook 去约束它，如果当前是 main 或 master 分支，就报错

无法及时看到开发效果

现在是 coder agent 写完代码和单元测试，直接就交给 reviewer agent 去代码走查了。

应该在这里停止一下，让用户看看开发出来的效果和功能，手动确认，再继续执行。

修改 dev-workflow skill

@dev-workflow/SKILL.md 修改这个 skill ，在 PHASE 2 的最后，增加一个 CHECKPOINT ，让用户去运行项目来确认 UI 效果和功能。确认无误以后再继续，如有问题还要重新改动。参考当前 CHECKPOINT #1 的位置和格式即可。

没有更新 README.md

每一个任务结束，都要及时更新 readme.md 以及其他相关文档。

修改 dev-workflow skill 增加这方面的描述。必要的时候（文档较多时）这里可以再扩展一个 subagent

任务 2

任务1 中遇到的问题，已经被改过来了，但效果如何呢？还需要再来一个任务进行验证。

使用 dev-workflow skill 开发一个新功能，重新走一遍流程试试。

/dev-workflow 开发一个新需求：
新增 todo 的时候，可以设置完成时间，用于判断该 todo 是否过期。
todo-list 下面增加几个筛选标签
- 全部：全部 todo
- 今天：完成时间是今天的 todo
- 过期：完成时间早于今天的 todo 
每个标签都计算 todo 数量（计算时只考虑未完成的数量，已完成的不计数了）

plan

启动 planer agent 制作 task plan

checkpoint1 停下，让用户确认 task plan

code

先新建 git 分支了 ------ 之前的改动有效果了。

然后 coder agent 开始工作

写代码，写测试，自行验证......

Checkpoint2 停下了，提示用户执行 npm run dev 去验证效果 ------ 之前的改动有效果了

我运行 npm run dev 来查看效果

我发现了一个问题，告诉 CC 来修改

change: 一个 todo 我设置了"完成"，它就再也看不到了，这会让用户很困惑。在所有 filter 列表中，已完成的 todo 也要显示出来，别隐藏着。

它重新启动 coder agent 开始修改

修改完成以后，Checkpoint2 再停止，用户检查，这次没问题了。我手动回复 confirmed

而且，我发现，它每次修改也都会自己提交 git commit ，而且当前 git status 是干净的。

说明之前对 skill 的修改有效果了。

review

人工确认之后，它继续到 reviewer agent

review 结束，通过。

但这里的 checkpoint 3 不应该停止，应该自动通过的，除非遇到问题。这里需要改进，问题不大。

手动确认一下，继续。

test

继续执行 tester agent

测试通过，但这次好像没有触发 Playwright ------ 又一个新问题，一会儿再去查。

completion

任务总结。

发现它自动更新了 README 文档 ------ 之前的改动也有效果。

任务2 发现的问题

checkpoint 3 不应该停止

checkpoint 3 不应该停止，除非遇到问题。修改 dev-workflow skill

@dev-workflow/SKILL.md 修改这个 skill ，
对于 CHECKPOINT #3 如果 review 审核通过了，可以直接跳转到下一步不用人工审核。

其实就是改了一句话，也不知道管不管用，好在问题不大。

tester 没有调用 playwright

我检查了 tester agent 的提示词，确实没有明确说明 playwright 的应用场景。

于是我让 CC 为 tester agent 增加 playwright 的描述

@tester.md 修改这个 subagent 提示词：单元测试成功以后，尝试执行 playwright 自动化测试。要求：
1. 判断用户是否安装 playwright CLI 或 MCP server ，如果没安装，提示用户，然后继续走流程。
2. 根据工作流中 planner agent 给出的测试范围和指导，来执行 playwright 。如果找不到 planner agent 给出的测试范围和指导 ，提示用户，然后继续走流程。
3. 如果用户安装了 playwright CLI 或 MCP server ，并且你得到了工作流中 planner agent 给出的测试范围和指导，则使用 playwright 执行自动化网页尝试。

现在 tester 有了明确的 playwright 应用场景和步骤，下一次就可以调用并执行。

关于 Plan mode

Claude code 自带的 Plan mode （其他 AI IDE 也有）和上文的 planer agent 是有功能重叠的。

Plan mode 有强制的只读权限，而 planner 也设置了 read-only tools ，功能是相同的。

如果用 Plan mode 需要手动在 CC 切换模式，而用 planer agent 更方便在 skill 中定义流程。

所以我这里用的是 planer agent 。

未来扩展

这只是一个最基础的开发模式，做的也是简单的功能，但已经彻底打破了传统开发模式了。

基于这种方式，我觉得很容易扩展到更规范、更复杂的研发流程中来。

例如，定义更长的流程，从 github issue （或 jira figma）开始，直接到 github PR

再例如，一个人并行开发多个任务（配合 git worktree），一天可以完成一周的工作量

我会继续探索更多的可能，会持续分享关于 AI 、智能体、全栈开发等话题，欢迎点赞关注～