我做了一个工具，让 AI Agent 不再跑偏

harness-kit 开源

用 AI Agent 写代码，时间久了都会遇到三个问题。

第一，跑偏。你说"做一个登录页"，Agent 做着做着开始改数据库结构，理由是"顺手优化了一下"。

第二，失忆。每次开新对话，Agent 不知道上次做到哪里，不知道哪些路走过是死路，重新来过。

第三，自以为完成。Agent 扫了一眼代码，觉得"差不多了"，宣布任务完成。但你一看，有三个功能根本没做。

大多数人的解法是在 Prompt 里加一句"注意，下次不要这样做"。没用。下一个 Session，Agent 又忘了。

这个问题的本质是：Prompt 只活在当次对话里，下次打开全部清零。

解决思路

Mitchell Hashimoto（Terraform 的发明人）在今年 2 月写过一篇博客，描述了他的做法：

每次 Agent 犯一个错，我就把解决方法永久写进它的运行环境。

他把这个思路叫做 Harness Engineering。Harness 是马具的意思——决定马往哪儿跑，而不是每次骑马之前再叮嘱一遍。

我做的 harness-kit 是这个思路的一个具体实现。

核心机制只有两层：

关键点是：这两层不依赖 AI 是否记得去执行，是机械强制的。

它覆盖的不只是写代码。从需求探索、架构设计、开发、测试，到发布和复盘，整个软件开发周期里 Agent 的行为都在约束范围内。

怎么用

安装（一条命令）

npx @wuguirongsg/harness-kit

或者全局安装后在任意项目里使用：

npm install -g @wuguirongsg/harness-kitharness-kit /path/to/your-project

支持 macOS / Linux / Windows。

初始化（安装好后直接和AI Agent 说，只做一次）

claude "请读取 HARNESS_SETUP.md 并按步骤初始化这个项目的 harness"

AI 会自动扫描你的项目（读 package.json、Cargo.toml、go.mod 等），然后问你 5 个它自己发现不了的问题，生成所有状态文件。完成后 HARNESS_SETUP.md 可以删掉。

之后每次使用

claude   # 直接启动，不需要任何额外参数

Session 开始时，Hook 自动把当前进度、架构决策、未完成功能清单注入上下文，Agent 主动汇报状态并等待你确认，不需要手动叫它读任何文件。

Session 结束时，如果 Agent 没有写摘要、没有更新功能清单、没有做 git commit，就无法退出，被 Hook 强制执行完收尾清单才放行。

三个问题是怎么解决的

跑偏：.harness/state/features.json 是功能完成合约。每个功能一条记录，passes 字段只能从 false 改成 true，不能删除条目，不能修改描述。Agent 在功能验收之前无法宣布"完成"。

失忆：.harness/registry/ 目录存储所有架构决策（ADR）和 Session 摘要。Session 开始时 Hook 自动注入最近 5 条记录，上下文永远是连续的。

自以为完成：Stop Hook 在 Agent 准备退出时拦截，检查 SESSION_END 是否完成。没完成就阻止退出，强制把 registry、features.json、git commit 都做完再放行。

支持的工具

harness-kit 安装后会自动检测项目里存在哪些工具的配置目录，对应写入各自的 Hook 配置。

Claude Code 通过 .claude/settings.json 注册三个 Hook 事件：SessionStart（启动时注入状态）、Stop（退出时拦截检查）、PreToolUse（每条 Bash 命令执行前校验）。这是目前约束最完整的一端。

Cursor 通过 .cursor/hooks.json 注册同等的生命周期 Hook，行为与 Claude Code 一致。

OpenCode 没有原生 Hook 系统，harness-kit 写入一个 TypeScript Plugin（.opencode/plugin/harness-opencode-plugin.ts），通过 session.created 和 session.idle 两个生命周期事件实现等效约束。

Codex CLI 通过 .codex/hooks.json 注册 Hook，有一个细节：Codex 用 JSON stdout（{"continue": false}）来阻断 Session 退出，而不是 exit code，这个差异 harness-kit 已经做了平台适配。

Windsurf / Aider 目前没有 Hook 系统，只能依靠 AGENTS.md 的文字指令，不是机械强制，约束力弱于上面四个工具。

开发生命周期指令

harness-kit 不只管"写代码"这一个阶段。它把软件开发拆成 7 个阶段，每个阶段 Session 开始时注入的上下文不同，Agent 的行为重心也不同。

用 :指令 明确告诉 Agent 当前在哪个阶段，也可以直接说话让它自动判断。

需求探索（DISCOVER）

:discover 聊一下支付模块的需求

Agent 进入需求收集模式，产出写入 docs/requirements/，不会动代码。

架构设计（DESIGN）

:design 支付模块用第三方 SDK 还是自己实现？

Agent 输出方案对比，决策结果写入 registry/decisions/，后续 Session 自动继承这个结论。

规划（PLAN）

:plan 把支付模块拆成具体功能点

Agent 把功能点逐条写入 features.json，每条 passes: false，形成本轮 Sprint 的合约。

开发（BUILD）

:build 继续做 feat-002

默认模式，直接进入编码。也可以不加指令，Session 开始时 Agent 会根据 current-sprint.md 里的"默认 Session 阶段"字段自动判断。

快速修复（FIX）

:fix 登录页有个对齐 bug

跳过规划流程，直接描述问题。SESSION_END 也极简，只在 _index.md 记一行，不创建摘要文件。

验证（VERIFY）

:verify 跑一遍购物车模块的测试

Agent 专注测试和 Bug 记录，产出写入 registry/。

发布（RELEASE）

:release 准备 v0.5.0 发布说明

Agent 整理变更记录，产出写入 docs/releases/v0.5.0.md。

查看当前状态

:status

任何时候输入，Agent 输出当前 Sprint 目标、已完成功能数、未完成功能数、最近决策摘要。不启动新任务，只汇报。

Sprint 切换

当前 Sprint 所有功能都 passes: true 之后，告诉 Agent：

第一阶段已经全部完成，请结合 backlog 规划第二阶段

Agent 读取 features.json 和 backlog.md，向你确认新功能范围后更新状态文件，进入下一轮。

目前 npm 上有一个类似的工具 harnesskit（注意没有连字符），发布于今年 2 月，也是基于 Harness Engineering 理念。

两者的定位不同：

harnesskit 的核心是自动配置生成。一条命令检测你的技术栈（语言、IDE、git 平台），自动生成对应的配置文件，内置了多角色 Agent 协作流程（Planner → Implementer → Reviewer 循环），偏向"一键初始化"。

harness-kit 是基于Session 协议 + 机械约束。不在乎初始化有多快，在乎的是 Agent 在长时间工作中持续可靠。Session 开始和结束都有 Hook 强制执行，外部状态跨 Session 持久，还带了一套需求管理层（.harness/product/），可以把 backlog、变更记录和 Agent 工作流打通。

简单说，如果你需要快速给新项目生成配置，用 harnesskit。如果你在一个项目上要和 Agent 持续工作几周甚至几个月，harness-kit 的约束层对你更有用。

另外一个值得提的研究：ETH Zurich 2026 年的论文（arXiv:2602.11988）发现，AI 自动生成的 AGENTS.md 会让成功率下降 3%、推理成本上升 20%。harness-kit 的 AGENTS.md 刻意保持在 60 行以内，只写 AI 自己发现不了的信息，其余约束全靠 Hook 和状态文件承担。

开源地址

GitHub: https://github.com/wuguirongsg/harness-kitGitee: https://gitee.com/wuguirong/harness-kit

npx @wuguirongsg/harness-kit

（完）