Harness Engineering 实践指南

为 AI 编程代理Claude Code、Codex、Cursor 等构建可靠工作环境的系统工程方法论。本文档综合 OpenAI、Anthropic、Martin Fowler、LangChain 及 GitHub 开源社区的最佳实践。一、核心概念Harness Agent - ModelHarness 是 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 占位典型调用方式/harness-engineering 技术文档 PRD文档该入口 skill 不负责长期日常开发而是负责在项目创建阶段一次性生成AGENTS.mdCLAUDE.mddocs/harness-status.mddocs/handoffs/.claude/hooks/.claude/skills/task-intake.claude/skills/review-fix.claude/skills/release-check.claude/skills/ui-verify.claude/skills/handoffscripts/bootstrap-verify.shevals/observability/二、七层架构模型综合 justin3go、Blake Crosley、celesteanders 等开源项目Harness 可分为七层Layer 1: Project Setup项目配置目标让 Agent 能正确启动和运行项目。文件作用.claude/settings.jsonClaude Code 配置hooks、权限、MCP.claude/skills/harness-engineering/初始化项目 Harness 的总入口 skill.claude/harness-bootstrap.json记录是否已初始化、版本、profilepackage.jsonscripts标准化命令入口.env.example环境变量模板tsconfig.json等语言/构建工具配置关键原则Agent 应该能通过一个清晰入口完成 Harness 初始化bootstrap 应是一次性初始化动作而不是长期日常命令已初始化项目应通过repair/upgrade演进而不是重复覆盖Layer 2: Context Engineering上下文工程目标让 Agent 快速理解项目全貌知道去哪找信息。文件作用建议行数CLAUDE.mdAI 代理主入口“目录而非百科”~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 推荐结构# 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禁止直接导入 axiosPrettier格式一致性自动格式化架构检查脚本层级依赖方向types/ 不能导入 views/bootstrap 校验脚本Harness 骨架完整性关键入口、子 skill、hook、状态板是否齐全自定义 linter 规则项目特定约束组件命名、导入顺序ESLint 架构约束示例// eslint.config.js{rules:{no-restricted-imports:[error,{patterns:[{group:[axios],message:Use api/client.ts instead of importing axios directly.}]}]}}架构检查脚本示例#!/bin/bash# scripts/check-architecture.sh# 检查层级依赖方向types/ 不能导入 api/、stores/ 等VIOLATIONS0forfileinsrc/types/*.ts;doifgrep-qEfrom [\]/(api|stores|components|views)/$file;thenechoVIOLATION:$fileimports from forbidden layerVIOLATIONS$((VIOLATIONS1))fidoneexit$VIOLATIONSLayer 4: Feedback Loops反馈循环目标Agent 出错时自动获得纠正信号。反馈速度层级越快越好PostToolUse Hook (毫秒) pre-commit (秒) CI (分钟) 人工审查 (小时)Claude Code Hooks 配置(.claude/settings.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工具调用后自动格式化、验证PreCommitgit commit 前lint testNotification任务完成时通知Hook 设计原则hook 可以快速失败但不能静默吞错日志应明确区分SKIP/OK/ERRORCorrect环路必须提供真实失败信号而不是伪装成功反例npx prettier--write$target_file/dev/null21||true这会吞掉格式化失败使日志与真实状态脱节。推荐写法ifnpx prettier--write$target_file/dev/null21;thenprintf%s OK %s viaprettier\n$(date-u%Y-%m-%dT%H:%M:%SZ)$target_fileelsestatus$?printf%s ERROR %s viaprettier exit%s\n$(date-u%Y-%m-%dT%H:%M:%SZ)$target_file$statusexit$statusfiLayer 5: Verification验证目标多层验证确保代码质量。验证层级确定性验证快 推理型验证慢 ├── TypeScript 类型检查 ├── AI 代码审查 ├── ESLint 规则检查 └── Agent 交叉验证 ├── 单元测试 ├── 架构约束检查 └── 格式检查Pre-commit 配置simple-git-hooks lint-staged// package.json{simple-git-hooks:{pre-commit:pnpm lint-staged},lint-staged:{*.{vue,ts,tsx}:[eslint --fix,prettier --write],*.css:[prettier --write]}}全量检查命令{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、docsbootstrap 校验入口文档、状态板、handoff、child skills、hooks 是否齐全workflow evaltask intake → review fix → handoff 是否能闭环流转Layer 6: Entropy Management熵管理目标对抗文档腐化和代码熵增。OpenAI 的策略持续小额偿还而非集中处理— 他们称之为垃圾回收。文档新鲜度检查脚本#!/bin/bash# scripts/check-docs-freshness.sh# 检查文档中引用的 repo 路径是否仍然存在stale0whileIFSread-rpath;doclean$(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 错误检查服务异常结构化日志、错误率、traceHarness 是否可持续运行状态板、handoff、review-report 是否持续回写三、CIVC 四大机制CIVC 是 Harness 的运行时闭环贯穿七层架构约束 (Constrain) → 告知 (Inform) → 验证 (Verify) → 纠正 (Correct) ↑ │ └────────────────────────────────────────────────────┘机制定义实现方式Constrain通过结构缩小可能性空间ESLint、TypeScript strict、架构检查、no-restricted-importsInform解决 Agent “知道什么”CLAUDE.md → docs/ 渐进式文档、API 类型定义Verify确定性 推理型分层验证pre-commit hooks、check:all、CI pipelineCorrect偏差检测与自动恢复PostToolUse auto-format、lint:fix、文档新鲜度检查四、四大护栏OpenAI/Anthropic 团队实践中反复出现的四个模式1. 上下文工程Context EngineeringAgent 只能推理它能看到的内容CLAUDE.md 是入口不是百科全书使用docs/xxx.md引用深层文档保持文档机器可读2. 架构约束Architecture Constraints严格的层级依赖模型如 Types → Config → Repo → Service → Runtime → UI用 linter 和结构测试机械化执行不依赖 Agent “记住”跨切面关注点认证、日志通过单一接口注入3. 反馈循环Feedback Loops错误信息即 Promptlinter 报错格式应为问题 修复建议 文档链接反馈越快越好PostToolUse pre-commit CI 人工Agent 审 Agent用一个 Agent 验证另一个的输出4. 熵管理Entropy Management持续小额偿还技术债定期文档一致性扫描命名规范漂移检测死代码清理五、新项目 Harness 搭建清单v2Phase 0: Bootstrap创建.claude/skills/harness-engineering/准备模板、脚本、profile 参考文档以/harness-engineering 技术文档 PRD文档作为初始化入口写入.claude/harness-bootstrap.json防止重复初始化Phase 1: Shared Context生成CLAUDE.md生成AGENTS.md生成docs/harness-status.md生成docs/handoffs/生成docs/execplans/生成docs/review-report/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七、参考来源核心文章OpenAI - Harness Engineering — 百万行代码实验报告Martin Fowler - Harness Engineering — 三大支柱定义LangChain - The Anatomy of an Agent Harness — Harness 解剖实践指南justin3go - 七层 Harness 模型Blake Crosley - Context Is Architecture — 七层上下文架构Blake Crosley - 5 Production Hooks — Hooks 实战Sakasegawa - Best PracticesFlashcat - CIVC 四大机制GitHub 开源项目celesteanders/harness — 最佳实践集合ai-boost/awesome-harness-engineering — 资源列表walkinglabs/awesome-harness-engineering — 工具与指南deusyu/harness-engineering — 中文学习指南CLAUDE.md 专项The Definitive Guide to CLAUDE.md — 五层配置系统CLAUDE.md Progressive Disclosure Guidedotclaude.com — .claude 目录参考