Harness Engineering 快速入门指南+配置分享（附研究报告）

如果你最近在 AI 编程圈里反复看到 Harness Engineering，这个词并不是突然空降出来的。2026 年 2 月，OpenAI 先公开复盘了它们怎样在 agent-first 开发里使用 harness；3 月，Anthropic 紧接着把长程任务里的 handoff、reset 和评估外置写成工程经验；4 月初，Martin Fowler 又把这套做法整理成了更容易传播的工程框架。

这波讨论之所以值得认真看，不是因为圈内又多了一个新术语，而是因为模型能力往上走之后，瓶颈已经明显变了。今天的大模型当然能写代码，但真实项目里的问题从来不是“它能不能写出几段代码”，而是“它能不能在多轮任务、长上下文、多人协作和持续迭代里稳定做对事”。

也正因为这样，越来越多团队开始把注意力从“怎么把提示词写得更像咒语”转向“怎么把模型工作的环境改造成一个系统”。换句话说，真正拉开差距的，不再只是模型本身，而是你的仓库里有没有计划工件、有没有统一验证入口、有没有清晰边界、有没有能接力的 handoff。

这就是 Harness Engineering 现在变热的根本原因。它不是“更会和模型聊天”，而是把计划、约束、验证、交接、回滚、恢复这些原本散落在聊天窗口里的东西，搬进仓库，变成可执行、可复检、可接力的系统。

所以这篇文章不会停留在“概念介绍”。接下来我会直接把一套可以照着搭的完整方案拆开讲：仓库怎么摆、AGENTS.md 怎么写、ARCHITECTURE.md 如何落边界、ExecPlan 和 Handoff 怎么做、verify.sh 怎么统一验证、新项目和存量项目各自怎么接管、什么时候再考虑 oh-my-codex 或 OpenHarness。目标很明确：让每个读者看完后，都能尽快把自己的 Harness Engineering 配起来。

一、先把核心想明白：Harness Engineering 到底在解决什么

很多人刚开始用 Codex、Claude Code 或别的 AI 编程工具时，最习惯的做法是“直接开聊”：描述需求，等模型写代码，出错了再补一句，跑偏了再改说法。

这种方式在小脚本、小改动、单文件修补里问题不大。一旦任务变成跨模块重构、长流程接管、多人协作或者会跨多个会话完成，问题就会一下子暴露出来：

• 模型记不住真正重要的上下文。
• 验证方式不统一，做没做完全靠口头判断。
• 长期任务缺少交接物，第二次打开时又得重来。
• 架构边界、命名规范、日志要求写在文档里，但没人真执行。

Harness Engineering 的重点，就是把这些“原本靠人盯着”的东西，升级成系统的一部分。你可以把它理解成：不再只训练模型回答问题，而是给模型搭一个真正能长期工作的工作台。

二、先别急着上外部工具，先把仓库变成系统记录

很多人一聊到 Harness Engineering，就马上想到多代理编排、工作流层、可恢复 session、权限系统。这些当然有价值，但对大多数开发者来说，第一步其实更朴素：

先让仓库本身能承载任务状态。

也就是把“项目怎么跑、怎么验证、现在做到哪一步、哪些目录不能乱动、下一步该做什么”这些信息，从聊天记录和脑子里搬出来，落进版本库。只要这一步没做，再强的模型、再花的工具链，最后也会变成新的混乱来源。

三、最小可用的仓库骨架，建议直接照着建

repo-root/
  AGENTS.md
  ARCHITECTURE.md
  PLANS.md
  docs/
    index.md
    exec-plans/
      active/
      completed/
    runbooks/
      verify.md
      release.md
  scripts/
    verify.sh
    doctor.sh
  .github/workflows/
    verify.yml

这套结构最重要的不是“看起来完整”，而是职责非常清楚：

• AGENTS.md：地图，告诉模型先读哪里、怎么做、什么叫完成。
• ARCHITECTURE.md：边界，告诉模型哪些依赖方向不能乱、哪些不变量不能破。
• PLANS.md / docs/exec-plans：计划，承接复杂任务和长程状态。
• docs/runbooks：运行说明，告诉模型和人怎么启动、怎么验证、怎么回滚。
• scripts/verify.sh：统一验证入口，把完成定义成同一个动作。

