换模型时最贵的不是 Token

你换模型时最贵的不是 Token，是给 AI 办入职。

前两天 X 上有条帖子说得很直白：GPT 额度用完换 Claude，Claude 用不了再换 DeepSeek，每换一次都要重新交代项目背景、技术栈、之前改了什么，「代码还没写几行，光给 AI 办入职手续了」（原帖）。

我在下面回了一段（原文）：

问题不在换模型，而在把聊天历史当成项目状态。可以维护一份独立于模型的交接包：硬约束、目录地图、关键决策、当前 diff 和最近一次通过的测试；换模型只重放这份状态，并要求它先复述计划再动手。这样额度切换才像换执行器，而不是重新入职。

这篇把那段话展开：交接包里放什么、放在哪、怎么写，最后给一份能直接复制的模板。

一、从写 prompt 到搭 Harness

最近 X 上讨论的方向变了：大家不再比谁的 prompt 写得妙，而是比谁给 Agent 搭的「挽具」更稳。

据 X 热点汇总，开发者正在从提示词转向「Harness 工程」：控制 Agent 能看到什么、能用哪些工具、输出怎么检查、会话记忆怎么留存，用来解决忘上下文、原地死循环这类问题；有人分享了给 Claude Code 用的五层结构——记忆文件、Skills、护栏、子 Agent、插件（来源一、来源二）。

这些讨论里各家数字我没逐条核实，这里不引。但方向我认同，而且可以说得更狠一点：

模型是执行器，Harness 才是你的资产。

模型三个月一换代，额度今天有明天没。你攒下来的那份「项目怎么跑、什么不能碰、现在做到哪」，才是跨模型存活的东西。交接包，就是 Harness 里最便宜、最先该搭的那一层。

二、聊天历史不是项目状态

为什么复制聊天记录不行？三个原因：

  • 太长。几十轮对话里，真正有用的是最后定下来的那几条，其余都是试错过程。新模型得自己从垃圾堆里捞结论。
  • 会过期。第 5 轮说「用方案 A」，第 30 轮改成了方案 B，聊天记录里两条都在，新模型不知道信哪个。
  • 没证据。「已经跑通了」是一句话，不是一条能复现的命令。

所以要把状态从对话里抽出来，放进仓库里的文件。我回帖里列的五样，就是最小集合：

  1. 硬约束：技术栈、版本、绝对不能做的事。
  2. 目录地图：哪个目录干什么，入口在哪。
  3. 关键决策：选了什么、没选什么、为什么。
  4. 当前 diff：做到哪了，哪些改动还没提交。
  5. 最近一次通过的测试：具体命令 + 结果，不是一句「测过了」。

再加一条动作规则：新模型先复述计划，再动手。复述错了，说明交接包有缺口，这时候补文件，比让它改错代码便宜得多。

三、放哪：一份事实源，两个入口

Claude Code 和 Codex 读的文件名不一样，别维护两份。

按官方文档：Codex 开工前会读 AGENTS.md，从项目根目录一路读到当前目录，按顺序拼接，项目级指令默认上限 32 KiB（Codex 文档）。Claude Code 读 CLAUDE.md，支持用 @路径 导入其他文件；仓库里已有 AGENTS.md 时，官方建议建一个 CLAUDE.md，第一行写 @AGENTS.md 导入（Claude Code 文档）。

所以结构是：AGENTS.md 当唯一事实源，CLAUDE.md 只做一层转接。

再按变化频率拆开：

  • 稳定的（约束、目录地图、命令、禁止事项）放 AGENTS.md，几周才改一次。
  • 易变的（当前任务、diff、最近测试）放 docs/handoff/STATE.md，每次收工都改。
  • 决策单独放 docs/handoff/DECISIONS.md，只追加不删除。

这样拆有两个好处：AGENTS.md 保持短，不吃 32 KiB 的额度；STATE.md 天天改也不会把稳定规则改乱。

目录长这样：

repo/
├── AGENTS.md              # 唯一事实源：约束、地图、命令、禁止事项、护栏
├── CLAUDE.md              # 只有一行 @AGENTS.md，外加 Claude 专属补充
└── docs/handoff/
    ├── STATE.md           # 当前任务状态，每次收工更新
    └── DECISIONS.md       # 关键决策日志，只追加

CLAUDE.md 全文：

@AGENTS.md
@docs/handoff/STATE.md

## Claude Code 专属
- 动手前先输出计划，等我确认。

Codex 不支持 @ 导入，所以在 AGENTS.md 里写明「开工前先读 docs/handoff/STATE.md」。

四、模板：直接复制

AGENTS.md

# 项目：<名称>

## 开工顺序（任何模型都先做这三步）
1. 读完本文件和 docs/handoff/STATE.md、docs/handoff/DECISIONS.md。
2. 用 5 行以内复述：目标、当前进度、下一步、你打算改哪些文件。
3. 跑一遍「最近一次通过的测试」里的命令，确认基线是绿的，再动手。
   跑不通就停下汇报，不要先修再说。

## 硬约束
- 运行时：<如 Node 22 / Python 3.12>
- 包管理：<如 pnpm，禁止 npm/yarn>
- 代码风格：<lint/format 命令>
- 必须保持兼容：<如 公开 API、数据库 schema>

## 目录地图
- src/<模块A>/   <干什么，入口文件>
- src/<模块B>/   <干什么>
- scripts/       <运维脚本，不要随手改>
- tests/         <测试，和 src 同构>

