Abide：让编码代理遵循项目规则的 Claude Code 插件

coldteadotai/abide

做法是在两个仓库里，把 93 段真实的 Claude Code 会话对着各自的 AGENTS.md 重放一遍。1,256 次编辑、147 轮，总共 22 美分。Jev 标记了 39 次编辑和 15 轮，一位独立评审者确认其中 10 次和 11 轮。轮级别的命中（一次性抽象、文件过大、逻辑重复）在 15 轮中站住了 11 次。方法、按规则的表格、哪里翻了车，都放在 benchmarks/replay。

npx @coldtea/abide login    # 选择 key 类型，粘贴一次即可
npx @coldtea/abide init     # 接入本机的每一个 agent

之后正常启动 claude、codex 或 opencode 就完事。这就是全部安装步骤。

它做什么

你的 AGENTS.md、CLAUDE.md 以及项目里其它指令文件塞满了任何 linter（静态检查工具）都查不了的规则。「永远不要让原始错误直接呈现给用户。」「不要创建过早的抽象。」这些没法用脚本表达，自然也就无从强制。在 93 段真实会话里，agent 从第一次编辑起，平均每 13 轮就会踩中一条。

demo-abstraction.mp4

Abide 就是来强制这些规则的。每次编辑（或每轮）发生时，它会针对每条规则向 Jev（TypeSafe 的决策模型）问一个问题，并拿到一个概率。Jev 只看规则和 diff（差异），看不到对话，所以第 200 次编辑和第 1 次编辑的检查方式完全一样。踩中规则时，agent 会被点名是哪一条，并在同一轮里修好。

一次调用对应一次编辑，约 300 毫秒，成本只要千分之几美分。

linter 能查的规则交给你的 linter 去查。

没有内置规则。没有指令文件，也没有任何需要强制的东西。

你的 key，你的数据。本工具不会跟我们的服务器通信。

过去做不到

过去用普通 LLM 逐条检查每次编辑或每一轮，经济上和延迟上都不划算。一次检查约 2,500 个 token。按常见模型价格算，每次编辑要一美分多、耗时几秒，而且返回的是自然语言文本，你还得二次解析，且没法完全信任。每天两百次编辑的做法根本无从谈起。

Jev 改写了这笔账。它是决策模型，回答带类型的问题时只返回一个校准后的概率，没有别的输出。没有自由文本，就没有凭空捏造的余地。它比普通 LLM 便宜最多 100 倍，响应约 300 毫秒。这两点合起来，让逐次检查、每条都查，变得划算。

三分钟看到第一次命中

去 typesafe.ai 申请一个 TypeSafe API key，或者直接用你已有的 Vercel AI Gateway key。

跑 npx @coldtea/abide login，选好 key 的种类和存放位置，粘贴进去。它会写入 ~/.abide/.env（适用于本机所有仓库），或写入本仓库的 .env.local，权限均为所有者独占。仓库根目录已有的 .env 文件也能直接用。

在仓库里跑 npx @coldtea/abide init。

启动你的 agent。它的第一轮会把你的规则编译成 .abide/rubric.json，并告诉你发现了什么。

让 agent 做一件规则明令禁止的事。比如 AGENTS.md 写明「使用 Yup，绝不手写校验」，agent 一旦写出手写的守卫逻辑，下面这段立刻就会蹦出来

Abide: This edit appears to break a rule from this repository's instructions.

- Rule "api-validation-uses-yup" from ~/.codex/AGENTS.md line 65: "When writing API endpoints, do NOT write input validations manually. Use Yup (with clear validation messages) + early return in the API handler". (0.86)

Repair apps/web/src/pages/api/logout.ts now, then continue with the task.

agent 在继续推进任务之前会把它修好。无需人工介入。

Agents

| Agent | 安装 | 落地位置 |
|---|---|---|
| Claude Code | npx @coldtea/abide init claude | ~/.claude/settings.json |
| Codex | npx @coldtea/abide init codex | ~/.codex/hooks.json |
| OpenCode | npx @coldtea/abide init opencode | ~/.config/opencode/plugins/abide.js |init 不带名字就会装进它找到的所有 agent。加上 --project 改为装到仓库内，团队成员拉取代码时一并获得。

