Harness Engineering 实践指南

为 AI 编程代理（Claude Code、Codex、Cursor 等）构建可靠工作环境的系统工程方法论。

本文档综合 OpenAI、Anthropic、Martin Fowler、LangChain 及 GitHub 开源社区的最佳实践。

一、核心概念

Harness = Agent - Model

Harness 是 AI 代理中除模型以外的一切：约束、工具、文档、反馈循环。优化 Harness 比优化 Prompt 更有效 --- LangChain 仅靠改进 Harness 就从 Terminal Bench 2.0 的 52.8% 跃升至 66.5%。

核心哲学：人类掌舵，智能体执行（Human Steer, Agent Execute）

范式演进

复制代码

提示词工程 (2023-2024) → 上下文工程 (2025) → 驾驭工程 (2026)

当前推荐落地形态（2026）

推荐把 Harness Engineering 实现为：

一个 bootstrap-only 总入口 skill ：.claude/skills/harness-engineering/
一组由它在项目初始化时生成的 项目本地子 skill
一套 repo 内共享的 状态板、handoff、guardrails、evals、observability 占位

典型调用方式：

text 复制代码

/harness-engineering @技术文档 @PRD文档

该入口 skill 不负责长期日常开发，而是负责在项目创建阶段一次性生成：

AGENTS.md
CLAUDE.md
docs/harness-status.md
docs/handoffs/
.claude/hooks/
.claude/skills/task-intake
.claude/skills/review-fix
.claude/skills/release-check
.claude/skills/ui-verify
.claude/skills/handoff
scripts/bootstrap-verify.sh
evals/
observability/

二、七层架构模型

综合 justin3go、Blake Crosley、celesteanders 等开源项目，Harness 可分为七层：

Layer 1: Project Setup（项目配置）

目标：让 Agent 能正确启动和运行项目。

文件	作用
`.claude/settings.json`	Claude Code 配置（hooks、权限、MCP）
`.claude/skills/harness-engineering/`	初始化项目 Harness 的总入口 skill
`.claude/harness-bootstrap.json`	记录是否已初始化、版本、profile
`package.json` scripts	标准化命令入口
`.env.example`	环境变量模板
`tsconfig.json` 等	语言/构建工具配置

关键原则：

Agent 应该能通过一个清晰入口完成 Harness 初始化
bootstrap 应是 一次性初始化动作，而不是长期日常命令
已初始化项目应通过 repair / upgrade 演进，而不是重复覆盖

Layer 2: Context Engineering（上下文工程）

目标：让 Agent 快速理解项目全貌，知道去哪找信息。

文件	作用	建议行数
`CLAUDE.md`	AI 代理主入口，"目录"而非"百科"	~100 行
`AGENTS.md`	跨代理通用指令	~100 行
`docs/harness-status.md`	当前目标、状态、证据、下一步	按需
`docs/handoffs/`	跨窗口连续性工件	按需
`docs/execplans/`	大任务计划	按需
`docs/review-report/`	findings、复验与证据沉淀	按需
`docs/architecture.md`	系统架构与分层设计	按需
`docs/conventions.md`	编码规范与模式	按需
`docs/development-guide.md`	开发指南与工作流	按需

CLAUDE.md 最佳实践（来自 242 个仓库分析）：

浅层级结构（一级标题 + 子节），不要深度嵌套
渐进式披露：CLAUDE.md 是目录，docs/ 是正文
包含可直接执行的命令，不要只写描述
保持 ~100 行，超出部分放 docs/

CLAUDE.md 推荐结构：

markdown 复制代码

# Project Name --- Harness Guide
## Quick Reference (技术栈速查表)
## Commands (可执行命令列表)
## Project Structure (目录结构，带简要说明)
## Architecture Constraints (不可违反的规则)
## Key Patterns (核心设计模式)
## Documentation Index (指向 docs/ 的链接表)
## CIVC Feedback Loops (反馈循环命令)

Layer 3: Constraints & Rules（约束与规则）

目标：用机制而非提示词强制执行规范。

核心原则：能用机制检查的，就不要只写在文档里让 Agent "记住"。

工具	约束类型	示例
TypeScript strict	类型安全	编译时捕获类型错误
ESLint	代码规范 + 架构约束	`no-restricted-imports` 禁止直接导入 axios
Prettier	格式一致性	自动格式化
架构检查脚本	层级依赖方向	types/ 不能导入 views/
bootstrap 校验脚本	Harness 骨架完整性	关键入口、子 skill、hook、状态板是否齐全
自定义 linter 规则	项目特定约束	组件命名、导入顺序

ESLint 架构约束示例：

javascript 复制代码

// eslint.config.js
{
  rules: {
    'no-restricted-imports': ['error', {
      patterns: [{
        group: ['axios'],
        message: 'Use api/client.ts instead of importing axios directly.'
      }]
    }]
  }
}

架构检查脚本示例：

bash 复制代码

