自AI Coding或者说Vibe Coding流行起来,开发者也意识到如何利用以及约束AI以写出更好维护、扩展的生产级代码越来越重要。Anthropic提出Harness工程以长时间使用Agents生产代码。本篇文章主要介绍一下Harness工程以及相关实践。

自Transformers为基底的ChatGPT流行起来,以自然语言作为主要沟通的方式与模型进行对话,同时,包括图像、音视频的多模态、跨模态模型也越来越多,用于不同任务的模型也越来越多。在编码任务中,Claude Sonnet、Opus,GPT,GLM,DeepSeek,Kimi,Gemini等都发挥出色SWE-bench Leaderboards。

随着基底模型发展的越来越好,GPT,Gemini,Claude,MiniMax等顶级模型能力不分伯仲,因此更需要考虑如何更好的通过某种规范和约定更便捷高效地进行AI Coding,产出高质量代码。

Harness的提出

当前AI Coding都是通过Agent的形式解决任务,”Agent“会选择上下文、使用相应工具等方式连接开发者与模型并创建文件、执行指令以及输出对应代码。

但问题也依然存在：

长时间运行 Agent 的核心挑战在于，它们必须以离散的会话（session）方式工作，而每个新会话开始时都没有此前的记忆。想象一个软件项目由轮班工程师负责，每位新到岗的工程师对上一班发生了什么毫无记忆。由于上下文窗口有限，且大多数复杂项目无法在单个窗口内完成，Agent 需要一种方式来衔接不同的编码会话。

而Anthropic提出的解决方案是：提出一套双管齐下的方案，使 Claude Agent SDK 能够在多个上下文窗口之间高效工作：一个用于首次运行时搭建环境的初始化 Agent（initializer agent），以及一个在每次会话中负责推进增量进展、同时为下一次会话留下清晰产物的编码 Agent（coding agent）。

在长时间运行Agent情况下,由于每次对话会包含上下文等信息,过长的上下文会降低模型思考能力。一般的Agent都具备压缩能力，但即使这种情况下，通过短暂的一句话也很难构建一个完整的项目。

Anthropic将问题分解为两个部分。首先，需要搭建一个初始环境，为给定提示词所要求的所有功能奠定基础，引导 Agent 逐步骤、逐功能地推进工作。其次，应该提示每个 Agent 朝目标做出增量进展，同时在会话结束时将环境保持在一个干净的状态。

初始化 Agent（Initializer agent）：第一个 Agent 会话使用专门的提示词，要求模型搭建初始环境：一个 init.sh 脚本、一个用于记录各 Agent 工作日志的 claude-progress.txt 文件，以及一个展示新增文件的初始 git commit。
编码 Agent（Coding agent）：后续每个会话要求模型做出增量进展，然后留下结构化的更新记录。

上下文环境组成

Feature List

为了解决 Agent 试图一次性完成整个应用、或过早认为项目已完成的问题，初始化 Agent 编写一份详尽的功能需求文件，对用户的初始提示词进行扩展.

也就是通过一个文件记录需要实现哪些功能并标记功能完成状态。

Increment Progress

相比于一次完成所有任务,下一轮迭代的编码 Agent 被要求每次只处理一个功能。这种增量式方法对于解决 Agent 一次做太多事情的倾向至关重要。解决方式是求模型将进度提交到 git 并附带描述性的 commit 信息，同时在进度文件中写下工作总结。这使得模型可以利用 git 回滚错误的代码变更，恢复到代码库的正常状态。

Testing

一种常见的失败情况是:Claude 倾向于在没有充分测试的情况下就将功能标记为已完成。在没有明确提示的情况下，Claude 通常会修改代码，甚至用单元测试或 curl 命令对开发服务器做测试，但无法识别该功能在端到端场景下其实并不可用。

我个人遇到的问题就是,在前端项目中,视觉看到的一些问题让Agent处理,其往往只是通过代码筛查。解决方式是:明确提示使用浏览器自动化工具并像真实用户一样进行全部测试.

如何工作

1.运行 pwd 查看当前工作目录。只能编辑该目录下的文件。

2.阅读 git 日志和进度文件，了解近期的工作内容。

3.阅读功能清单文件，选择优先级最高且尚未完成的功能开始工作。

此外，让初始化 Agent 编写一个 init.sh 脚本来启动开发服务器，并在实现新功能前先跑一遍基本的端到端测试，也很有帮助。

