AI Harness Engineering 完全实战指南

前言

最近很多人提到的 Harness,并不是指某个叫 Harness 的厂商产品,而是指一套围绕 AI Agent 编程/交付 形成的新工程方法论。

如果用一句话概括:

AI Harness Engineering 不是让模型"更聪明",而是让工程环境、约束、反馈回路、验证手段和上下文组织方式更适合 Agent 持续稳定地产出。

这件事的核心变化在于,工程师的价值重心开始从"亲手写每一行代码",逐渐转向:

从这个角度看,Harness 更像一个"驾驭系统"而不是"提示词技巧"。


1. 什么是 AI Harness Engineering

1.1 先说人话定义

Harness 本意有"马具、驾具、约束与控制系统"的意思。放到 AI Agent 工程里,它指的是:

为 Agent 准备一套可以稳定工作的工程操作环境,让它知道去哪里看、按什么规则改、改完如何验证、出错后如何恢复。

所以,Harness Engineering 不是单点技巧,而是一整套工程组合拳:

1.2 它和 Prompt Engineering 的区别

很多人第一次接触 AI 编程时,关注点是 Prompt Engineering,也就是:

但到了 Agent 阶段,仅靠提示词已经不够了。

因为真实工程任务不是一次性问答,而是一个长链路过程:

  1. 读代码
  2. 理解上下文
  3. 跑命令
  4. 修改文件
  5. 运行测试
  6. 打开页面验证
  7. 看日志排错
  8. 再次修改
  9. 提交结果

Prompt 只解决"如何描述任务",Harness 解决的是"Agent 在真实工程系统里如何持续可靠地完成任务"。

1.3 一张表看懂 Prompt、Context、Harness

阶段 核心问题 关注重点 典型做法 局限性
Prompt Engineering 我要怎么说,模型才更容易回答对? 指令措辞 角色设定、few-shot、模板化提示词 适合短对话,不适合长链路任务
Context Engineering 我要给模型哪些信息,它才更可能做对? 上下文组织 RAG、规则文件、历史记录、工具输出注入 解决"知道什么",但不解决"如何稳定执行"
Harness Engineering 我要给 Agent 一个什么工作环境,它才会稳定完成任务? 环境、约束、反馈闭环 文档入口、脚本、验证、工具、护栏、进度文件、结构测试 建设成本更高,需要工程体系配合

一句话概括:

1.4 为什么它最近突然火了

因为过去一年,AI 编码工具从"代码补全"迅速进入了"可执行 Agent"阶段:

一旦 Agent 真正开始参与工程交付,大家很快就会发现一个现实:

大部分失败并不是模型完全不会写代码,而是环境不清晰、目标不明确、验证不完整、约束不够强。

这时,工程团队真正要做的,就不是继续堆提示词,而是开始"设计 Harness"。


2. Harness 的前世今生

2.1 前世:它并不是凭空出现的

虽然 Harness Engineering 这个词是最近才流行起来,但背后的思想其实并不新,至少能追溯到以下几类传统工程实践:

2.1.1 Test Harness

传统测试工程里早就有 test harness 的概念,即:

本质上就是给系统建立一个"可重复、可验证、可回归"的执行框架。

AI Harness 只是把这个思路从"测试程序"扩大到了"驾驭 Agent 干活"。

2.1.2 CI/CD Pipeline

CI/CD 做的事情其实也很像 Harness:

今天只是把执行主体从 shell 脚本和流水线任务,扩展到了具备推理能力的 Agent。

2.1.3 平台工程与 Golden Path

平台工程这些年一直在做一件事:给研发提供"标准路径"。

比如:

这些 golden path 天然就非常适合 Agent,因为 Agent 最怕的是"项目千奇百怪、每个仓库玩法不同"。

所以从某种意义上说:

Harness Engineering 是 Prompt Engineering、测试工程、平台工程、可观测性和自动化交付在 Agent 时代的一次汇合。

2.2 今生:这个词是怎么被正式讨论起来的

2026 年 2 月,Harness Engineering 这个说法开始快速出圈,主要有几条关键脉络:

2.2.1 Mitchell Hashimoto:把"反复犯错"变成"永久护栏"