很多团队的问题并不是缺工具，而是这五样最基础的东西没有形成系统。

四、AGENTS.md 的正确写法：地图，不是百科全书

AGENTS.md 最大的坑，就是总想一口气写成“万能手册”。最后文档越堆越长，谁都不爱看，过几天还会过时。

真正有用的 AGENTS.md，不是把所有细节都塞进去，而是只做三件事：告诉模型先读哪、按什么流程做、什么情况算完成。

下面这份模板，已经足够作为通用起点：

# AGENTS.md

## 目标
本仓库采用 harness engineering 方式工作：把约束、计划、验证与交接写进仓库工件，让 Codex 在没有外部上下文的情况下也能稳定推进任务。

## 先读什么
- 架构总览：./ARCHITECTURE.md
- 计划规范：./PLANS.md
- 文档索引：./docs/index.md
- 执行计划：./docs/exec-plans/active/
- Runbook：./docs/runbooks/

## 工作流约定（PBV）
- Planner：先产出或更新 ExecPlan，把验收标准写清楚
- Builder：严格按已批准的 Plan 修改代码
- Verifier：独立运行 verify 流水线并记录结果

## 什么情况下必须写 ExecPlan
- 需要跨多个文件或模块修改
- 需要迁移、重构、引入新依赖
- 影响安全、权限、支付、发布、数据模型
- 预计超过 30 分钟，或会跨多次会话完成

## 一键验证
- 本地：./scripts/verify.sh
- CI：同样调用 verify.sh
- verify 不绿，不允许标记完成