问题	初始化 Agent 的应对	编码 Agent 的应对
Claude 过早宣布整个项目完成。	建立功能清单文件：基于输入规格，创建一个结构化的 JSON 文件，列出所有端到端的功能描述。	在每次会话开始时读取功能清单文件，选择一个功能开始工作。
Claude 在退出时留下了 bug 或未记录的进展。	初始化一个 git 仓库并创建进度记录文件。	会话开始时读取进度记录文件和 git 提交日志，并在开发服务器上运行基本测试以捕获未记录的 bug。会话结束时提交一次 git commit 并更新进度记录。
Claude 过早将功能标记为已完成。	建立功能清单文件。	自行验证所有功能。只有经过仔细测试后，才将功能标记为”通过”。
Claude 需要花时间摸索如何运行应用。	编写一个 `init.sh` 脚本来启动开发服务器。	会话开始时先读取 `init.sh`。

Harness Engineering

Harness Engineering（驾驭工程）是围绕 AI 智能体设计和构建约束机制、反馈回路、工作流控制和持续改进循环的系统工程实践。
它不优化模型本身，而是优化模型运行的环境。核心哲学八个字：人类掌舵，智能体执行（Human Steer, Agent Execute）。Harness一词来自马具——缰绳、马鞍、嚼子——这是一套引导强大但不可预测的动物的完整装备。驾驭工程不是去削弱 AI 的能力，而是为它打造一套黄金缰绳，让它跑得又快又稳。

Harness其实也是基于AI模型的应用,可以说从一开始的prompt enginnering到上下文工程(注入相关信息)再到现在的Harness Engineering.

范式	核心问题	优化对象	交互模式
提示词工程	怎么把话说清楚	Prompt 的措辞、格式、示例	一问一答
上下文工程	怎么给 AI 喂信息	文档、代码片段、历史对话	信息注入 → 生成
驾驭工程	怎么让 Agent 可靠工作	约束、反馈回路、控制系统	人类掌舵，Agent 执行

个人认为,这个词的出现一方面还是Anthropic的工程师包括CEO等人提出,有影响力,另一方面也是对AI工程化的系统性总结.而且目前看来对于开发者编码提效很有用.

目前针对Agent Coding常见的三个问题,归类为:

失败模式 1：试图一步到位（One-shotting）

Agent 倾向于在一个会话里把所有功能都做完。结果是上下文窗口耗尽，留下一堆没有文档的半成品代码，下一个会话启动时只能花大量时间猜测之前发生了什么。

失败模式 2：过早宣布胜利

在项目后期，当部分功能已经完成后，Agent 会环顾四周，看到已有进展就直接宣布任务完成——即使还有大量功能未实现。

失败模式 3：过早标记功能完成

在没有明确提示的情况下，Agent 写完代码就标记为完成，却没有做端到端测试。单元测试或 curl 命令通过了不代表功能真正可用。

此外，智能体还有一个危险特性：它非常擅长模式复制。代码库里有什么模式，它就忠实地复制并放大——包括坏模式和架构漂移。这意味着不加约束的 Agent 会以惊人的速度积累技术债务。

解决方案总结为:

上下文工程,提供一个稳定、小巧的入口点，然后教 Agent 根据当前任务按需检索和拉取更多的上下文。
架构约束。
反馈循环。
熵管理。

Harness的实践

目前许多AI IDE和CLI都自带一些良好的harness实践,比如记录改动和执行测试等等。

实践

Web项目实战路径

不要在初始阶段让 Codex、Claude Code 或 OpenCode 从零生成大型项目；应先限定范围、输入约束和验收标准，以降低后续维护成本。

写PRD(项目需求说明)->让Agent只读分析->小步实现->验证(跑单测、看diff等)

不要让 Agent 一次性实现完整 CRUD。每完成一步都应能够检查 diff 并运行验证

重点:

PRD 是否清楚。
Agent 是否先读代码。
计划是否可审。
验证是否闭环。
错误是否沉淀到规范。

Bug修复与重构路径

先收集完整证据：

错误现象。
复现步骤。
日志或 stack trace。
最近相关改动。
期望行为。

如果缺少复现步骤，先让 Agent 做只读分析和复现计划。不要让它直接改代码。

