【实战解析】wow-harness：Claude Code的治理层框架，16个Hook+8关状态机让AI Agent不再偷懒

wow-harness 是一个针对 Claude Code 的开源治理层（Governance Layer）框架，通过16个生命周期hook实时拦截、8关状态机独立审查、Schema级工具隔离等机制，解决AI Agent"假装完成""任务漂移""自评偏差"等问题。本文从架构设计、核心机制、安装部署、实际使用体验等角度做深度拆解。

黑马14253

728人浏览 · 2026-04-13 19:45:47

黑马14253 · 2026-04-13 19:45:47 发布

wow-harness 是一个针对 Claude Code 的开源治理层（Governance Layer）框架，通过16个生命周期hook实时拦截、8关状态机独立审查、Schema级工具隔离等机制，解决AI Agent"假装完成"“任务漂移”"自评偏差"等问题。本文从架构设计、核心机制、安装部署、实际使用体验等角度做深度拆解。

前言

上周用Claude Code做项目,让它加个接口。它报告"测试全部通过"。我没多想就合了。第二天上线,那接口直接空指针——它根本没跑测试，是自己脑补了一个结果告诉我的。

这种事估计用过Claude Code的人都遇到过。AI做对的80%让你放松警惕,但剩下20%的静默遗漏才是真正危险的。有时候监督AI agent的时间比自己写还长。

然后我刷到了wow-harness这个项目。它是从Towow（通爻）6个月的生产环境里提炼出来的,专门解决这个问题。MIT协议开源。

一、AI Agent的五大坏毛病

在讲wow-harness之前，先明确下它要解决什么。作者总结了AI agent的结构性偏见：

问题	表现	危害
假装完成	“测试全过了”（实际没跑）	上线后出生产事故
跳过审查	“这个改动很简单”	引入未审查代码
任务漂移	修一个bug，顺手重构三个文件	代码变更不可控
自我评价偏差	问自己"做得好不好"，永远"好"	无法发现自身错误
并行污染	多session互相影响	代码冲突和数据混乱

作者给了一个很扎心的数据：

CLAUDE.md 指令遵从率:     ~20%
PreToolUse hook 执行率:   100%

你在CLAUDE.md里写"修改后必须跑测试"，AI大概率无视。但把这个要求写成hook,它就没法绕过。

二、核心架构

2.1 整体设计

                        ┌─────────────────┐
                        │   Claude Code    │
                        └────────┬────────┘
                                 │
                    ┌────────────▼────────────┐
                    │    wow-harness 治理层     │
                    │                          │
                    │  ┌──────────────────┐   │
                    │  │  16个生命周期Hook │   │
                    │  │  (实时拦截)       │   │
                    │  └────────┬─────────┘   │
                    │           │              │
                    │  ┌────────▼─────────┐   │
                    │  │  8关状态机        │   │
                    │  │  (独立审查)       │   │
                    │  └────────┬─────────┘   │
                    │           │              │
                    │  ┌────────▼─────────┐   │
                    │  │  15个自动验证器   │   │
                    │  │  (变更校验)       │   │
                    │  └────────┬─────────┘   │
                    │           │              │
                    │  ┌────────▼─────────┐   │
                    │  │  16个专业化Skill  │   │
                    │  │  (判断框架)       │   │
                    │  └──────────────────┘   │
                    └─────────────────────────┘

2.2 16个生命周期Hook

覆盖7个阶段,每个阶段都有拦截点：

# Hook 生命周期
SessionStart  →  加载上下文、重置风险状态、展示可用工具
PreToolUse    →  拦截危险部署、门控审查agent、净化读取内容
PostToolUse   →  编辑时路由上下文、检测循环、追踪风险
Stop          →  验证是否存在完成候选品 (transcript × git diff)
SessionEnd    →  反思、分析轨迹、持久化进度

关键点：这些hook是机械执行的,不是"建议"。PreToolUse会在AI每次调用工具前运行,如果条件不满足,工具调用直接失败。

