前五篇我们把概念体系搭完了：什么是 harness（第 1 篇）、循环本体（第 2 篇）、上下文四策略（第 3 篇）、工具与权限（第 4 篇）、长任务多代理 (第 5 篇)。骨架已经立住，但真正决定一个团队 agent 好不好用的，是这些骨架被怎么"喂养"和"修剪"的——CLAUDE.md 写多长、hooks 加在哪一拍、MCP 装几个、skill 什么时候才载入、配置怎么追溯到一次具体的失败。

这一篇不再是"讲清楚一种机制是什么"，而是"工程师 day-to-day 怎么用 harness 把活干完不出事"。我们把它整理成 5 大配置面 + 12 条实战经验 + 4 个真实案例 + 1 份可抄的 settings.json，目的是：你读完之后，能直接走到自己的 repo，敲下第一行 .claude/CLAUDE.md。

1. 引子：Skill Issue 重构思维

2026 年初，HumanLayer 写过一篇 Skill Issue: Harness Engineering for Coding Agents，一句话点透了行业里所有"等下一个模型"派的尴尬：

It’s not a model problem. It’s a configuration problem.
这不是模型的问题，是配置的问题。

文章里有个被反复引用的对比数字：Opus 4.6 在 Claude Code 自带的 harness 里，Terminal Bench 2.0 排第 33；同样的模型放进另一个 harness（且 post-training 阶段没用过那个 harness），排第 5。28 名的差距，模型一行权重都没动——差的全在外壳。

这个数字之所以有冲击力，是因为它跟我们的下意识反着。我们习惯把"agent 干不成事"归咎于模型——“GPT-5.x 还不够强”、“等 Opus 5 出来就好了”。Skill Issue 这个词是一种工程文化的复位：当 agent 失败时，先怀疑你的 harness，再怀疑模型。这跟操作系统社区一句老话很像——“先怪自己的代码，再怪编译器，最后才怪 CPU”。

Sebastian Raschka 在 Components of a Coding Agent 里给了一个更冷静的版本：

A lot of apparent “model quality” is really context quality.

也就是：很多被你感知为"模型不行"的问题，本质是上下文里没塞对东西。而上下文里塞什么、什么时候塞、怎么压、怎么收回——这些全部归 harness 管。

理解到这一层，“配置” (configuration) 就不再是个让人觉得无聊的词。它是 2026 年 AI 工程师跟模型打交道的主要工作面。本篇剩下的所有内容，都围绕一句话展开：Harness engineering 不是写完 prompt 就完事，而是持续 ship 配置 + 持续根据失败迭代。

2. 五大配置面

我们先建立坐标系。Claude Code 暴露给工程师的"配置面" (configuration surface) 总共五张牌：CLAUDE.md / 自定义命令 / hooks / MCP / skills。每一张牌有它独特的物理性质——什么时候被加载、消不消耗上下文、能不能短路 loop、改起来多重——这决定了你应该把"什么样的规则"放到"哪一张牌"上。

配置面	加载时机	是否进 prompt（耗 token）	能否短路循环	推荐"装多少"	典型用途
CLAUDE.md / AGENTS.md	每个 turn 都重读	是（核心位置）	否	< 60 行	项目硬约束、风格、禁忌
Custom slash commands	用户主动 /cmd 触发	仅触发时进 prompt	否	8–15 个	可重放的工作流（写测试、review）
Hooks	生命周期事件触发，主进程跑	否（不进 prompt）	是	3–6 个	确定性强制（lint、format、安全检查）
MCP servers	启动时连接	工具 schema 进 prompt	否	5–6 个上限	外部系统（数据库、邮箱、企业 API）
Skills	仅声明时只载元数据，调用时才载完整	渐进式（progressive disclosure）	否	不限，按需	大段领域知识、专门工作流

下面逐个拆。

2.1 CLAUDE.md / AGENTS.md：项目宪法

