AI Harness Engineering 完全实战指南
前言
最近很多人提到的 Harness,并不是指某个叫 Harness 的厂商产品,而是指一套围绕 AI Agent 编程/交付 形成的新工程方法论。
如果用一句话概括:
AI Harness Engineering 不是让模型"更聪明",而是让工程环境、约束、反馈回路、验证手段和上下文组织方式更适合 Agent 持续稳定地产出。
这件事的核心变化在于,工程师的价值重心开始从"亲手写每一行代码",逐渐转向:
- 定义目标
- 拆解任务
- 提供高质量上下文
- 设计验证机制
- 增加约束和护栏
- 让 Agent 可以自查、自修、自迭代
从这个角度看,Harness 更像一个"驾驭系统"而不是"提示词技巧"。
1. 什么是 AI Harness Engineering
1.1 先说人话定义
Harness 本意有"马具、驾具、约束与控制系统"的意思。放到 AI Agent 工程里,它指的是:
为 Agent 准备一套可以稳定工作的工程操作环境,让它知道去哪里看、按什么规则改、改完如何验证、出错后如何恢复。
所以,Harness Engineering 不是单点技巧,而是一整套工程组合拳:
- 上下文组织
- 任务拆解
- 工具接入
- 测试与验证
- 架构约束
- 日志与可观测性
- 失败恢复
- 持续清理熵增
1.2 它和 Prompt Engineering 的区别
很多人第一次接触 AI 编程时,关注点是 Prompt Engineering,也就是:
- 提示词怎么写
- 角色怎么设
- 要不要加 few-shot
- system prompt 怎么调
但到了 Agent 阶段,仅靠提示词已经不够了。
因为真实工程任务不是一次性问答,而是一个长链路过程:
- 读代码
- 理解上下文
- 跑命令
- 修改文件
- 运行测试
- 打开页面验证
- 看日志排错
- 再次修改
- 提交结果
Prompt 只解决"如何描述任务",Harness 解决的是"Agent 在真实工程系统里如何持续可靠地完成任务"。
1.3 一张表看懂 Prompt、Context、Harness
| 阶段 | 核心问题 | 关注重点 | 典型做法 | 局限性 |
|---|---|---|---|---|
| Prompt Engineering | 我要怎么说,模型才更容易回答对? | 指令措辞 | 角色设定、few-shot、模板化提示词 | 适合短对话,不适合长链路任务 |
| Context Engineering | 我要给模型哪些信息,它才更可能做对? | 上下文组织 | RAG、规则文件、历史记录、工具输出注入 | 解决"知道什么",但不解决"如何稳定执行" |
| Harness Engineering | 我要给 Agent 一个什么工作环境,它才会稳定完成任务? | 环境、约束、反馈闭环 | 文档入口、脚本、验证、工具、护栏、进度文件、结构测试 | 建设成本更高,需要工程体系配合 |
一句话概括:
- Prompt Engineering 解决"说什么"
- Context Engineering 解决"知道什么"
- Harness Engineering 解决"在什么环境里做事"
1.4 为什么它最近突然火了
因为过去一年,AI 编码工具从"代码补全"迅速进入了"可执行 Agent"阶段:
- 可以读写文件
- 可以运行终端命令
- 可以调用浏览器
- 可以接入 MCP / 外部工具
- 可以在较长时间内持续执行任务
一旦 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 工作流的一个阶段。
他的核心观点非常务实:
- Agent 更高效的前提,是尽量第一次就做对
- 每次 Agent 犯同样的错,都应该花时间做一个机制,让它以后别再犯
- 这个机制既可以是
AGENTS.md之类的隐式提示,也可以是实际可执行脚本与工具
这一定义非常接地气,也最适合一线工程师理解。
2.2.2 OpenAI:把 Harness 提升为"Agent-first 工程方法"
OpenAI 在 2026 年 2 月 11 日发布了《Harness engineering: leveraging Codex in an agent-first world》。
这篇文章的重要性在于,它不再把 Harness 当成零散技巧,而是把它上升为一套完整工程实践:
- 用仓库内文档作为 system of record
- 用短
AGENTS.md作为目录入口,而不是超长说明书 - 让 Agent 直接访问 UI、日志、指标、链路
- 用结构化架构约束和自定义 lint 限制自由度
- 用后台 Agent 定期做"垃圾回收"和技术债清理
OpenAI 还给出了一个很强的信号:
Human steer. Agents execute.
也就是:
- 人负责方向、约束、审美、判断
- Agent 负责执行、验证、迭代和规模化产出
2.2.3 Anthropic:长任务 Agent 需要初始化环境与进度文件
Anthropic 在 2025 年底到 2026 年初围绕长时间运行 Agent 的实践里,系统讨论了 effective harnesses。
它给出的关键经验很有代表性:
- 初始会话不要直接开干,而是先让
initializer agent准备环境 - 建立 feature list,避免 Agent 过早宣布"做完了"
- 建立 progress file,避免新上下文窗口接手时完全失忆
- 每次只推进一个特性,避免"一口气把整个系统做坏"
- 强制做端到端验证,而不是只跑单测或
curl
这套思路本质上就是:
给长链路 Agent 一个稳定的接力机制。
2.3 一个更准确的理解
所以今天说 Harness,不要把它理解成某个产品名词,更不要把它理解成"高级 prompt 模板"。
更准确的理解是:
当 AI 从回答问题变成执行工程任务后,我们需要给它配一整套工程操作系统,这套操作系统就是 Harness。
3. AI Harness Engineering 的核心组成
3.1 上下文工程:让 Agent 找得到"真相"
Agent 最怕的不是代码复杂,而是信息分散。
如果关键信息在:
- 飞书聊天记录
- 口头约定
- 过期 wiki
- 脑子里
那对 Agent 来说,这些信息几乎等于不存在。
因此 Harness 的第一层,就是把"真实知识"尽量收敛进仓库或可访问系统中,例如:
AGENTS.md/CLAUDE.mdARCHITECTURE.mddocs/runbookscripts/Makefiletask listprogress file
最佳实践不是写一个 1000 行大而全的入口文件,而是:
- 入口文件只做索引
- 深层知识拆到不同文档
- 文档版本化
- 文档可校验
- 文档与代码一起演进
3.2 任务拆解:别让 Agent 一口吃成胖子
很多人用 Agent 的第一反应是:
帮我把这个系统重构完,并补齐测试,再优化前端,再修一下部署。
这种任务几乎天然高风险。
对 Agent 来说,好的任务应该是:
- 边界清晰
- 输入明确
- 输出可验证
- 时长可控
- 回滚容易
典型做法:
- 先设计,再执行
- 先计划,再编码
- 一次只做一个功能或一个 bug
- 大任务拆成多个独立 PR
- 每一步都能单独验证
3.3 验证闭环:让 Agent 自己知道哪里错了
Harness 的核心不是"让 Agent 一次写对",而是"让 Agent 出错后能尽快发现并修正"。
常见验证手段包括:
- 单元测试
- 集成测试
- 端到端测试
- 静态检查
- 类型检查
- lint
- 快照比对
- 浏览器自动化
- API contract 校验
- 性能阈值校验
- 安全扫描
如果没有验证,Agent 很容易出现几类典型假成功:
- 代码能跑,但需求没实现
- 单测通过,但页面功能坏了
- 功能表面正常,但日志里全是报错
- 改好了 A,顺手把 B 搞坏了
所以工程上真正应该投资的是:
把"你错了"这件事,尽量从人工肉眼检查,变成机器可判定信号。
3.4 工具接入:让 Agent 有手有脚
没有工具的 Agent,本质上还是高级聊天机器人。
真正能落地的 Harness,通常会给 Agent 接上这些能力:
- 读写仓库文件
- 运行构建与测试命令
- 浏览器自动化
- 日志查询
- 指标查询
- Trace 查询
- Git 操作
- PR / Issue 操作
- 部署环境只读排查能力
对于一线工程师来说,最实用的一条原则是:
优先接入那些能帮助 Agent 自证正确性的工具,而不是只接入"更多信息"。
例如:
- 能截图,比单纯能读 HTML 更有用
- 能跑
npm test,比只看 package.json 更有用 - 能查日志和指标,比只看 YAML 更有用
3.5 Skills:把经验固化为可复用工作流
这是 Harness 里容易被忽视的一层。
所谓 Skills,就是把"每次排障/执行的标准步骤"结构化后,包装成 Agent 可以直接调用的命名工作流。
不同工具对 Skills 的实现方式不同,但核心思路一致:
不要让 Agent 每次从零开始猜步骤——把经过验证的 SOP 显式化,让 Agent 直接调用。
这件事的价值在于:
- 减少 Agent 的无效探索
- 保证关键流程的可重复性
- 让团队积累的操作经验真正变成资产
具体实现方式会在第六章结合 Codex 和 Claude Code 分别展示。
3.6 架构约束:自由度太高反而会害死 Agent
很多人以为,Agent 越强,越应该给它完全自由。
现实往往相反。
在真实工程里,Agent 在这些环境下更容易稳定产出:
- 目录结构稳定
- 分层清晰
- 依赖方向固定
- 命名规则统一
- 入口明确
- 边界清楚
OpenAI 的一个很重要经验就是:对 Agent 来说,严格边界和可预测结构是生产力倍增器。
这意味着你应该尽量把这些规则显式化:
- 哪些层可以依赖哪些层
- 哪些目录不允许跨层调用
- 哪些字段必须经过 schema 校验
- 哪些文件不能超过多大
- 哪些日志必须结构化
并尽可能把这些规则做成:
- lint
- structural test
- CI check
- 自动修复脚本
3.7 熵增治理:Agent 会复制坏模式
这点非常重要。
Agent 有一个天然特征:它会复制代码库里已经存在的模式。
如果仓库里已有坏味道,Agent 往往会把坏味道规模化扩散:
- 复制烂 helper
- 继续堆 if-else
- 延续不合理命名
- 抄旧的临时写法
- 沿袭未清理的技术债
所以 Harness 不能只解决"如何生成",还必须解决"如何持续清理"。
常见做法:
- 周期性整理文档
- 周期性扫描架构漂移
- 周期性做小步重构
- 周期性修 lint / 类型 / schema 漏洞
- 建立 golden principles
也就是说,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 高自治执行:
- 需求本身还没讨论清楚
- 业务规则高度依赖隐性知识
- 缺少可执行验证手段
- 仓库极度混乱,没有稳定入口
- 任何一次误改都可能造成严重事故
这时更合适的方式是:
- 让 Agent 先做调研、整理、分析
- 让人做最终判断
- 先补 Harness,再提高自治级别
5. 一线工程师如何真正落地 Harness
5.1 第一阶段:别追求全自动,先追求"少踩坑"
很多团队一上来就想做全自动编码、全自动提 PR、全自动合并。
这通常不是最优路径。
更现实的第一阶段应该是:
- 先让 Agent 知道怎么构建和测试
- 先让 Agent 知道仓库规则和常见坑
- 先让 Agent 能验证自己的修改
- 先让 Agent 只做小任务
- 先让 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 每次自己猜命令。
直接提供稳定脚本,例如:
scripts/bootstrap.shscripts/verify.shscripts/smoke.shscripts/test-changed.sh
示例:
#!/usr/bin/env bash
set -euo pipefail
pnpm lint
pnpm test
pnpm test:e2e --reporter=line
5.2.3 一个进度文件
如果任务可能跨多个会话,建议增加:
agent-progress.mdfeature-list.jsondocs/exec-plans/
这样新一轮 Agent 进来时,不用重新猜之前做到了哪里。
5.2.4 一套明确的验证入口
最怕的是:
- 构建命令有 4 套
- 测试命令每个人记忆不同
- 本地和 CI 跑法不一致
要尽量收敛成:
- 一个标准启动入口
- 一个标准验证入口
- 一个标准 smoke test 入口
5.3 第三阶段:给 Agent 增加"可见性"
当你发现 Agent 会改代码,但总在验证阶段翻车时,就该补这一层:
- 浏览器自动化
- 截图
- DOM 快照
- 日志查询
- 指标查询
- Trace 查询
目标不是"让 Agent 知道更多",而是"让 Agent 观察到运行结果"。
因为很多问题只看代码看不出来:
- 页面按钮点了没反应
- 请求 200 但渲染错了
- 服务能启动但性能恶化
- 功能正常但日志疯狂报错
5.4 第四阶段:把人工经验固化成 Skills
每当你看到 Agent 犯一个重复错误,就问自己:
这个错误,能不能不要靠我下次再提醒,而是直接被机制阻止?
常见落地方式:
- 写进入口文档
- 写成 lint 规则
- 写成结构测试
- 写成 schema 校验
- 写成 pre-commit / CI check
- 封装成 Skill,让 Agent 下次直接调用
这一步,才是 Harness 真正开始"复利"的地方。
6. 实战:用 Codex + Skills 和 Claude Code + Skills 落地 K8s Harness
这一章不再讲抽象原则,直接带你做一个真实项目,并用两种主流工具各走一遍完整流程。
选用的开源项目是 dockersamples/example-voting-app,原因很简单:
- 标准的多服务应用,不是单 Pod 玩具项目
- 官方仓库自带 Kubernetes YAML,开箱即用
- 组件足够少,一小时内能完整跑一遍
- 天然覆盖
部署 → 访问 → 故障注入 → Agent 排障 → 修复 → 验证完整链路
6.1 项目结构与实验目标
example-voting-app 的核心组件:
| 组件 | 技术栈 | 说明 |
|---|---|---|
vote | Python | 前端投票页面,NodePort 31000 |
result | Node.js | 结果展示页面,NodePort 31001 |
worker | .NET | 消费 Redis 消息并写入 Postgres |
redis | Redis | 消息缓存 |
db | Postgres | 持久化存储 |
这一章要演示的,不只是"把故障修好",而是两个工具在同一个 Harness 基础上,如何通过各自的 Skills 机制稳定驱动排障:
- 搭建公共 Harness 基础(两个工具共用)
- 场景 A:用 Codex + Skills 完成两个典型故障的排查与修复
- 场景 B:用 Claude Code + Skills 完成同样的排查与修复
- 对比两种工具的 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 只需要维护一套。
6.4.1 AGENTS.md
# 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,真正纳入工程生产体系。
它的关键不在于神奇提示词,而在于五件事:
- 给 Agent 正确上下文
- 给 Agent 清晰边界
- 给 Agent 可执行工具
- 给 Agent 强验证闭环
- 给 Agent 长期治理机制(Skills 是其中最可复用的部分)
对一线工程师来说,Harness 最现实的意义不是"完全取代开发",而是:
- 把重复劳动自动化
- 把验证链路前移
- 把经验沉淀成 Skills 和规则
- 把 Agent 从一次性帮手,变成可持续协作的工程成员
未来真正拉开差距的,大概率不是谁"会不会用 Agent",而是谁能把自己的工程系统改造成 Agent 友好型系统。
而这件事,本质上就是 Harness Engineering。
9. 参考资料
- Example Voting App: https://github.com/dockersamples/example-voting-app
- OpenAI Harness Engineering: https://openai.com/index/harness-engineering/
- Anthropic Effective Harnesses: https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents
- Mitchell Hashimoto: https://mitchellh.com/writing/my-ai-adoption-journey
- Martin Fowler / Thoughtworks: https://martinfowler.com/articles/exploring-gen-ai/harness-engineering.html
- Everything Claude Code: https://github.com/affaan-m/everything-claude-code/blob/main/README.zh-CN.md