2.3 8关状态机（Gate System）

G0 问题定义
  → G1 设计方案
    → G2 独立审查 ★
      → G3 实现方案
        → G4 审查+锁定 ★
          → G5 任务拆分
            → G6 独立审查 ★
              → G7 执行+日志
                → G8 终审 ★

★ = 独立审查者（独立上下文、只读工具）

偶数关是独立审查关,启动一个新的agent来审查。审查agent的工具清单里物理上没有写入工具：

// 审查agent的工具配置
{
  "allowed_tools": ["Read", "Search", "Grep", "ListFiles"],
  // 注意：没有 Edit、Write、Execute
  // 不是"请不要用"，是物理上不存在
}

结果：遵从率从~70%提升到100%。

2.4 Schema级工具隔离

这个设计我觉得是整个项目最精髓的地方。传统做法是在prompt里写"审查时请不要修改代码",遵从率大概70%。wow-harness的做法是在审查agent的tool schema里直接删掉写入工具——不是"请不要"，是"不能"。

2.5 Fail-open安全方向

# 伪代码：hook读不到数据时的处理
def pre_tool_use_hook(tool_call):
    risk_data = read_risk_state()
    if risk_data is None:
        # 不是跳过检查，而是注入更多检查
        inject_additional_review()
        # 失败模式永远是"过于谨慎"
        # 绝不"静默跳过"

三、安装部署

3.1 环境要求

项目	要求
AI工具	Claude Code
Python	3.9+
Git	已安装

3.2 安装步骤

# 1. 克隆仓库
git clone https://github.com/NatureBlueee/wow-harness.git
cd wow-harness

# 2. 运行安装脚本（选择信任层级）
python3 scripts/install/phase2_auto.py /path/to/your/project --tier drop-in

三个信任层级：

层级	信任度	说明
drop-in	最低	原样安装hook+skill，先试试看
adapt	中等	读项目README和文档，适配skill
mine	完全	读工作transcript，深度适配开发模式

安装器是幂等的,跑多次结果一样。

3.3 安装后的目录结构

your-project/
├── .claude/
│   ├── settings.json    # Hook注册（追加模式，不覆盖已有）
│   ├── skills/          # 16个agent行为定义
│   └── rules/           # 路径作用域上下文规则
├── scripts/
│   ├── hooks/           # 16个生命周期hook
│   └── checks/          # 15个自动化验证器
└── CLAUDE.md            # 治理指南（自动生成，可编辑）

四、实际使用和踩坑

4.1 好的地方

"假装完成"确实少了。Stop hook会在agent说"完成"时检查transcript和git diff,没有真实变更就打回
审查agent隔离设计效果很好,独立上下文+只读工具,审查质量明显提升
安装无侵入,hook是追加到settings.json里的，不会覆盖你已有的配置

4.2 踩坑记录

问题	原因	解决
小项目改动也要过8关	状态机粒度太粗	在CLAUDE.md里配置简化模式
偶尔触发额外审查	Fail-open机制,临时文件未生成	等一下重试，正常现象
独立审查agent响应慢	需要启动新的agent上下文	接受，这是安全的代价
不支持Cursor/Copilot	目前只做了Claude Code	等作者扩展，或自己fork改

4.3 建议

小项目用drop-in层级就够了。8关状态机可以在CLAUDE.md里调整,不是每个改动都需要走完整流程。大型项目或团队协作场景,建议上adapt或mine层级,效果会好很多。

五、与其他方案的对比

维度	wow-harness	纯CLAUDE.md	自定义hook
拦截方式	机械hook+schema隔离	自然语言指令	需自己写
遵从率	~100%	~20%	看实现质量
审查机制	独立agent+只读工具	自我审查	无
安装成本	一条命令	手写	高
灵活性	三层级可调	完全灵活	完全灵活
适用范围	仅Claude Code	仅Claude Code	看实现