Mitchell Hashimoto 在 2026 年 2 月 5 日的文章《My AI Adoption Journey》中,把 Engineer the Harness 明确作为 AI 工作流的一个阶段。

他的核心观点非常务实:

这一定义非常接地气,也最适合一线工程师理解。

2.2.2 OpenAI:把 Harness 提升为"Agent-first 工程方法"

OpenAI 在 2026 年 2 月 11 日发布了《Harness engineering: leveraging Codex in an agent-first world》。

这篇文章的重要性在于,它不再把 Harness 当成零散技巧,而是把它上升为一套完整工程实践:

OpenAI 还给出了一个很强的信号:

Human steer. Agents execute.

也就是:

2.2.3 Anthropic:长任务 Agent 需要初始化环境与进度文件

Anthropic 在 2025 年底到 2026 年初围绕长时间运行 Agent 的实践里,系统讨论了 effective harnesses。

它给出的关键经验很有代表性:

这套思路本质上就是:

给长链路 Agent 一个稳定的接力机制。

2.3 一个更准确的理解

所以今天说 Harness,不要把它理解成某个产品名词,更不要把它理解成"高级 prompt 模板"。

更准确的理解是:

当 AI 从回答问题变成执行工程任务后,我们需要给它配一整套工程操作系统,这套操作系统就是 Harness。


3. AI Harness Engineering 的核心组成

3.1 上下文工程:让 Agent 找得到"真相"

Agent 最怕的不是代码复杂,而是信息分散。

如果关键信息在:

那对 Agent 来说,这些信息几乎等于不存在。

因此 Harness 的第一层,就是把"真实知识"尽量收敛进仓库或可访问系统中,例如:

最佳实践不是写一个 1000 行大而全的入口文件,而是:

3.2 任务拆解:别让 Agent 一口吃成胖子

很多人用 Agent 的第一反应是:

帮我把这个系统重构完,并补齐测试,再优化前端,再修一下部署。

这种任务几乎天然高风险。

对 Agent 来说,好的任务应该是:

典型做法:

3.3 验证闭环:让 Agent 自己知道哪里错了

Harness 的核心不是"让 Agent 一次写对",而是"让 Agent 出错后能尽快发现并修正"。

常见验证手段包括:

如果没有验证,Agent 很容易出现几类典型假成功:

所以工程上真正应该投资的是:

把"你错了"这件事,尽量从人工肉眼检查,变成机器可判定信号。

3.4 工具接入:让 Agent 有手有脚

没有工具的 Agent,本质上还是高级聊天机器人。

真正能落地的 Harness,通常会给 Agent 接上这些能力:

对于一线工程师来说,最实用的一条原则是:

优先接入那些能帮助 Agent 自证正确性的工具,而不是只接入"更多信息"。

例如:

3.5 Skills:把经验固化为可复用工作流

这是 Harness 里容易被忽视的一层。

所谓 Skills,就是把"每次排障/执行的标准步骤"结构化后,包装成 Agent 可以直接调用的命名工作流。

不同工具对 Skills 的实现方式不同,但核心思路一致:

不要让 Agent 每次从零开始猜步骤——把经过验证的 SOP 显式化,让 Agent 直接调用。

这件事的价值在于:

具体实现方式会在第六章结合 Codex 和 Claude Code 分别展示。

3.6 架构约束:自由度太高反而会害死 Agent

很多人以为,Agent 越强,越应该给它完全自由。

现实往往相反。

在真实工程里,Agent 在这些环境下更容易稳定产出:

OpenAI 的一个很重要经验就是:对 Agent 来说,严格边界和可预测结构是生产力倍增器。

这意味着你应该尽量把这些规则显式化:

并尽可能把这些规则做成:

3.7 熵增治理:Agent 会复制坏模式

这点非常重要。

Agent 有一个天然特征:它会复制代码库里已经存在的模式。

如果仓库里已有坏味道,Agent 往往会把坏味道规模化扩散:

所以 Harness 不能只解决"如何生成",还必须解决"如何持续清理"。

常见做法:

也就是说,Harness 不是静态模板,而是一个持续迭代的治理系统。