1. 先复现或解释如何复现。
2. 提出 2-3 个可能根因。
3. 用代码和日志验证假设。
4. 做最小修复。
5. 补回归测试。
6. 跑验证。
7. 写复盘。

这些做法看起来省时间，通常会增加下一轮返工风险：

不复现直接改。
猜一个原因就改。
修完不补测试。
改大范围无关代码。

还要避免把“顺手重构”和 bugfix 混在一起。bugfix 先追求最小修复，结构调整另开任务。

重构路径

重构前先把这几个问题问完：

外部行为是否保持不变？
现有测试是否足够？
是否需要 characterization test？
重构范围是否清楚？
是否有回滚点？

Agent流程

1. 分析当前结构。
2. 找重复、复杂度、边界问题。
3. 写重构计划。
4. 人审计划。
5. 小步改动。
6. 每步跑测试。
7. 最后做 diff 审查。

重构时可以让 Agent 先补 characterization test。它们不证明现有行为正确，只负责把现有行为固定下来，避免重构把行为改掉。

验证标准

Bug 修复：

原 bug 可复现。
修复后不再复现。
有回归测试。

重构：

外部行为不变。
测试通过。
diff 中没有无关功能变化。

停止条件

遇到下面情况，先停：

bug 无法复现，也无法给出可信复现路径。
修复需要改动权限、支付、数据删除、认证等高风险区域。
重构范围越过原计划。
测试失败原因说不清。
Agent 要引入新依赖绕过问题。

停止不是失败。先把状态、证据和未解决问题写进任务记录，再决定是否拆分任务。

复盘沉淀

任务结束后，让 Agent 回答这些问题，再决定要不要沉淀到规范：

这个 bug 为什么会出现？
哪些测试原本应该发现它？
AGENTS.md / CLAUDE.md 需要新增什么规则？
是否应该做成 bug-fix skill？

自动化脚本实战路径

一个常见的脚本执行步骤,定义CLI->让Agent写计划->实现和测试->整理交付记录

任务 1：定义 CLI

命令：
  check-md-links <dir>

输出：
  文件路径、行号、损坏链接。

退出码：
  0 表示无损坏链接。
  1 表示存在损坏链接。

任务 2：让 Agent 写计划

先把 Agent 限制在计划阶段：

不直接实现。
先列边界情况。
先列测试样例。

边界情况：

空目录。
无链接文件。
相对路径。
锚点链接。
外部链接跳过或只记录。

任务 3：实现和测试

顺序：

任务 4：整理交付记录

让 Agent 在完成后输出：

Changed files:
Commands run:
Known limitations:
Examples:
Next safe improvement:

如果它只说“完成了”，说明练习还没结束。

验证标准

样例目录下能识别坏链接。
正常链接不误报。
输出包含文件和行号。
测试通过。
退出码符合约定。
已说明暂不支持的链接类型。

工作流工具实战路径

手动创建一个任务目录。
让 Agent 根据需求填写 PRD。
让 Agent 先写实现计划，不写代码。
人工审查 Agent 的实现计划。
让 Agent 执行。
让 Agent 把验证结果记录到 status.md。
任务结束后写 retrospective.md。

个人开发者工作流

我认为个人开发者vibe coding最常见的问题就是基本只通过简单的一段话就想实现完整的某个功能/修改一个可能涉及范围比较大的bug,造成的后果可能是功能实现不完善或者bug无法完全被修复

任务前:

任务开始前先准备这五件事：

目标。
不做什么。
相关路径。
验收标准。
验证命令。

任务中:

任务进行中关注这些边界：

单次只做一个目标。
先计划再实现。
大任务拆成小任务。
改动范围不清楚就暂停。
测试失败先定位再修。

任务后:

任务收尾时，不要只结束会话；应把可复用经验记录下来：

哪条规则应该沉淀？
哪个流程适合做成 skill？
哪个测试应该补？
哪个文档应该更新？

团队工作流

团队使用 AI 的重点不在每个人都擅长 prompt，而在团队共用同一套上下文和质量标准。

团队规范

团队流程

可以追踪这些信号：

AI 任务一次通过率。
审查发现的高危问题数。
CI 修复轮次。
重复 bug 数量。
需求澄清轮次。
从 issue 到 PR 的周期。

指标用于改进工作流。指标异常时，优先检查任务定义、上下文入口和验证闸门，再考虑是否换模型。