## 受保护路径
- vendor/**, third_party/**, generated/**
- infra/prod/**, .github/workflows/**
- secrets/**, *.key, *.pem, .env*

## 输出与交接
- 每次停下前都要更新 Progress / Decision Log
- 每个长任务都要留下 Handoff
- 记录：已做、未做、如何复现、如何验证、风险与下一步

这份模板真正有价值的地方，不是写得多漂亮，而是它能让模型一进仓库就知道从哪开始、怎么推进、什么不能碰。

五、ARCHITECTURE.md 要写什么：别写理想状态，只写真实边界

很多团队的架构文档不是没有，而是没法用。因为它们太像 PPT，太像愿景，而不是能拿来判断“这次改动有没有越界”的实际规则。

真正有用的 ARCHITECTURE.md，至少应该包含：

• 核心业务域和关键入口。
• 分层与依赖方向。
• 关键不变量。
• 怎么验证架构没被破坏。

一个能直接改的模板如下：

# ARCHITECTURE.md

## 总览
- 核心业务域：
  - domain-a: 负责...
  - domain-b: 负责...
- 关键入口：
  - API: 
  - Web/UI: 
  - CLI/Jobs: 

## 分层与依赖方向
建议层次：
- types/ → config/ → repo/ → service/ → runtime/ → ui/

规则：
- 依赖只能向前
- 横切关注点必须走统一入口
- 任何跨域调用都必须经过显式边界

## 关键不变量
- 禁止裸 console.log / print
- 类型与 schema 命名必须统一
- 单文件默认不超过 500 行
- 敏感数据不得写日志
- 外部 IO 必须做校验与限流

## 如何验证架构没有被破坏
- 结构测试命令：make structural-test
- 失败修复指引：见 docs/runbooks/verify.md

## 变更策略
- 小改动：轻量 plan + verify
- 大改动：ExecPlan + milestone + 回滚路径

这里最重要的一点是：边界要能被验证，不变量要能被执行。 如果它只是写在文档里，最后还是会腐烂。真正稳定的做法，是把这些规则慢慢升级成结构测试、lint 或 CI。

六、复杂任务必须工件化：ExecPlan 是长任务的主心骨

Harness Engineering 和普通“AI 辅助写代码”最本质的区别之一，就是对计划的态度不同。前者不会把计划只停留在聊天里，而是把计划当成正式工件。

最简单的判断标准就是：满足下面任意一条，就必须写 ExecPlan：

• 需要跨多个文件或模块改动。
• 涉及迁移、重构、引入新依赖。
• 影响安全、权限、支付、发布、数据模型。
• 预计会超过 30 分钟，或者会跨多个会话完成。

ExecPlan 不需要写成论文，但它必须满足一个要求：换一个全新会话，甚至换一个人，只靠这份文件也能继续推进。

下面这份模板可以直接用：

# <短标题>

## Purpose / Big Picture
说明目标、完成后用户能感知到什么变化。

## Context and Orientation
- 相关模块/文件
- 当前痛点
- 关键术语
- 明确不做什么

## Scope
- In scope:
- Out of scope:

## Constraints & Policies
- 性能/可靠性要求
- 安全/权限约束
- 受保护路径
- 兼容性要求

## Plan of Work
按顺序写清每一步会改哪些文件、为什么改、怎么验证。

## Concrete Steps
把动作拆成可执行步骤，每个 milestone 都能独立验证。

## Validation and Acceptance
- 启动命令
- 验证命令
- 新增/更新哪些测试
- 手测步骤

## Idempotence and Recovery
- 哪些步骤可重复执行
- 出错怎么恢复
- 如何回滚

## Progress
- [ ] 时间戳 + 当前进度

## Surprises & Discoveries
记录意外发现、失败证据、边界问题。

## Decision Log
记录为什么改计划、为什么做这个取舍。

## Outcomes & Retrospective
总结完成了什么，还欠什么，下一次该补什么 harness。

只要这份东西写到位，长任务的稳定性就会明显提升。

七、Handoff 才是长任务能不能接上的关键

很多任务不是做不完，而是做着做着断掉，然后第二次打开时已经没人能快速接上。真正缺的，不是更强的模型，而是更好的交接物。

下面这份 Handoff 模板，已经足够应付大多数项目：

# Handoff: <任务名>

## 当前状态概览
- 目标：一句话说明要解决什么
- 当前进度：完成到哪个 milestone / 哪个 commit
- 是否可安全合并：是 / 否（原因）

## 已完成（带证据）
- 改动点：
- 关键 commit / branch：
- 通过的验证：
  - lint:
  - typecheck:
  - unit:
  - e2e:
  - manual:

## 未完成与下一步
- 命令：
- 文件路径：
- 预期结果 / 验收点：

## 复现与验证 runbook
- 如何启动：
- 如何复现问题：
- 如何验证修复：

## 风险与注意事项
- 可能的回归面：
- 兼容性 / 迁移风险：
- 回滚策略：

## 需要人类判断的问题
- 可选方案：
- 推荐方案与理由：

很多人一开始不重视这个东西，但真正跑过几次长任务后，都会发现它的重要性远远超过“再优化一轮提示词”。

八、verify.sh 必须只有一个入口

一堆团队明明有 lint、有单测、有构建命令，但最后还是经常出“看起来改好了，实际一跑全崩”的问题。原因不是没验证，而是验证方式太分散。

最省事的办法，就是把“完成”定义成同一个动作。下面这份多栈版 verify.sh 可以直接拿去改：

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

ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
cd "$ROOT"

echo "==> verify: repo=$(basename "$ROOT")  pwd=$ROOT"

run_if() {
  local desc="$1"; shift
  local cmd="$*"
  echo "---- $desc"
  bash -lc "$cmd"
}

if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
  echo "==> git status (short)"
  git status --porcelain || true
fi

if [[ -f package.json ]]; then
  PM=""
  if command -v pnpm >/dev/null 2>&1; then PM="pnpm";
  elif command -v yarn >/dev/null 2>&1; then PM="yarn";
  else PM="npm"; fi

  run_if "node: install (best-effort)" "$PM -s install || true"
  run_if "node: lint" "$PM -s run lint"
  run_if "node: typecheck" "$PM -s run typecheck || $PM -s run tsc -- --noEmit"
  run_if "node: unit" "$PM -s run test || true"
  run_if "node: build" "$PM -s run build"
  run_if "node: e2e (optional)" "$PM -s run test:e2e || true"
fi

if [[ -f pyproject.toml || -f requirements.txt ]]; then
  if command -v uv >/dev/null 2>&1 && [[ -f pyproject.toml ]]; then
    run_if "python: uv sync (best-effort)" "uv sync --extra dev || true"
    run_if "python: ruff" "uv run ruff check . || true"
    run_if "python: pytest" "uv run pytest -q || true"
  else
    run_if "python: ruff (if installed)" "ruff check . || true"
    run_if "python: pytest (if installed)" "pytest -q || true"
  fi
fi

if [[ -f go.mod ]]; then
  run_if "go: test" "go test ./..."
fi

if [[ -f composer.json ]]; then
  run_if "php: composer install (best-effort)" "composer install --no-interaction || true"
  run_if "php: lint (optional)" "composer lint || true"
  run_if "php: unit (optional)" "composer test || true"
fi

echo "==> verify: done"

这份脚本不要求你一步做到完美，它的意义是先把验证入口统一。之后你再慢慢加结构测试、手测 runbook、预发布检查，整套系统才会越来越稳。

九、PBV：先强制角色切换，再考虑多代理

很多人一看到 Planner、Builder、Verifier，就以为非得上多代理编排。其实未必。单代理一样能先跑起来，关键是强制角色切换。

1. Planner 阶段：只允许写计划、补验收、标边界，不许直接改代码。
2. Builder 阶段：只按计划改代码，尽量让改动最小、可验证、可回滚。
3. Verifier 阶段：独立跑 verify，按 runbook 手测，把失败证据写回 Plan 或 Handoff。

这一步跑熟后，再考虑把不同角色拆到不同 worktree、不同 agent。否则多代理只会把混乱并行化。

十、新项目和存量项目，落地节奏不一样

新项目：先搭承载层，再写业务

1. 先把 AGENTS.md、ARCHITECTURE.md、docs/index.md、docs/runbooks/verify.md 建起来。
2. 落地统一验证入口 ./scripts/verify.sh。
3. 用一个最小垂直切片跑通 PBV。
4. 把第一个反复错误升级成规则，而不是写在文档里。

存量项目：先接管状态，再接管功能

1. 补最小地图和 verify 基线，不急着让模型写大功能。
2. 把现有真实模块边界和关键入口写进 ARCHITECTURE.md。
3. 选一个低风险任务，用 ExecPlan 完整跑一次 PBV。
4. 开始要求每个长任务都留下 Handoff。
5. 等状态承载层稳定后，再引入并行 worktree、多代理或更复杂 runtime。

这是很多人最容易走反的地方：以为先上工具再补治理，实际上通常应该反过来。

十一、什么时候再看 oh-my-codex、OpenHarness、claw-code

当你已经把 repo-native harness 配稳之后，外部工具才会真正放大收益。

• oh-my-codex 更适合已经在用 Codex，并且开始需要可恢复状态、hooks、团队 worktree 和长流程编排的人。
• OpenHarness 更适合想把底层 runtime 做得更通用，不想绑定单一模型或渠道的人。
• claw-code 更值得从工程设计角度研究，尤其是权限模式、doctor 检查、容器优先、parity harness 这些 runtime 能力。

简单说：仓库内的 harness 是地基，外部工作流层是放大器。 地基没打稳，放大器只会把混乱放大。

十二、给每个读者的最小执行清单

如果你今天只准备做 5 件事，就做这 5 件：

1. 在仓库根目录建 AGENTS.md。
2. 补一份只写真实边界的 ARCHITECTURE.md。
3. 把本地验证收口成 ./scripts/verify.sh。
4. 给长任务建立 docs/exec-plans/active/。
5. 每次停下前都写一份 Handoff。

只要这五件事做出来，你的 AI 编程就已经不是“全靠上下文运气”的状态了，而是开始进入真正可持续、可交付、可接力的系统模式。

完整深度研究报告下载

如果你想看更完整、更细的原始研究版，包括工具对比、风险矩阵、迁移里程碑、引用来源、指标体系和更完整的方法论，可以直接下载下面这份报告：

下载《Codex 模式下 Harness Engineering 深度研究与落地方法论》

这份文档更接近研究报告本体，适合需要完整参考材料、想系统搭建团队级 Harness 的读者继续深入看。

参考资料

• OpenAI：Harness engineering: leveraging Codex in an agent-first world
• OpenAI Cookbook：Using PLANS.md for multi-hour problem solving
• Anthropic：Harness design for long-running application development
• Anthropic：Effective harnesses for long-running agents
• oh-my-codex
• OpenHarness
• claw-code
• Martin Fowler：Harness engineering for coding agent users