4. 适用场景

4.1 最适合 Harness 的场景

下面这些场景,通常非常适合引入 AI Harness Engineering:

场景 为什么适合 典型任务
存量项目日常维护 任务碎、重复多、验证链路清晰 修 bug、补测试、修 lint、升级依赖
前后端联调修复 能通过页面、接口、日志形成闭环 页面报错修复、接口字段对齐、表单提交流程修复
CI 失败自动修复 输入与报错明确,验证标准固定 修构建失败、修测试失败、修镜像构建脚本
Kubernetes / IaC 调整 配置结构化,命令可验证 修 YAML、调 Helm values、修 Terraform 模块
文档与代码同步 规则容易结构化和自动检查 更新 runbook、补使用说明、同步 API 文档
小步重构 可控、可拆、可逐步验证 提取公共函数、统一错误处理、拆大文件

4.2 非常有价值但需要更强 Harness 的场景

这些场景不是不能做,而是必须先把护栏搭好:

因为这些任务的共同特点是:

在这类场景里,Harness 不足时,Agent 很容易"看起来改了很多,实际上风险更大"。

4.3 明显不适合直接放手给 Agent 的场景

如果满足下面任一条,就不建议一开始就让 Agent 高自治执行:

这时更合适的方式是:


5. 一线工程师如何真正落地 Harness

5.1 第一阶段:别追求全自动,先追求"少踩坑"

很多团队一上来就想做全自动编码、全自动提 PR、全自动合并。

这通常不是最优路径。

更现实的第一阶段应该是:

  1. 先让 Agent 知道怎么构建和测试
  2. 先让 Agent 知道仓库规则和常见坑
  3. 先让 Agent 能验证自己的修改
  4. 先让 Agent 只做小任务
  5. 先让 Agent 把结果交给人审核

简单说就是:

先让它"可用",再让它"自治"。

5.2 第二阶段:最小可用 Harness 该长什么样

如果你现在就想在项目里落地,一个最小可用版本通常只需要下面这些东西:

5.2.1 一个短小的入口文档

建议内容包括:

Codex 读 AGENTS.md,Claude Code 读 CLAUDE.md 或 AGENTS.md,两者格式兼容。同一份文件可以同时服务两个工具。

示例:

# AGENTS.md

## Build
- Install: `pnpm install`
- Dev: `pnpm dev`
- Test: `pnpm test`
- Lint: `pnpm lint`

## Rules
- Do not edit generated files under `src/generated`
- Changes in `api/` must update tests in `tests/api`
- Keep service layer free of UI imports

## Verification
- Run `pnpm lint && pnpm test`
- For UI changes, run `pnpm test:e2e`

5.2.2 一组可复用脚本

不要要求 Agent 每次自己猜命令。

直接提供稳定脚本,例如:

示例:

#!/usr/bin/env bash
set -euo pipefail

pnpm lint
pnpm test
pnpm test:e2e --reporter=line

5.2.3 一个进度文件

如果任务可能跨多个会话,建议增加:

这样新一轮 Agent 进来时,不用重新猜之前做到了哪里。

5.2.4 一套明确的验证入口

最怕的是:

要尽量收敛成:

5.3 第三阶段:给 Agent 增加"可见性"

当你发现 Agent 会改代码,但总在验证阶段翻车时,就该补这一层:

目标不是"让 Agent 知道更多",而是"让 Agent 观察到运行结果"。

因为很多问题只看代码看不出来:

5.4 第四阶段:把人工经验固化成 Skills

每当你看到 Agent 犯一个重复错误,就问自己:

这个错误,能不能不要靠我下次再提醒,而是直接被机制阻止?

常见落地方式:

这一步,才是 Harness 真正开始"复利"的地方。


6. 实战:用 Codex + Skills 和 Claude Code + Skills 落地 K8s Harness

这一章不再讲抽象原则,直接带你做一个真实项目,并用两种主流工具各走一遍完整流程。

选用的开源项目是 dockersamples/example-voting-app,原因很简单:

6.1 项目结构与实验目标

example-voting-app 的核心组件:

组件 技术栈 说明
vote Python 前端投票页面,NodePort 31000
result Node.js 结果展示页面,NodePort 31001
worker .NET 消费 Redis 消息并写入 Postgres
redis Redis 消息缓存
db Postgres 持久化存储

这一章要演示的,不只是"把故障修好",而是两个工具在同一个 Harness 基础上,如何通过各自的 Skills 机制稳定驱动排障:

  1. 搭建公共 Harness 基础(两个工具共用)
  2. 场景 A:用 Codex + Skills 完成两个典型故障的排查与修复
  3. 场景 B:用 Claude Code + Skills 完成同样的排查与修复
  4. 对比两种工具的 Harness 异同,沉淀最终资产

6.2 准备实验环境

如果你没有现成的 Kubernetes 集群,可以参考 基于Kind搭建测试集群。

配置文件 vote-kind.yaml(将 10.10.50.30 替换成你的实际宿主机 IP):

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
networking:
  apiServerAddress: "10.10.50.30"
nodes:
- role: control-plane
  extraPortMappings:
  - containerPort: 31000
    hostPort: 31000
    listenAddress: "10.10.50.30"
    protocol: tcp
  - containerPort: 31001
    hostPort: 31001
    listenAddress: "10.10.50.30"
    protocol: tcp
- role: worker
- role: worker

坑:31000、31001 需要手工映射,但不要把 6443 放进 extraPortMappings。Kind 本身会处理 API server 的 6443,再手工映射一次会导致 kind create cluster 在收尾阶段报错。

sudo kind create cluster --config=vote-kind.yaml --name vote-demo --image kindest/node:v1.34.0 --retain

~/.kube 权限异常时,直接导出到临时文件:

kind export kubeconfig --name vote-demo --kubeconfig /tmp/vote-demo.kubeconfig
export KUBECONFIG=/tmp/vote-demo.kubeconfig

6.3 首次部署与建立 baseline

git clone https://github.com/dockersamples/example-voting-app.git
cd example-voting-app
kubectl create namespace vote-demo
kubectl apply -n vote-demo -f k8s-specifications/

等待所有工作负载进入 Running 后,建立 baseline——这一步不能跳过,没有正常态的参照,后面的排障就是盲人摸象:

curl -I http://10.10.50.30:31000   # 期望 200
curl -I http://10.10.50.30:31001   # 期望 200

再手工投一票,确认 result 页面的统计数字变化,baseline 建立完毕。

6.4 搭建公共 Harness 基础

Codex 和 Claude Code 都会读 AGENTS.md,所以公共 Harness 只需要维护一套。

# AGENTS.md

## Repo Layout
- `k8s-specifications/`: upstream Kubernetes manifests
- `vote/`: Python voting UI
- `result/`: Node.js result UI
- `worker/`: background worker

## Cluster
- Kind cluster name: `vote-demo`
- Namespace: `vote-demo`
- Vote URL: `http://10.10.50.30:31000`
- Result URL: `http://10.10.50.30:31001`

## Standard Commands
- Deploy: `kubectl apply -n vote-demo -f k8s-specifications/`
- Check pods: `kubectl get pods -n vote-demo`
- Check services: `kubectl get svc -n vote-demo`
- Describe pod: `kubectl describe pod <name> -n vote-demo`
- View logs: `kubectl logs <name> -n vote-demo`

## Constraints
- Only modify files under `k8s-specifications/`
- One task = one service, unless the issue crosses service boundaries
- After every fix, run `scripts/verify-cluster.sh` and `scripts/smoke-app.sh`

## Debugging Priority
1. `kubectl get pods,svc,endpoints -n vote-demo`
2. `kubectl describe`
3. `kubectl logs`
4. Reproduce via curl or browser
5. Apply the smallest possible YAML fix

6.4.2 集群验证脚本

# scripts/verify-cluster.sh
#!/usr/bin/env bash
set -euo pipefail

kubectl get pods -n vote-demo
kubectl wait --for=condition=Available deployment/vote -n vote-demo --timeout=180s
kubectl wait --for=condition=Available deployment/result -n vote-demo --timeout=180s
kubectl wait --for=condition=Available deployment/worker -n vote-demo --timeout=180s
kubectl get svc -n vote-demo
kubectl get endpoints -n vote-demo