检查清单

开发前清单

[ ] 目标清楚。
[ ] 不做哪些事已经写清楚。
[ ] 上下文入口清楚。
[ ] 相关规范文件存在。
[ ] 验收标准可验证。
[ ] 高风险点已标注。
[ ] 需要人确认的决策已列出。

让 Agent 开始前

[ ] 要求先只读分析。
[ ] 要求列文件范围。
[ ] 要求列计划。
[ ] 要求列验证命令。
[ ] 明确不要改无关文件。

实现中清单

[ ] 改动是否保持最小。
[ ] 是否遵守现有模式。
[ ] 是否引入新依赖。
[ ] 是否修改了公共接口。
[ ] 是否同步更新类型、文档、测试。

完成前清单

[ ] 测试已运行。
[ ] lint / typecheck / 构建已运行或说明不能运行原因。
[ ] Git diff 已审查。
[ ] 无临时代码。
[ ] 无无关改动。
[ ] 验收标准逐条满足。

复盘清单

[ ] 这次是否暴露规范缺失？
[ ] 是否有重复 prompt 可以写成 skill？
[ ] 是否有新测试应该补？
[ ] 是否有 MCP 能减少复制粘贴？
[ ] 是否有项目规则已经不符合当前做法？
[ ] 是否有本次经验应该写进任务模板或 skill？

常见坑

1.一句话开工。描述不清楚

开工前把四件事写清楚：

1	写 Goal / Context / Constraints / Done When。

2.网页端违章本地开发。把文件一段段复制给网页模型，让它生成补丁。

这样做容易制造表面正确但无法应用的补丁。网页模型看不到完整本地仓库，也跑不了测试

建议分工是：

1	网页端负责澄清，本地 Agent 负责执行。

3.规范文件写成作文

规范文件不是宣言。写太长、太虚，Agent 难以提取可执行约束。尤其是“写可验证、可维护的代码”“注意安全”这种话，看着正确，但没有可执行约束。

把规则改成短、明确、可验证：

1 2	短、硬、具体。每条规则问：删掉它，Agent 会犯错吗？

4.MCP装太多

MCP 不是越多越强。工具过多时，权限边界会变乱，调用噪声会变大，Agent 也更容易在多个相似工具里选错。

起步时只接最小集合：

1	先只读、少量、明确场景。

5.skills的复用

别人写的 skill 可以参考，但不能替你理解自己的流程。下载太多以后，常见结果是触发条件互相冲突，输出格式也和你的项目流程不匹配。

先从自己的高频流程提炼：

1	优先把自己的高频流程写成 skill。

6.不看diff

聊天总结可能遗漏事实，diff 记录实际改动。最终发生了什么，只能看文件改动。AI 可能附带修改无关文件，也可能绕过已有抽象，风险也可能出现在一行看似无害的改动里。

不要跳过最后这一步：

1	最终事实是 diff，不是聊天总结。

7.完成不验证

“AI 说完成”只是一个声明，不是证据。

1	AI 说完成 != 项目已经完成。

让它交代验证命令和结果；跑不了，也要说清楚为什么跑不了。

1	完成前必须运行或说明验证命令。

8.把工具数量当成能力

同时装很多 MCP、skills、hooks 和多 Agent 框架，看起来像系统，实际可能只是更难解释的混乱。

先问缺口：

1	当前失败来自任务不清、上下文不足、执行不稳、权限太大，还是验证缺失？

每次只补一层。补完后用一次真实任务验证它是否减少返工。

9.不写交接记录

长任务做到一半只靠聊天历史续命，很容易在上下文压缩、换工具或换人时断掉。

每次阶段结束都写四行：

已完成：
未完成：
验证结果：
下一步：

这些内容应该进入任务目录或项目文档，而不是只留在对话里。

跨阶段提示词库

跨阶段提示词库 - Vibe Coding 实战手册

Sekyoro的博客小屋

Beyond AI Coding:Harness工程与更好地AI开发

Harness的提出

上下文环境组成

如何工作

Harness Engineering

Harness的实践

实践

Web项目实战路径

Bug修复与重构路径

自动化脚本实战路径

工作流工具实战路径

个人开发者工作流

团队工作流

检查清单

常见坑

跨阶段提示词库

端到端流程

相关工具

SpecKit

OpenSpec

Superpowers

Trellis

参考资料