CLAUDE.md（Anthropic 系叫法）和 AGENTS.md（OpenAI / Codex 系叫法）是同一类东西：每个 turn 都被注入到 prompt 里、agent 不可见地总在读的项目说明书。它一共有三层级：

• 项目级 (<repo-root>/CLAUDE.md)：跟着 repo 走，团队共享。
• 用户级 (~/.claude/CLAUDE.md)：跟着账号走，跨项目个人偏好。
• 目录级 (<sub-dir>/CLAUDE.md)：仅这个子目录生效，常用于 monorepo 子模块。

更具体的优先级是"越具体越后写、越靠近 prompt 末尾、权重越高"。所以个人偏好放用户级，项目硬约束放项目级，子模块特例放目录级。

写 CLAUDE.md 有三条铁律：

1. 每条规则都能追溯到一次具体失败——这条叫"Ratchet 原则"（详见 §3.1）。“function names should be camelCase” 写下来之前，得回答"上次模型是不是真的写出了 do_thing()"。
2. 总长度推荐 < 60 行。Addy Osmani 在 Agent Harness Engineering 里把它比作"飞行员的 checklist，不是 style guide"。CLAUDE.md 每个 turn 都重读，超过 60 行会显著挤压实际任务的上下文预算。
3. 机器自动生成的 CLAUDE.md，不如人手写的。/init 工具一拉，能给你拉出 600 行 boilerplate（项目说明、tech stack、目录树……）——这些信息模型其实可以从 ls + package.json 自己推出来，把它写进每 turn 都加载的 CLAUDE.md 是浪费弹药。

下面是一段我推荐的极简模板（< 50 行），重点是禁忌 + 本仓库特有的"坑"：

# Project: <name>

## Hard rules (do NOT violate)
- Never run `git push --force` to main/master.
- Never edit files under `vendor/` or `third_party/`.
- Never commit files containing API keys (regex: /sk-[A-Za-z0-9]{32}/).

## Style
- Python: black, ruff (config in pyproject.toml). 不要在 import 区上面加注释。
- Tests live in `tests/`，文件名 `test_*.py`，**不要**用 `unittest.TestCase`，用 pytest 风格。

## Known footguns(具体失败追溯)
- 2026-03-12: 模型把 secrets.py 的 `DEBUG=True` 改成 False 导致生产挂了。
  → 不要碰 `config/secrets.py`。
- 2026-03-25: 模型为节省 token 把 docstring 删了。
  → 保留所有 docstring，**只增不删**。

## Verification
- 改完代码必须跑 `make test-fast`（< 10s）。
- 提交前自动运行 `make lint`（hook 已配，无需手动）。

这种写法的精髓是让每一条规则带"伤疤"——你能在 commit history 里找到它对应的那次事故。这才是真正的 Ratchet：每加一条都让系统更不可逆地变好。

2.2 Custom slash commands：可重放的工作流