#!/bin/bash
# scripts/check-architecture.sh
# 检查层级依赖方向：types/ 不能导入 api/、stores/ 等
VIOLATIONS=0
for file in src/types/*.ts; do
  if grep -qE "from ['\"]@/(api|stores|components|views)/" "$file"; then
    echo "VIOLATION: $file imports from forbidden layer"
    VIOLATIONS=$((VIOLATIONS + 1))
  fi
done
exit $VIOLATIONS

Layer 4: Feedback Loops（反馈循环）

目标：Agent 出错时自动获得纠正信号。

反馈速度层级（越快越好）：

复制代码

PostToolUse Hook (毫秒) > pre-commit (秒) > CI (分钟) > 人工审查 (小时)

Claude Code Hooks 配置 (.claude/settings.json)：

json 复制代码

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/posttooluse-format.sh\""
          }
        ]
      }
    ]
  }
}

Hook 类型说明：

Hook	触发时机	用途
`PreToolUse`	工具调用前	拦截危险操作（exit 2 = 阻止）
`PostToolUse`	工具调用后	自动格式化、验证
`PreCommit`	git commit 前	lint + test
`Notification`	任务完成时	通知

Hook 设计原则：

hook 可以快速失败，但不能静默吞错
日志应明确区分 SKIP / OK / ERROR
Correct 环路必须提供真实失败信号，而不是伪装成功

反例：

bash 复制代码

npx prettier --write "$target_file" >/dev/null 2>&1 || true

这会吞掉格式化失败，使日志与真实状态脱节。

推荐写法：

bash 复制代码

if npx prettier --write "$target_file" >/dev/null 2>&1; then
  printf '%s OK %s via=prettier\n' "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" "$target_file"
else
  status=$?
  printf '%s ERROR %s via=prettier exit=%s\n' "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" "$target_file" "$status"
  exit "$status"
fi

Layer 5: Verification（验证）

目标：多层验证确保代码质量。

验证层级：

复制代码

确定性验证（快）          推理型验证（慢）
├── TypeScript 类型检查    ├── AI 代码审查
├── ESLint 规则检查        └── Agent 交叉验证
├── 单元测试
├── 架构约束检查
└── 格式检查

Pre-commit 配置（simple-git-hooks + lint-staged）：

json 复制代码

// package.json
{
  "simple-git-hooks": {
    "pre-commit": "pnpm lint-staged"
  },
  "lint-staged": {
    "*.{vue,ts,tsx}": ["eslint --fix", "prettier --write"],
    "*.css": ["prettier --write"]
  }
}

全量检查命令：

json 复制代码

{
  "scripts": {
    "check:all": "pnpm format:check && pnpm lint && pnpm check:arch && pnpm check:docs && pnpm build && pnpm test"
  }
}

Harness 级验证不应只停留在 check:all。建议至少分三层：

工程健康检查：build、lint、test、arch、docs
bootstrap 校验：入口文档、状态板、handoff、child skills、hooks 是否齐全
workflow eval：task intake → review fix → handoff 是否能闭环流转

Layer 6: Entropy Management（熵管理）

目标：对抗文档腐化和代码熵增。

OpenAI 的策略：持续小额偿还，而非集中处理 --- 他们称之为"垃圾回收"。

文档新鲜度检查脚本：

bash 复制代码

#!/bin/bash
# scripts/check-docs-freshness.sh
# 检查文档中引用的 repo 路径是否仍然存在
stale=0
while IFS= read -r path; do
  clean="$(printf '%s' "$path" | sed -E 's/^[<(]+//; s/[>)",;:]+$//; s/:[0-9]+$//')"
  [ -z "$clean" ] && continue
  if [ ! -e "$clean" ]; then
    echo "STALE: $clean referenced in docs but not found"
    stale=$((stale + 1))
  fi
done < <(
  grep -rohE '(\.claude|docs|scripts|evals|observability|src)/[A-Za-z0-9_./:-]+' docs/*.md CLAUDE.md AGENTS.md | sort -u
)
exit "$stale"

熵管理策略：

定期运行文档一致性检查
CLAUDE.md 保持精简（~100 行），减少维护负担
让 Agent 在发现文档过期时主动更新
测试文件与源码同目录，减少漂移

Layer 7: Observability（可观测性）

目标：了解 Agent 的工作质量和效率。

运行时证据	追踪方式
启动是否成功	本地启动日志 / 健康检查
页面是否可用	截图、DOM snapshot、关键路径 smoke
浏览器异常	console / network 错误检查
服务异常	结构化日志、错误率、trace
Harness 是否可持续运行	状态板、handoff、review-report 是否持续回写

三、CIVC 四大机制

CIVC 是 Harness 的运行时闭环，贯穿七层架构：

复制代码

约束 (Constrain) → 告知 (Inform) → 验证 (Verify) → 纠正 (Correct)
     ↑                                                    │
     └────────────────────────────────────────────────────┘

机制	定义	实现方式
Constrain	通过结构缩小可能性空间	ESLint、TypeScript strict、架构检查、`no-restricted-imports`
Inform	解决 Agent "知道什么"	CLAUDE.md → docs/ 渐进式文档、API 类型定义
Verify	确定性 + 推理型分层验证	pre-commit hooks、`check:all`、CI pipeline
Correct	偏差检测与自动恢复	PostToolUse auto-format、lint:fix、文档新鲜度检查

四、四大护栏

OpenAI/Anthropic 团队实践中反复出现的四个模式：

1. 上下文工程（Context Engineering）

Agent 只能推理它能看到的内容
CLAUDE.md 是入口，不是百科全书
使用 @docs/xxx.md 引用深层文档
保持文档机器可读

2. 架构约束（Architecture Constraints）

严格的层级依赖模型（如 Types → Config → Repo → Service → Runtime → UI）
用 linter 和结构测试机械化执行，不依赖 Agent "记住"
跨切面关注点（认证、日志）通过单一接口注入

3. 反馈循环（Feedback Loops）

错误信息即 Prompt：linter 报错格式应为 问题 + 修复建议 + 文档链接
反馈越快越好：PostToolUse > pre-commit > CI > 人工
Agent 审 Agent：用一个 Agent 验证另一个的输出

4. 熵管理（Entropy Management）

持续小额偿还技术债
定期文档一致性扫描
命名规范漂移检测
死代码清理

五、新项目 Harness 搭建清单（v2）

Phase 0: Bootstrap

创建 .claude/skills/harness-engineering/
准备模板、脚本、profile 参考文档
以 /harness-engineering @技术文档 @PRD文档 作为初始化入口
写入 .claude/harness-bootstrap.json 防止重复初始化

Phase 1: Shared Context

Phase 2: Child Skills

生成 .claude/skills/task-intake/
生成 .claude/skills/review-fix/
生成 .claude/skills/release-check/
生成 .claude/skills/ui-verify/
生成 .claude/skills/handoff/

Phase 3: Guardrails + Hooks

配置 .claude/settings.json
配置 .claude/hooks/posttooluse-format.sh
创建 scripts/check-architecture.sh
创建 scripts/check-docs-freshness.sh
创建 scripts/bootstrap-verify.sh
明确 hook 不得吞错

Phase 4: Evals + Observability

创建 evals/harness/
创建 evals/regression/
创建 observability/README.md
为 UI / 服务运行时证据预留最小协议

Phase 5: Long-Running Workflow

规定 task intake 必须回写状态板
规定 review fix 必须沉淀 review-report
规定暂停/切换窗口时必须写 handoff
规定 verified 必须绑定 fresh evidence

六、文件清单模板

复制代码

project-root/
├── CLAUDE.md                      # AI 代理主入口（~100 行）
├── AGENTS.md                      # 跨代理通用指令
├── README.md                      # 项目 README
├── .claude/
│   ├── settings.json              # Claude Code hooks + 配置
│   ├── harness-bootstrap.json     # bootstrap 标记与 profile
│   ├── hooks/
│   │   └── posttooluse-format.sh  # 自动纠偏，失败显式暴露
│   └── skills/
│       ├── harness-engineering/   # bootstrap-only 总入口 skill
│       ├── task-intake/           # 任务接入
│       ├── review-fix/            # 审查修复
│       ├── release-check/         # 发布检查
│       ├── ui-verify/             # UI 验证
│       └── handoff/               # 交接沉淀
├── docs/
│   ├── harness-status.md          # 状态板
│   ├── handoffs/                  # 交接文档
│   ├── execplans/                 # 大任务计划
│   ├── review-report/             # findings / 复验 / 证据
│   ├── architecture.md            # 系统架构
│   ├── conventions.md             # 编码规范
│   ├── development-guide.md       # 开发指南
│   ├── api-guide.md               # API 文档（如适用）
│   └── component-guide.md         # 组件文档（如适用）
├── scripts/
│   ├── check-architecture.sh      # 架构约束检查
│   └── check-docs-freshness.sh    # 文档新鲜度检查
│   └── bootstrap-verify.sh        # Harness 骨架校验
├── evals/
│   ├── harness/                   # Harness 级 eval
│   └── regression/                # 历史问题回归
├── observability/
│   └── README.md                  # 运行时证据与可观测性占位
├── eslint.config.js               # ESLint 配置（含架构规则）
├── .prettierrc                    # Prettier 配置（如需）
└── package.json                   # scripts + git hooks + lint-staged

七、参考来源

Harness Engineering 实践指南

一、核心概念

范式演进

当前推荐落地形态（2026）

二、七层架构模型

Layer 1: Project Setup（项目配置）

Layer 2: Context Engineering（上下文工程）

Layer 3: Constraints & Rules（约束与规则）

Layer 4: Feedback Loops（反馈循环）

Layer 5: Verification（验证）

Layer 6: Entropy Management（熵管理）

Layer 7: Observability（可观测性）

三、CIVC 四大机制

四、四大护栏

1. 上下文工程（Context Engineering）

2. 架构约束（Architecture Constraints）

3. 反馈循环（Feedback Loops）

4. 熵管理（Entropy Management）

五、新项目 Harness 搭建清单（v2）

Phase 0: Bootstrap

Phase 1: Shared Context

Phase 2: Child Skills

Phase 3: Guardrails + Hooks

Phase 4: Evals + Observability

Phase 5: Long-Running Workflow

六、文件清单模板

七、参考来源

核心文章

实践指南

GitHub 开源项目

CLAUDE.md 专项