只有 Codex 需要多做一步，启动 codex 后输入 /hooks，接受 abide 的四个条目。Codex 对每个新 hook 只问一次。Codex 通过 apply_patch 编辑；abide 读取补丁并判定其中每个文件。

只有 OpenCode 特殊，OpenCode 没有 hook 进程，所以 abide 以插件形式运行。检查方式和消息格式都一样。违反规则的编辑会在工具结果（tool result）末尾追加修复请求；若整轮结束时仍存在违规，则追加一条后续消息。

看看你的代码库已经在哪些地方违规

abide audit src/

每个文件都按「刚写完」的标准被判定。你会得到一张按规则汇总的表格，和一份按文件汇总的清单。在一个真实 Next.js 应用的 33 个 API 路由上跑一遍，耗时 12 秒，成本约一美分。

命令

| 命令 | 作用 |
|---|---|
| abide login | 存储你的 TypeSafe 或 Vercel AI Gateway key，作用于你本人或本仓库 |
| abide init [agent] | 安装 hooks（claude、codex、opencode，或所有已发现的 agent） |
| abide audit [paths] | 判定已有文件，按规则与文件输出报告 |
| abide check [paths] | 按 hooks 的方式检查未提交的变更 |
| abide report | 报告你的规则，哪些被触发，哪些从未触发 |
| abide replay <agent> | 对本仓库过往的三种 agent 会话进行判定 |
| abide compile | 立即编译 rubric（评分细则），而不是等到下一次会话 |
| abide calibrate | 用近期 git 历史为每条规则打分 |
| abide tune | 重写那些从未触发的规则 |
| abide bench | 在你的机器上实测延迟与开销 |
| abide uninstall [agent] | 移除 hooks |report、check、audit、bench、calibrate 都支持 --json。

Rubric 属于你

abide/rubric.json 是一个应当入库、人类可读的文件。每条判定都会点名所对应的规则，每条规则都会引用它来源的指令文件行号。判定错了，对应规则可以重写。

每条规则在两个时机之一运行。edit 阶段，每次编辑之后跑一次；turn 阶段，整轮结束时针对完整 diff 一次性跑。「这次是不是做了超出要求的事」在 12 次编辑的第 1 次之后根本没有答案。

每条规则可以附带一个 glob 模式作用域，让 API 路由和样式表被问不同的问题。

判定结果分档。0.8 及以上，agent 被要求修复；0.5 到 0.8，你自己会看到一条提示，agent 看不到；0.5 以下，啥也不发生。

措辞糟糕的规则在所有情况下都会拿到 0.4，永远不会触发。calibrate 会用你历史里的 20 个真实 hunk（差异片段）把它们挑出来关掉。tune 则让 agent 来重写它们。

成本、隐私、安全

变更行通过你的 key 发往 TypeSafe，每次调用都请求零数据留存（zero data retention），除此之外哪儿也不发。

key 的查找顺序，环境变量、仓库根目录的 .env.local 和 .env，再到 ~/.abide/.env。绝不通过命令行参数传入，绝不写入日志。设置 AI_GATEWAY_API_KEY 取代 TypeSafe key 即可走 Vercel AI Gateway。

本仓库 13 条规则下的一次检查消耗 1,000 至 1,600 个输入 token，成本 $0.00004 至 $0.00007，Jev 约 300 毫秒，含 Node 启动在内的整个 hook 流程约 1 秒。15 次编辑的一轮成本约为十分之一美分。测量于 2026-09-18，直连 TypeSafe。

abide bench 会测量你自己的数字。

hooks 不会破坏你的会话。每条路径都以退出码 0 退出，设有硬性截止时间，且只输出宿主期望的内容。

没有 key 或无网络时，编辑照常通过、跳过检查，漏检事件记录在 .abide/events.jsonl，由 report 统计。

它如何接入

每个 agent 四个 hook。会话开始，对指令文件做哈希，若有变更则让 agent 重新编译。轮开始，用 git 快照工作树。每次编辑之后，对该 hunk 跑 edit 阶段规则。轮结束，将整轮 diff 与快照对比，跑 turn 阶段规则，并对 shell 命令写入的文件额外跑 edit 阶段规则。