## 常用命令
- 安装：<命令>
- 单测：<命令>
- 全量检查：<命令>
- 本地启动：<命令>

## 禁止事项
- 不改 <目录/文件>（原因：<一句话>）
- 不做 git push --force、reset --hard、删除分支
- 不新增依赖，除非先说明理由并得到确认
- 不读、不打印、不提交任何密钥、Token、Cookie、.env 内容
- 不发布、不部署、不对外发消息

## 护栏
- 同一条命令连续失败 3 次：停下，汇报现象和已排除的原因。
- 连续 <N> 步没有新的测试通过或新的有效 diff：视为无进展，停下汇报。
- 单次任务预算：<最长时长 / 最大步数>，到点无论进度都收工写 STATE.md。

## 收工规则
- 更新 docs/handoff/STATE.md（覆盖写，保持当前状态）。
- 有新的取舍，追加到 docs/handoff/DECISIONS.md。

docs/handoff/STATE.md

# 当前状态（更新于 <YYYY-MM-DD HH:MM，时区>，by <模型/人>）

## 目标
- 本轮要完成：<一句话>
- 本轮不做：<明确的非目标>

## 工作区
- 分支：<branch>，基线提交：<commit>
- 已推送：是/否
- 未提交改动：<文件列表，或「无」>

## 当前 diff 摘要
- <文件>：<改了什么，为什么>

## 最近一次通过的测试
- 命令：<完整命令>
- 目录：<在哪执行>
- 结果：<通过 x / 失败 y>
- 时间：<YYYY-MM-DD HH:MM>
- 说明：<哪些是模拟，哪些是真实环境>

## 已知失败 / 卡点
- 现象：<报错或行为>
- 已排除：<试过什么>
- 怀疑方向：<下一步查什么>

## 下一步
1. <具体动作>
2. <具体动作>

## 待人决定
- <需要我拍板的问题>

docs/handoff/DECISIONS.md

## <YYYY-MM-DD> <决策标题>
- 选择：<选了什么>
- 放弃：<没选什么>
- 原因：<一两句>
- 推翻条件：<出现什么情况要重新评估>

换模型时的第一句话

你是这个仓库的新执行者。先读 AGENTS.md 和 docs/handoff/ 下的文件。
不要改任何代码。用 5 行以内复述：目标、当前进度、下一步、要改的文件、
你认为交接包里缺了什么。等我确认后再开始。

最后那句「交接包里缺了什么」很关键。新模型看不懂的地方，就是你下次会踩的坑，顺手补进文件。

五、护栏：别让 Agent 自证活着

交接包解决「换人能接上」，护栏解决「一个人别跑飞」。

前几天另一条讨论在讲用看门狗 Agent 盯 Worker 的响应延迟。我回的是（原文）：

看门狗只盯响应延迟还不够：假死也可能是持续有响应、但动作原地重复。我会再加三层护栏——重复动作哈希、无进展计数、硬预算/租约超时；最后 WDOG 自己也要有外部 dead-man switch，不能靠它自证活着。

拆开说：

  • 重复动作哈希：把「工具名 + 参数」做哈希，同一个哈希短时间内反复出现，就是在原地打转。响应再快也没用。
  • 无进展计数：定义什么叫进展——新的测试通过、新的有效 diff、新的结论。连续 N 步都没有，就停。
  • 硬预算 / 租约超时：任务领的是一份有期限的租约，到点必须续约或交还。不续约就收回，不靠 Agent 自己说「快好了」。
  • 外部 dead-man switch：看门狗本身也会挂。它要定期向外部打卡，外部收不到打卡就报警。监工不能给自己出健康证明。

落到交接包里，前三条就是上面 AGENTS.md 的「护栏」一节：用自然语言写给模型，同时尽量在脚本或调度层做硬限制。只写在 prompt 里的规则，模型可能不遵守；写进外部检查的规则，它绕不过去。

第四条不在交接包里，在你的运行环境里。这也是 Harness 和 prompt 的区别：Harness 有一部分根本不经过模型。

六、怎么维护才不烂尾

模板不难，难的是一直更新。三条纪律：

  1. 收工必写 STATE.md。写进 AGENTS.md 的收工规则里，让模型自己写，你只审。
  2. 测试命令必须能复制即跑。写不出完整命令的「通过」，一律当没测。
  3. 决策只追加不删。方案改了就追加一条新决策，写清推翻了哪条。新模型最怕的不是没信息，是两条互相打架的信息。

边界

交接包不是万能的：

  • 它不抹平模型差异。同一份状态，强模型和弱模型的执行结果照样不一样。它省的是入职成本，不是能力差距。
  • 它替代不了测试。交接包里的「最近一次通过」只是线索，新模型开工前要自己重跑一遍。
  • 密钥永远不进包。只写「凭证由环境提供」，不写凭证本身。

站内旧文可以对照看：《把没做完的任务交给另一个 Agent，什么才算完整交接》 讲的是接手时要审计的工作区、提交和测试证据；这篇讲的是在换模型之前，就把这些状态常驻在仓库里。

来源与口径：作者观点来自两条 X 回复原文；Harness 工程的行业讨论引自 X 热点汇总，属于对 X 帖子的摘要，相关数字未逐条核实，本文未引用；Claude Code 与 Codex 的文件加载规则以 2026-11-04 查阅的官方文档为准，版本更新后可能变化。