6.4.3 Smoke 验证脚本

# scripts/smoke-app.sh
#!/usr/bin/env bash
set -euo pipefail

vote_code=$(curl -s -o /tmp/vote.html -w '%{http_code}' http://10.10.50.30:31000)
result_code=$(curl -s -o /tmp/result.html -w '%{http_code}' http://10.10.50.30:31001)

test "$vote_code" = "200"
test "$result_code" = "200"

6.5 场景 A:用 Codex + Skills 排障

Skills 在 Codex 中是什么

Codex 的 Skills 是定义在 AGENTS.md(或单独的 SKILLS.md)里的命名工作流。

每个 Skill 有一个名字和一套标准步骤。当你在任务描述里引用 Skill 名称,Codex 会直接按照 Skill 定义执行,而不是重新推理步骤。

这是 Harness 里非常关键的一层:把验证过的 SOP 显式化,让 Agent 不用每次从零猜。

定义 k8s-diagnose Skill

在 AGENTS.md 末尾追加 ## Skills 小节:

## Skills

### k8s-diagnose
适用场景:vote-demo 集群中任意 K8s 故障排查
执行步骤:
1. `kubectl get pods,svc,endpoints -n vote-demo` — 确认整体状态
2. 分支判断:
   - Pod 状态非 Running → `kubectl describe pod <name> -n vote-demo`,看 Events
   - Pod Running 但访问异常 → `kubectl describe svc <name> -n vote-demo` + `kubectl get endpoints -n vote-demo`
3. `bash scripts/smoke-app.sh` — 复现访问失败,拿到机器信号
4. 只修改直接相关的 `k8s-specifications/` 文件,最小改动
5. `bash scripts/verify-cluster.sh && bash scripts/smoke-app.sh` — 验收
输出:根因(一句话)/ 修改文件 / 验证结果 / 是否需要新增长期护栏

故障一:Result 页面打不开(targetPort 错误)

注入故障

将 result-service.yaml 中的 targetPort 从 80 改成 81,然后应用:

kubectl apply -n vote-demo -f k8s-specifications/result-service.yaml

故障现象:Pod 全部 Running,但 curl http://10.10.50.30:31001 返回 000。光看 Pod 状态完全无法发现问题。

下发任务

使用 k8s-diagnose Skill 修复 vote-demo 命名空间中 result 页面不可访问的问题。

约束:
- 只允许修改 k8s-specifications/result-service.yaml
- 先排查,再修改

验收:
- http://10.10.50.30:31001 返回 200
- kubectl get endpoints result -n vote-demo 存在有效后端

Codex 排查过程

Codex 检索到 k8s-diagnose Skill,按步骤 1 执行:

kubectl get pods,svc,endpoints -n vote-demo

发现 endpoints/result 注册成了 10.244.1.3:81,进入步骤 2 的"访问异常"分支:

kubectl describe svc result -n vote-demo

确认 targetPort: 81,对照 result-deployment.yaml 确认容器只暴露 containerPort: 80。

根因:Service 的 targetPort: 81 与容器实际监听的 80 不匹配。

最小修改 targetPort: 81 → targetPort: 80,应用后执行步骤 5 验收:

kubectl apply -n vote-demo -f k8s-specifications/result-service.yaml
bash scripts/verify-cluster.sh && bash scripts/smoke-app.sh

全部通过。

故障二:Vote 服务进入 ImagePullBackOff

注入故障

将 vote-deployment.yaml 的镜像改为不存在的 tag:

- image: dockersamples/examplevotingapp_vote:does-not-exist
kubectl apply -n vote-demo -f k8s-specifications/vote-deployment.yaml

故障现象:新 Pod 进入 ImagePullBackOff,rollout 卡住。注意:旧 Pod 可能还在提供服务,所以 curl 短时间内仍可能返回 200,单凭 curl 无法判断。

下发任务

使用 k8s-diagnose Skill 修复 vote 服务无法启动的问题。

约束:
- 只允许修改 k8s-specifications/vote-deployment.yaml
- 必须先确认 Pod 失败根因,再动文件

验收:
- vote Pod 恢复 Running
- http://10.10.50.30:31000 返回 200

Codex 排查过程

步骤 1 发现新 Pod 处于 ImagePullBackOff,进入"Pod 状态非 Running"分支:

kubectl describe pod -l app=vote -n vote-demo

Events 区域明确显示:Failed to pull image "dockersamples/examplevotingapp_vote:does-not-exist"。

根因:镜像 tag 不存在,Pod 卡在 ErrImagePull。

去掉不存在的 tag,执行步骤 5 验收:

kubectl apply -n vote-demo -f k8s-specifications/vote-deployment.yaml
kubectl rollout status deployment/vote -n vote-demo --timeout=180s
bash scripts/verify-cluster.sh && bash scripts/smoke-app.sh

rollout 完成,vote Pod 恢复 Running,验收全部通过。


6.6 场景 B:用 Claude Code + Skills 排障

Skills 在 Claude Code 中是什么

Claude Code 的 Skills 是存放在 .claude/commands/ 目录下的 .md 文件,每个文件对应一个可复用的工作流,通过 /skill-name 触发。

与 Codex Skills 的核心差异:

Codex Skills Claude Code Skills
定义位置 AGENTS.md 的 ## Skills 小节 .claude/commands/<name>.md
触发方式 在任务描述中引用 Skill 名称 对话中输入 /skill-name
作用范围 全局,Codex 自动检索 当前 Claude Code 会话
适合场景 离线/后台 Agent 任务 人机交互式排障

两者的 Skill 内容可以互相参考,但触发方式不同。

定义 /k8s-debug Skill

创建 .claude/commands/k8s-debug.md:

# K8s 故障排查

按以下顺序排查 vote-demo 命名空间的 K8s 故障:

## 步骤

**1. 确认整体状态**
运行 `kubectl get pods,svc,endpoints -n vote-demo`,记录异常项。

**2. 判断故障类型,选择排查路径**

- Pod 状态非 Running(CrashLoopBackOff、ImagePullBackOff 等)
  → `kubectl describe pod <name> -n vote-demo`,重点看 Events 区域
- Pod Running 但访问异常
  → `kubectl describe svc <name> -n vote-demo`
  → `kubectl get endpoints -n vote-demo`,确认后端 IP:Port 是否正确

**3. 复现访问失败**
`bash scripts/smoke-app.sh`,拿到机器可判定的失败信号。

**4. 最小修复**
只修改直接相关的 `k8s-specifications/` 文件,改动范围不超过一个资源对象。

**5. 验收**
`bash scripts/verify-cluster.sh && bash scripts/smoke-app.sh`

## 输出格式
- **根因**:一句话说清楚
- **修改文件**:文件路径 + 具体改动
- **验证结果**:关键命令的输出摘要
- **建议护栏**:是否需要新增规则或脚本防止复发

故障一:Result 页面打不开

使用相同的故障注入(targetPort: 81),在 Claude Code 里触发 Skill:

/k8s-debug result 页面 http://10.10.50.30:31001 返回 000,请排查修复。
约束:只允许修改 k8s-specifications/result-service.yaml

Claude Code 加载 k8s-debug Skill,按步骤依次执行。步骤 2 进入"Pod Running 但访问异常"分支,kubectl describe svc result + kubectl get endpoints 锁定根因:targetPort 错误。

最小修改 + 步骤 5 验收,全部通过。输出:

根因:result Service 的 targetPort 配置为 81,但容器只监听 80,导致 Endpoints 注册错误端口。
修改文件:k8s-specifications/result-service.yaml,targetPort: 81 → targetPort: 80
验证结果:endpoints/result 恢复 10.244.1.3:80,smoke-app.sh 退出码 0
建议护栏:在 AGENTS.md 中添加"修改 Service 后必须运行 smoke-app.sh"检查项

故障二:Vote 服务 ImagePullBackOff

使用相同的故障注入(:does-not-exist tag),在 Claude Code 里触发 Skill:

/k8s-debug vote 服务新 Pod 无法启动,请排查修复。
约束:只允许修改 k8s-specifications/vote-deployment.yaml

步骤 2 进入"Pod 状态非 Running"分支,kubectl describe pod 的 Events 区域直接给出镜像拉取失败的错误。

最小修改 + rollout 等待 + 步骤 5 验收,全部通过。


6.7 两种工具的 Harness 对比

维度 Codex + Skills Claude Code + Skills
上下文入口 AGENTS.md AGENTS.md / CLAUDE.md(兼容)
Skill 定义 AGENTS.md 的 ## Skills 小节 .claude/commands/<name>.md
Skill 触发 任务描述中引用 Skill 名称 对话中 /skill-name
执行模式 适合无人值守的后台任务 适合人机交互式排障
验证脚本 共用 scripts/verify-cluster.sh + scripts/smoke-app.sh 共用,完全一致
Harness 文档 共用 AGENTS.md 共用,完全一致

关键结论:Harness 基础层(AGENTS.md + 脚本)对两个工具完全共用,差异只在 Skill 的定义方式和触发方式。 维护一套 Harness 就能同时支撑两个工具。

6.8 沉淀 Harness 资产

修好了只是普通排障;把经验沉淀成规则、Skill 和任务模板,才算真正做了 Harness Engineering。

固定任务模板

任务:修复 vote-demo 集群中的某个发布故障

(Codex)使用 k8s-diagnose Skill 执行
(Claude Code)触发 /k8s-debug Skill 执行

约束:
- 只修改直接相关的 k8s-specifications/ 文件
- 修改后必须执行 scripts/verify-cluster.sh 和 scripts/smoke-app.sh

输出:根因 / 修改文件 / 验证结果 / 是否需要新增护栏

固定验证入口

bash scripts/verify-cluster.sh
bash scripts/smoke-app.sh

无论是人工操作、Codex 任务还是 Claude Code 排障,验证入口统一。

复盘记录

每修完一个问题,补一条简短记录:

# retro-result-service-port

- symptom: result page unavailable on 31001
- root cause: service targetPort changed from 80 to 81
- detection: kubectl describe svc result + smoke check
- permanent fix: require scripts/smoke-app.sh after every service change
- skill update: k8s-diagnose / /k8s-debug 步骤 3 已覆盖此场景,无需单独更新

这一步看起来简单,但它决定了你的系统是"每次重新踩坑",还是"Agent 越用越稳"。


7. 常见误区

7.1 误区一:把 Harness 等同于提示词模板

错。

提示词只是入口,Harness 是整套运行环境。Skills 也不是"更好的提示词",而是把验证过的工作流显式化。

7.2 误区二:觉得模型变强后 Harness 就不重要了

也错。

模型越强,能做的事越多,造成的破坏半径也越大。越是高自治,就越需要约束、验证和恢复机制。

7.3 误区三:没有测试也能先上 Agent

可以做,但收益会被严重限制。

没有验证闭环,Agent 的大部分输出都需要人工兜底,效率很难真正起飞。

7.4 误区四:让 Agent 直接处理高风险生产变更

如果没有成熟 Harness,这通常不是工程进步,而是在拿线上系统做实验。

7.5 误区五:Codex 和 Claude Code 要维护两套 Harness

不需要。

AGENTS.md 和验证脚本对两个工具完全共用。Skills 的定义位置不同,但内容可以直接复用,改动量极小。

7.6 误区六:只盯着"生成速度",忽视"熵增速度"

Agent 最大的长期问题之一,不是写得慢,而是坏模式扩散得太快。

没有治理的高速生成,最后往往会变成更快的技术债堆积。


8. 我的结论

如果说 Prompt Engineering 解决的是"怎么和模型说话",那么 AI Harness Engineering 解决的是:

怎么把一个会说话、会用工具、会改代码的 Agent,真正纳入工程生产体系。

它的关键不在于神奇提示词,而在于五件事:

对一线工程师来说,Harness 最现实的意义不是"完全取代开发",而是:

未来真正拉开差距的,大概率不是谁"会不会用 Agent",而是谁能把自己的工程系统改造成 Agent 友好型系统。

而这件事,本质上就是 Harness Engineering。


9. 参考资料