Claude Code 把 .claude/commands/*.md 全部当作可调用的"自定义斜杠命令"。每个 markdown 文件就是一段会被注入成"当前任务指令"的 prompt 模板，文件里可以用 $ARGUMENTS 占位符吃用户参数。

它解决的是"重复性工作流"问题——你团队里凡是出现过两次的"先做 X 再做 Y 再写报告 Z"，都应该被命令化。常见的几个：

• /write-tests <path>：读文件 → 识别公共 API → 写 pytest → 跑测试 → 修失败。
• /review <pr-id>：拉 PR diff → 跑 linter → 找潜在 bug → 写 review。
• /deploy <env>：跑 smoke 测试 → 标记 release → 触发部署。
• /debug <issue>：复现 → 加日志 → 隔离最小复现 → 回报。

举个 /write-tests 文件的最小内容：

# /write-tests

Write comprehensive tests for the file or module specified in $ARGUMENTS.

Steps:
1. Read the source file and understand its public API.
2. Identify functions / classes / methods that need testing.
3. Write pytest tests covering happy path, edge cases, error cases.
4. Save to mirror path under `tests/`.
5. Run tests and fix failures until they pass.
6. Run `make lint` and report results.

注意三个要点：

• 它只在你 /write-tests 时才进 prompt，不像 CLAUDE.md 每 turn 都吃 token。
• 它是可版本化的——commit 进 repo，团队所有人共享同一套 workflow。
• 它把"步骤"显式写出来，避免每次靠模型自己琢磨流程。这是 §3.7 "把流程交给配置而不是模型"的最小落地。

2.3 Hooks：harness 唯一的"确定性"回路

Hooks 是 Claude Code 配置面里性质最特殊的一张牌——它不在模型的上下文里。理解这一点是关键。

Anthropic 提供的 hook 触发点至少包括：

• UserPromptSubmit：用户回车之后、模型看到之前。可以偷偷往 prompt 注入信息。
• PreToolUse：模型决定调工具之后、harness 真去执行之前。可以拒绝、改写参数、要求二次确认。
• PostToolUse：工具执行完之后、结果回喂给模型之前。可以做 lint、auto-format、把无关大输出过滤掉。
• Stop：模型说"我做完了"之后，harness 决定是否真的停。可以强制要求"必须先跑完测试"。
• PreCompact：上下文要压缩之前。可以把关键信息抢救到 scratchpad。
• SubagentStart / SubagentStop：子代理生命周期。

Hooks 的杀手锏属性 是它不消耗上下文——在主进程跑 shell 命令，把 stderr / stdout 通过 stdin 注入回 agent，但 hook 本身的代码、定义、运行过程对模型不可见。

这意味着：所有"每次都该做、且模型不需要知道是怎么做的"事情，都该用 hook 实现。比如：

• 每次 Edit / Write 之后自动 ruff --fix——模型只看到一个干净的最终文件。
• 每次 commit 之前自动跑核心测试，失败就 abort——模型看到 abort 信息，自己改。
• 每次 Bash 调用前扫一下命令是不是黑名单——直接 short-circuit。

Hooks 也是 harness 里唯一能短路 loop 的机制——它能 exit 1 或 exit 2 把模型即将做的动作直接掐掉。这是确定性的最后一道防线。

2.4 MCP servers：通往外部世界的桥，但要克制

MCP（Model Context Protocol）server 把外部系统暴露成"工具"——数据库、GitHub、Notion、邮箱、内部 API 都可以挂上去。安装一行 npx @modelcontextprotocol/server-postgres，agent 立刻就能查 SQL。

诱惑很大。但代价也很真实：MCP server 注册的每个工具都要把 schema 注入 prompt。装 5 个 server，每个暴露 10 个工具，就是 50 个工具的 schema——动辄几千 token，每个 turn 都吃。Vercel 那个"砍 80% 工具反而更准更快"的案例（详见 §4.2）就是从这里来的。

实战上有三个建议：

1. 上限 5–6 个 server。Claude Code 文档自己也是这个建议——再多就开始压垮 prompt。
2. 不在用的关掉。你这个项目用不到 PostgreSQL 但全局装了 server？挪到对应 repo 的 .claude/settings.json 里启用，别放用户全局。
3. CLI 替代往往更轻——gh、docker、psql、kubectl 这些 CLI 模型早在训练里见过几百万次，调它们比挂一个 MCP server 省得多。这条单独抽出来作为第 8 条经验讲（§3.8）。

2.5 Skills：渐进式披露的胜利

Skills 是 Anthropic 在 Claude Code 里铺的最新一层配置面，核心创新是 progressive disclosure（渐进式披露）：

• 声明阶段：harness 启动时，只把 skill 的"name + 一行描述 + 触发条件"注入 prompt——成本极低，几十 token 一个。
• 触发阶段：模型判断当前任务匹配某 skill，才把这个 skill 的完整 markdown 内容（可能是几千 token 的工作流 + 知识 + 例子）载入。
• 退出阶段：skill 用完，相关内容下一轮就被压缩掉。

对比 monolithic 系统提示词的差距非常大——后者把 N 个 skill 的所有内容一次性塞进 system prompt，每个 turn 都带着；前者只在用得到时才装弹。在我自己的项目里，把 7 个 skill 改成 progressive disclosure 之后，平均每 turn 的 prompt token 数从 18K 降到 4K，而能力一点没减。

skills 的另一个用途是把"领域知识"塞进 harness 但不塞进上下文——比如"我们公司内部财务数据库的字段对照表"、“这个 repo 的编译流程文档 1500 行”，全部以 skill 形式存在 .claude/skills/，需要时才被模型主动调用。

3. 12 条实战经验

这一节是本篇的核心。每一条都是社区在 2025–2026 年踩过坑总结出来的，按"重要性 / 普遍性"排序。

#	一句话	适用层
1	Ratchet 原则：每条规则都追溯到一次失败	CLAUDE.md
2	Start minimal，遇到失败再加	全部
3	不用的工具/skill/MCP 关掉	MCP / skills
4	CLAUDE.md 别用机器自动生成	CLAUDE.md
5	“What NOT to do” 比 “do” 更值钱	CLAUDE.md
6	从失败迭代，不追求一次完美	工作方法
7	A/B test 你的 config	工作方法
8	CLI 比 MCP 轻	MCP
9	确定性回路交给 hook	hooks
10	别每次都跑全套测试	hooks
11	把 battle-tested config 进 repo	工作方法
12	harness 跟模型一起进化，主动 prune	工作方法

3.1 Ratchet 原则：每条规则都能追溯到一次具体失败

Addy Osmani 在 Agent Harness Engineering 里给这条命名：“Every line in a good AGENTS.md should be traceable back to a specific thing that went wrong.”

为什么这条排第 1？因为它是反"理论最佳实践"病的疫苗。一个新人接手 agent 项目，第一反应往往是去查"业界最佳实践"——“应该写什么？” 然后把 ChatGPT 给的 30 条建议照单抄进 CLAUDE.md。

但这就是 config bloat 的开端。每条没经过失败验证的规则，都是占着 prompt 位置不干活的"理论税"。Ratchet 原则是说：只有当你看到模型真的犯了某个错，你才把"防止它再犯"的那一行写进 CLAUDE.md——加进去之后就别撤，让系统单调地、不可逆地变好。这就是 ratchet（棘轮）这个隐喻的来源。

操作上：每次 agent 出事故，做事故复盘的最后一问是"这条能写进 CLAUDE.md 吗？" 能就写，不能就别写。

3.2 Start minimal，遇到失败再加

跟第 1 条同根。HumanLayer 文章里 Viv Trivedy 说得很直白：“good agent building is an exercise in iteration. You can’t do iterations if you don’t have a v0.1.”

很多人想一上来就把 5 大配置面全部填满——CLAUDE.md 写 200 行、装 8 个 MCP server、写 20 个自定义命令、配置 6 个 hook、安装 12 个 skill——然后发现 agent 慢得要命、动不动就报错，根本不知道是哪个配置在打架。

更好的做法：只写 CLAUDE.md（< 30 行），跑两周。每次失败问自己"这条能不能让我加 1 行规则解决？" 加不动了再开第二张牌（hooks）。再加不动开第三张（custom commands）。MCP 和 skills 留到最后——它们成本最高、收益最不可预测。

3.3 每个工具的 schema 都进 prompt：关掉不用的就是免费提速

这是 Vercel 80% 砍工具的物理基础。每注册一个工具，它的 name + description + 参数 schema 就永久占据 prompt 头部——不管你这次任务用不用得到。装 50 个工具，每个 100 token，光工具 schema 就吃 5K。然后你的项目实际上每次只用到其中 5 个。

更糟的是，工具一多模型就开始"挑花眼"——HumanLayer 文章直接列出现象：“Too many tools flood context windows faster, pushing agents into performance degradation zones.” 模型在 50 个工具里挑对一个的概率，比在 5 个里挑对低得多。

操作上：定期审计工具表。打开 .claude/settings.json，问自己每一个 MCP server / skill “上次用这个是多久以前？” 一个月没用过的，删掉。这是免费的性能提升。

3.4 CLAUDE.md 别用机器自动生成

ETH Zurich 2026 年初有个 agent 文件研究 被 HumanLayer 引用：他们扫了大量开源 repo 的 AGENTS.md 文件，发现绝大多数自动生成的文件对模型表现几乎没贡献——重复 README 已经写过的内容、罗列模型自己能从 ls 推出来的目录树、写一些"the project is a web application"这种废话。

人手写的 60 行 > 机器生成的 600 行。原因很简单：CLAUDE.md 的核心价值是 “模型不可能从 repo 推断出来的暗知识”——团队约定、历史踩坑、组织偏好——这些只能人写。机器只会重复明摆着的东西。

操作上：用 /init 这类工具时，把生成结果当成草稿——删 80%、留 20%、再加一节"踩坑追溯"，那才是好 CLAUDE.md。

3.5 “What NOT to do” 比 “What to do” 更值钱

人类语言里负面命令信号比正面命令更强——“不要碰 X” 比 “请使用 Y” 更不容易被模型转译错。模型已经知道一万种"怎么做"的可能，你写正面规范它会觉得是"建议"；你写禁忌它知道这是 hard constraint。

aicodeinvest 的实施指南 直接把"Anti-patterns / What NOT to do" 列为 CLAUDE.md 必须有的一节。我自己的经验是这一节往往是 CLAUDE.md 最值钱的部分。比起"使用 type hints"，“不要在 legacy/ 目录下加 type hints” 在实战中救我的次数多得多。

3.6 从失败迭代，而不是追求一次完美

Manus 6 个月重写 5 次（详见 §4.1）这事的意义不只在"他们改了 5 次"，而在"他们没等想清楚再写"。harness engineering 像 SRE 而不像建筑学——你需要一个 v0.1 跑起来，然后看它怎么坏、修哪里、再 ship——不要试图把 v1.0 一次性 ship 完美。

现实中的做法：

• 每周 review 一次最近 N 次失败任务的 transcript。
• 给每次失败打标签——“模型遗忘上下文”、“工具用错”、“权限误判”……
• 高频标签 → 下一周的配置改进清单。

这个机制比"读完业界最佳实践"靠谱十倍——你的 harness 应该是你自己 repo 失败模式的形状，不是某篇博客的形状。

3.7 A/B test 你的 config

避免假优化最直接的办法。每次想加一条 CLAUDE.md 规则、加一个 hook、装一个 MCP server，用真实任务做对照：在 N 个有代表性的 task 上跑两次，一次 with config 一次 without，看完成率 / 平均 turn 数 / 平均 token 数。

要点：用你团队真实的任务而不是公开 benchmark。Terminal Bench 和你的 codebase 长得不像，你 A/B 出来的结论也不像。Manus / Vercel / LangChain 这几家共同的工程实践就是有自己的"内部 benchmark"——一组反复跑的代表性任务，每次架构改动都让它们重跑一遍。

3.8 CLI 比 MCP 轻

模型在 git / docker / kubectl / gh / curl / psql 这些常用 CLI 上已经训练过——你不需要给它 schema，它就知道 git log --oneline -10 是什么意思。挂一个 MCP server 来"暴露 git 操作"反而更重——schema 占 prompt、subprocess 占内存、抽象层过厚反而限制了模型本来的灵活性。

经验法则：当你能用一行 Bash 解决的事，就别建一个 MCP server。MCP 留给三类场景：

1. 必须用 RPC 而非 CLI 才能访问的服务（某些企业 API）；
2. 需要严格 typed 输出 / schema 验证的场景；
3. CLI 命令复杂到模型容易写错（比如多步 OAuth）。

其他全用 Bash + 现成 CLI。这跟 Unix 哲学一脉相承——小工具组合 > 大胖框架。

3.9 Hooks 是确定性回路：把"每次都该做"交给 hook

只要某件事满足"每次工具调用后都该做 且 不需要模型决定怎么做"，就该交给 hook。理由：

• 省上下文：hook 里跑的代码和它的输出过滤逻辑模型都看不见，不占 token。
• 省 turn 数：模型不需要"记得 lint"、“记得 format”、“记得跑测试”——hook 替它跑了。
• 更可靠：hook 是 shell 脚本，确定性 100%；模型记忆是概率事件，会忘。

最常见的 4 个 hook 类别：

1. PostToolUse：Edit / Write 之后跑 ruff --fix / prettier --write，自动修代码格式。
2. PreToolUse：Bash 调用前扫黑名单（rm -rf /、git push --force）。
3. Stop：模型说"完成"之前，强制跑 make test-fast。
4. PreCompact：压缩之前，把关键文件路径 / 当前 TODO 抢救到 scratch.md。

3.10 别每次工具调用都跑全套测试

新手最容易掉的坑：在 PostToolUse hook 里挂上 pytest tests/——结果每次模型保存一个文件，跑 5 分钟测试，5 分钟测试输出全部回喂给模型。一上午下来上下文撑爆了，agent 反复忘记自己要干嘛。

正确的分层：

时机	跑什么	期望耗时
每次 Edit / Write 后	linter（ruff / prettier）	< 1s
make test-fast	单元测试核心子集	< 10s
模型 Stop 前	单元 + 集成	< 1min
Pre-commit hook	单元 + 集成 + lint	< 2min
Pre-push hook / CI	全套（含 e2e）	5–20min

记住一个原则：反馈越频繁，越要快；越慢的反馈，越要稀。HumanLayer 直接说：“verification must be context-efficient—‘swallow the output and only surface errors’ prevents massive test outputs from overwhelming the agent’s focus.” 也就是只把"失败信息"喂给模型，成功就 silent return。

3.11 把 battle-tested config 放进 repo

team agility 来自把"踩过坑的配置"沉淀下来。具体做法：

• .claude/CLAUDE.md：跟 repo 走（项目级）。
• .claude/commands/*.md：跟 repo 走，团队所有人共享自定义命令。
• .claude/hooks/*.sh：跟 repo 走。
• .claude/settings.json：跟 repo 走。

而个人偏好（“我喜欢中文 commit message”）放 ~/.claude/CLAUDE.md 用户级。

这样新人 clone repo 立刻继承团队多年踩坑的成果，不用再自己重新发现一遍。Addy Osmani 把这种现象起了个名 “Harness as a Service” (HaaS)——把 harness 配置从"个人偏好"变成"团队基础设施"。

3.12 harness 跟模型一起进化：主动 prune 老 scaffolding

Anthropic 工程团队多次提到一个观察：“当模型变强，旧 scaffolding 反而成为枷锁”。比如 Opus 4.4 时代你写过这样一段 CLAUDE.md：

重要：在每次写完代码后，请先思考可能的边界情况，再给出最终代码。

到 Opus 4.6 / 4.7 这条规则可能已经过时——模型默认就这么干了，你这句话反而占位置，甚至诱导它写出冗余的 reasoning。

operational 上：每次大版本模型升级，都过一遍 CLAUDE.md / hooks / skills，问每条"这条还需要吗？"——能裁就裁。这跟"Ratchet 原则"看似矛盾（一加不撤），其实是互补的——Ratchet 防止你乱加；模型升级时主动 prune 防止你越加越累。Anthropic 自己内部用的术语是 “context anxiety scaffolding”——很多老规则其实是上一代模型 context anxiety 时代的遗留物，新模型早就不需要了。

4. 真实案例 4 则

理论讲完，看几家把 harness engineering 当真生意做的公司。

4.1 Manus：6 个月重写 5 次，每次"删"比"加"多

Manus 是 2025 年下半年最早把 harness 当核心 IP 的团队之一。Aakash Gupta 的 Medium 长文 2025 Was Agents. 2026 Is Agent Harnesses. 里给了一个被广泛引用的事实：

Manus rewrote their harness five times in six months. Same models. Five architectures.

关键不在"重写 5 次"，而在 5 次重写里 4 次都是删比加多——更短的系统提示词、更少的工具、更紧的 turn 上限、更稀的检索调用。每次删除都让 agent 更稳。这印证了第 3 条 (砍工具是免费提速) 和第 6 条 (从失败迭代)。

4.2 Vercel：删 80% 工具，成功率反而上升

Vercel 在 2026 年初公开他们 v0 agent 的一次大改：把可用工具从 ~50 个砍到 10 个。Aakash Gupta 引用的结果是：

Removed 80% of their agent’s tools and got better results, including faster responses and higher task success rates.

这件事的反直觉点在于"少 = 多"。直觉上工具越多越能干活，实际上工具越多模型挑得越乱。当任务简单到 10 个工具就够时，多出来的 40 个工具的 schema 一直占着 prompt 头部，反而拉低了任务相关上下文的密度。

砍掉之后的具体收益：响应更快（少 token）、token 成本下降、success rate 更高、工具误用更少。这就是为什么"hygiene work"是 harness engineer 的日常——它不是性能优化的边角料，是主菜。

4.3 LangChain：Deep Research 一年 4 次架构重构

LangChain 的 Deep Research 是开源里被研究得最透的多 agent 工作流之一。它一年内重构 4 次架构，每次重构关注点不在"换更强的模型"，而在三件事：workflow 结构、上下文管理、子任务协调。

它印证了一个判断：当模型质量进入饱和期，工程优势全部来自于 harness。你不能再靠"等下一个模型"提升 30%——你必须把循环、压缩、子代理这些 harness 元素调到极致。LangChain 公开的 retrospective 里，他们把 4 次重构对应的胜率提升各 ~10–15%，累计 1.5x 不靠模型升级。

4.4 OpenAI / Stripe / GitHub：harness engineering 是持续工程

到了 2026 年，harness engineering 已经不只是 Anthropic / OpenAI 这种 model lab 的内部活，而是大型工程组织的日常实践：

• OpenAI 的 Codex 团队公开过一种叫 layered architectural enforcement 的做法——把"这个 PR 是否符合 X 架构原则"写成可调用的 evaluator agent，每次 PR 都跑。失败模式直接打回来当下一轮 prompt。
• Stripe 内部分享过 garbage collection drift detection——每周扫一遍 agent 生成的代码，检查"是否引入了与现有代码风格不一致的模式"，把 drift 写成报告反向喂回给 CLAUDE.md。
• GitHub Copilot 团队推动 pre-push feedback loop——每次 git push 之前 agent 必须先看到 CI 失败列表（mock 一份），相当于在本地就把"这次推上去是不是要红"先回放一遍。

这些 case 共同指向一个判断：harness engineering 是持续工程，不是静态配置——你不是写一份 CLAUDE.md 就能一劳永逸，你需要一个团队（或一个负责人）持续做这件事，跟 SRE / 平台团队一样有专人值守。

5. 一份可抄的 settings.json 示例

下面是一个最小可工作的 .claude/settings.json，可直接 copy 到任何 Python repo 启用。三个核心要点：

1. PostToolUse 的 ruff fix — 写完自动改格式。
2. PreToolUse 的 Bash 黑名单 — 拦截危险命令。
3. Stop 时跑 fast 测试 — 模型说"完成"前必须验证。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "ruff check --fix \"$CLAUDE_FILE_PATH\" 2>&1 | tail -20 || true"
      },
      {
        "matcher": "Write|Edit",
        "command": "ruff format \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "scripts/bash-guard.sh \"$CLAUDE_TOOL_INPUT\""
      }
    ],
    "Stop": [
      {
        "command": "make test-fast 2>&1 | tail -30"
      }
    ],
    "PreCompact": [
      {
        "command": "echo \"--- compact at $(date) ---\" >> .claude/scratch.md"
      }
    ]
  },
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${env:GITHUB_TOKEN}" }
    }
  },
  "permissions": {
    "allow": ["Read", "Glob", "Grep"],
    "deny": ["Bash(rm -rf:*)", "Bash(git push --force:*)"]
  }
}

scripts/bash-guard.sh 是个 10 行的 shell 脚本，扫输入命令是不是命中黑名单，命中就 exit 2 让 hook 短路 agent。这种"配置 + 脚本"的组合是 harness engineering 最常用的乐高块——一切复杂逻辑都装在脚本里，settings.json 保持声明式干净。

6. Prompt engineering vs Harness engineering：差一个数量级

最后回到一个常见的混淆。

Prompt engineering 关心的是单次模型互动——这一句怎么说、举几个例子、用什么口吻、CoT 还是直答。它是 LLM 工程的最小颗粒，重要但已经不是瓶颈。

Harness engineering 关心的是从用户意图到产出落地一整条链路上所有可工程化的部分——什么时候调模型、模型可以调什么工具、工具怎么权限管控、上下文什么时候压缩、压缩怎么不丢东西、子代理什么时候开 fork、agent 失败了怎么 resume、配置怎么版本化、团队怎么共享配置——它是包含 prompt engineering 作为子集的更大游戏。

只盯 prompt 而忽视 harness，等于把 90% 的工程优化空间留在桌上——因为 prompt 在你 harness 调好之后只是一个变量；而 harness 调不好的话，无论 prompt 怎么写都救不回来。

prompt eng. 是把"这一句怎么说"调到极致；
harness eng. 是设计能可持续 ship 的 agent 工程系统。
前者是工艺，后者是工程。

关键 takeaway

• “It’s not a model problem. It’s a configuration problem”——同一个模型在不同 harness 里能差 28 名，先怀疑配置再怀疑模型。
• 5 大配置面：CLAUDE.md / 自定义命令 / hooks / MCP / skills。各有物理性质，各有适配场景。Hooks 不消耗上下文是它的杀手锏。
• Ratchet 原则 + Start minimal：每条规则都追溯到一次具体失败；先最小，遇到失败再加；机器自动生成 < 人手写。
• "删"比"加"重要：Manus 6 个月 5 次重写、Vercel 砍 80% 工具，主旋律都是裁，不是加。每次模型升级都该 prune 一次老 scaffolding。
• harness engineering 是持续工程——不是写一份 CLAUDE.md 一劳永逸，而是要团队像 SRE 一样持续 ship、A/B、回归。它包含 prompt engineering 作为子集，是 2026 年 AI 工程师的主战场。

下一篇（也是本系列最后一篇）我们抬头看远处——HaaS、自适应 harness、natural-language harness、模型与 harness 共同训练，2026 之后还有什么开放问题。

---

参考资料

• HumanLayer, Skill Issue: Harness Engineering for Coding Agents, 2026.
• Addy Osmani, Agent Harness Engineering, 2026.
• Birgitta Böckeler, Harness Engineering for Coding Agent Users, martinfowler.com, 2026.
• AI Code Invest, Harness Engineering for Claude Code: A Practical Guide, 2026.
• Sebastian Raschka, Components of a Coding Agent, 2026.
• Aakash Gupta, 2025 Was Agents. 2026 Is Agent Harnesses. Here’s Why That Changes Everything, Medium, 2026.
• Avi Chawla, The Anatomy of an Agent Harness, Daily Dose of DS, 2026.
• WaveSpeedAI, Claude Code Agent Harness: Architecture Breakdown, 2026.
• Anthropic, Effective Harnesses for Long-Running Agents, 2025.