Quartz 4

Harness Engineering：围绕现有代码库构建工程化治理框架完全指南

21 min read

Harness Engineering：围绕现有代码库构建工程化治理框架完全指南

概述

Harness Engineering（工程化治理框架）是围绕代码库构建完整工程化开发框架的学科，核心目标是让代码的编写、测试、集成、部署和维护过程可重复（reproducible）、可观测（observable）、自动化（automated），并提供良好的开发者体验（Developer Experience, DX）。

在 AI Agent 时代，这一概念进一步扩展为：设计让人类和 AI agent 都能可靠地在代码库中工作的环境。

OpenAI 的 Codex 团队在 2025-2026 年间实验证明：三名工程师利用 Codex agent 从零开始构建了百万行级别的生产系统，没有一行代码是人类手写的。他们将这套方法论命名为 Harness Engineering（OpenAI, 2026；InfoQ, 2026）。Martin Fowler 将其定义为”用于约束和维护 AI agent 行为的工具与实践体系”（Fowler, 2026）。

核心认知：模型之外的系统比模型本身更重要。 LangChain 的实证表明，通过仅改变 harness（不改变模型），其编码代理在 Terminal Bench 2.0 上从 52.8% 跃升至 66.5%，从 Top 30 进入 Top 5（NxCode, 2026）。

一、绝对必要的核心组件

1. 版本控制与分支策略

版本控制是一切工程化的起点。推荐 Trunk-Based Development——Google 的 35,000 名开发者在单一 monorepo 中使用此模式（trunkbaseddevelopment.com）。

核心实践：

  • 每日集成：开发者至少每天提交一次代码到主干
  • 小批量变更：每次提交尽可能小且自包含
  • 代码评审（Code Review）：通过 Pull Request 或类似机制进行同行评审
  • 受保护分支：主干分支需要通过 CI 检查和至少一人审批才能合并
  • Feature Flags（功能开关）允许未完成的功能合入主干但不暴露给用户

分支策略演进：Git Flow（2010，复杂）→ GitHub Flow（折中）→ Trunk-Based Development（推荐）。

2. 代码规范与 Linting（机械化执行）

OpenAI Codex 团队将此提升到架构级别——通过自定义 linter 和结构测试（structural tests）强制执行严格的依赖层级（Types → Config → Repo → Service → Runtime → UI），agent 无法违反模块边界。更值得注意的是，这些 linter 本身也是由 Codex agent 编写的。

核心原则：Mechanical Enforcement Over Documentation（机械化执行优于文档记录）——与其写一份”请遵守以下架构规则”的文档，不如让 CI 系统自动拒绝违反规则的代码（Tony Lee, 2026）。

主流工具演进：

  • JavaScript/TypeScript：JSLint → JSHint → ESLint → Biome（Rust 构建，快 10-100x）
  • Python：Pylint → Black + isort + mypy → Ruff（Rust 构建）
  • Go：golangci-lint（go vet + staticcheck 等聚合）
  • 格式化：Prettier（JS/TS）、Black（Python）、gofmt（Go）
  • 企业级：SonarQube（多语言集中式分析）、Semgrep（安全规则）

3. 自动化构建（一条命令构建）

构建系统是一切自动化的基础。演进路线：

时期工具特点
1976Make最早的构建自动化工具
2000CMake跨平台元构建系统
2007GradleJVM/Android 标准
2015BazelGoogle 开源，Hermetic builds + 分布式缓存
2023Buck2Meta 开源，Rust 编写，构建速度是 Buck1 的两倍
2024+Turborepo/Nx现代 JS/TS monorepo 编排

核心追求是 Hermetic Build（密封构建）——构建过程和产物不受外部环境影响（DevSecOps Now）。三个层次的可重复性：

  1. Repeatable Build：构建步骤被脚本化
  2. Rebuildable Build：能重新生成任何历史版本
  3. Binary Reproducible Build：给定相同输入，输出完全相同

4. 自动化测试框架

遵循测试金字塔模型（Atlassian）：

        /  E2E  \          ← 少量、缓慢、昂贵
       / 集成测试 \         ← 中等数量
      /  单元测试  \        ← 大量、快速、廉价
     ================

TDD（Test-Driven Development）核心循环：Red → Green → Refactor（IBM）。

5. CI/CD 管道

持续集成的历史：Grady Booch 1991 年首次提出 → Kent Beck 1996 年发展为 XP 核心实践 → Martin Fowler 2006 年文章引发工具大爆发 → 现代 GitHub Actions / GitLab CI（Devopedia）。

现代 CI/CD 管道阶段：

Source → Build → Test → Security Scan → Deploy to Staging → Acceptance Tests → Deploy to Production

Martin Fowler 的经典论断：“持续集成不能消除 bug，但它让 bug 变得极其容易发现和修复。“

6. 依赖管理 + Lockfile

Lockfile 革命确保了构建可重复性。Cargo 在每次成功构建后将确切版本保存到 Cargo.lock——“如果它在你的机器上编译通过，那它在每台其他机器上也应该编译通过”。

OpenAI 团队偏好”无聊的技术”——选择 API 稳定、可组合、在训练数据中有充分表示的依赖。在某些情况下，让 agent 重新实现部分功能比处理不透明的上游行为更经济（InfoQ, 2026）。

7. 文档系统（Docs-as-Code）

在 Harness Engineering 中，文档不仅给人类看——它是 agent 的”眼睛”。

关键原则：“从 agent 的视角来看，它访问不到的任何东西都不存在”——存在于 Google Docs、Slack 对话或人脑中的知识对系统来说是不可见的。仓库必须是唯一的真实来源（single source of truth）（Tony Lee, 2026）。

文档的角色是提供 “A Map, Not a Manual”（地图而非手册）：简洁的架构概览，展示项目结构和极少变化的不变量。

二、AI 编码代理治理框架

1. CLAUDE.md / 项目指令文件

CLAUDE.md 是 Claude Code 在每次会话开始时自动读取的特殊文件，充当 AI 与代码库之间的”入职指南”。采用最佳实践的开发者达到满意结果所需的迭代次数减少了 35%（UX Planet）。

应该包含的内容：

  • Claude 无法猜到的 Bash 命令（如 npm run test、npm run build）
  • 与默认不同的代码风格规则
  • 测试指令和偏好的测试运行器
  • 仓库规范（分支命名、PR 约定）
  • 项目特定的架构决策

不应该包含的内容：

  • Claude 可以通过阅读代码推断的信息
  • 标准语言惯例
  • 频繁变化的信息

关键原则：

  • 保持简洁——对每一行问”删除这一行会导致 Claude 犯错吗？”
  • 签入 Git，让团队共享和迭代
  • 使用 .claude/rules/ 模块化规则目录替代臃肿的单一文件
  • 规则文件支持路径作用域（paths frontmatter），只在处理匹配文件时加载

多级层次：

位置作用
~/.claude/CLAUDE.md全局适用于所有会话
./CLAUDE.md（项目根目录）签入 git，与团队共享
父目录对 monorepo 有用
子目录按需加载

跨工具对比：

工具指令文件特色
Claude CodeCLAUDE.md@path 导入、.claude/rules/ 模块化
Cursor.cursor/rules/*.mdc.mdc 含 frontmatter，最成熟
GitHub Copilot.github/copilot-instructions.md企业级组织策略

2. Hooks 系统

Hooks 是在 Claude 操作流程特定节点自动运行的 shell 命令。关键区别：CLAUDE.md 指令是建议性的，而 Hooks 是确定性的（Claude Code Hooks 文档）。

完整的 Hook 事件列表：

事件触发时机可阻断？
SessionStart会话开始或恢复否
UserPromptSubmit用户提交提示是
PreToolUse工具执行前是
PostToolUse工具执行成功后否
Stop主代理完成响应是

四种 Handler 类型：

  1. Command：执行 shell 命令
  2. HTTP：向远程端点发送 POST 请求
  3. Prompt：发送给 Claude 进行单轮评估
  4. Agent：生成子代理进行深度验证

退出码 2 = 阻断性错误——Claude 取消待处理的操作。每个安全 hook 必须使用退出码 2。

配置示例：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": ".claude/hooks/validate-bash.sh", "timeout": 5 }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{ "type": "command", "command": ".claude/hooks/lint.sh" }]
      }
    ]
  }
}

最佳实践：

  • 保持 hooks 快速（<2 秒，理想 <500ms）
  • 优先使用 PreToolUse 做策略守卫，PostToolUse 做清理
  • 配置编辑不会热加载——Claude 在会话开始时快照 hooks

3. MCP（Model Context Protocol）

MCP 被比喻为”AI 应用的 USB-C”——一个通用连接器，允许任何 AI 模型通过单一标准化接口与任何工具通信。

关键里程碑：

  • 2024年11月：Anthropic 发布 MCP 开放标准
  • 2025年3月：OpenAI 采用 MCP
  • 2025年5月：GitHub 和 Microsoft 加入 MCP 指导委员会
  • 2025年12月：捐赠给 Linux Foundation 下的 AAIF
  • 截至 2026年2月：6,400+ MCP 服务器，SDK 月下载量 9,700 万+（Pento）

三种作用域： local（默认）、project（.mcp.json，与团队共享）、user（所有项目）

上下文开销： 每个 MCP 服务器增加 500-2,000 token。建议从 3-5 个服务器开始。

4. 安全与权限控制

权限规则评估顺序： deny → ask → allow

四种权限模式：

  1. Normal mode（默认）：每次敏感操作需确认
  2. Plan mode：只读访问
  3. Auto-accept mode：自动批准文件读写
  4. Bypass mode：移除所有确认

沙盒化： 基于 OS 级原语（Linux bubblewrap / macOS Seatbelt），安全地减少了 84% 的权限提示（Anthropic）。

已知安全漏洞（已修复）：

  • CVE-2025-59536（CVSS 8.7）：通过 Hooks 实现远程代码执行
  • CVE-2026-21852（CVSS 5.3）：通过恶意 ANTHROPIC_BASE_URL 窃取 API 密钥
  • 两者在 Claude Code 2.0.65+ 已修复

5. Memory 和上下文管理

两种跨会话机制：

  1. CLAUDE.md 文件：手动编写的指令
  2. Auto Memory：Claude 根据纠正和偏好自动写的笔记

上下文窗口管理： 200,000 token 硬上限

  • 0-50%：自由工作
  • 50-70%：注意
  • 70-90%：运行 /compact（减少 60-70% token）
  • 90%+：运行 /clear

6. Skills 和自定义工作流

推荐的项目配置结构：

your-project/
├── CLAUDE.md
├── .mcp.json
└── .claude/
    ├── settings.json
    ├── settings.local.json
    ├── rules/
    │   ├── code-style.md
    │   ├── testing.md
    │   └── security.md
    ├── skills/
    │   ├── fix-issue/SKILL.md
    │   └── deploy/SKILL.md
    ├── agents/
    │   └── security-reviewer.md
    └── hooks/
        ├── validate-bash.sh
        └── lint.sh

三、行业实践

Google：Monorepo、Bazel 与 Readability 制度

  • 超大型 Monorepo（Google3）：95%+ 的代码在一个仓库，所有工程师采用 Trunk-Based Development（Pragmatic Engineer）
  • Bazel 构建系统：Hermetic builds + 细粒度依赖追踪 + 沙箱化执行 + 分布式构建。被 Google、Stripe、Dropbox、Pinterest、SpaceX、Nvidia 等公司使用
  • Readability 制度：标准化的全公司导师制代码审查流程，源自第三号员工 Craig Silverstein。每个 PR 需要三种审批——LGTM（逻辑）、Code Owners（所有权）、Readability（规范）（Engineers Codex）

Meta/Facebook：源码控制、构建系统与 AI 测试

  • Sapling 源码控制：基于 Mercurial 重新设计，EdenFS 虚拟文件系统避免全仓库检出（Engineering at Meta）
  • Buck2 构建系统：Rust 编写，核心与规则完全分离，开箱支持 11 种语言，构建速度是 Buck1 的两倍（Engineering at Meta）
  • LLM 变异测试（ACH）：隐私工程师接受了 73% 的 LLM 生成测试（InfoQ）
  • JiTTesting：PR 进入生产前即时生成回归测试（Engineering at Meta）
  • SapFix：自动化 Bug 修复，从故障检测到发布修复中位时间仅 69 分钟

Netflix：不可变基础设施与渐进式交付

  • Nebula：基于 Gradle 的定制化插件集处理构建，CI 使用 Jenkins（25 个 master）（Netflix Tech Blog）
  • 不可变服务器模式：每次部署创建新 AMI，生产实例在线修改被强烈反对
  • Spinnaker：Netflix 创建的持续交付平台，内置 blue/green 和 canary 策略
  • Kayenta：Google + Netflix 联合开发的自动化金丝雀分析（Netflix Tech Blog）

Stripe：API 卓越性与开发者生产力

  • API 版本化：基于日期的滚动版本，自 2011 年保持与每个版本的兼容性（Stripe Blog）
  • Sorbet：Ruby 静态类型检查器，覆盖 1500 万行代码
  • 大规模迁移：一个 PR 将 370 万行代码从 Flow 迁移到 TypeScript

Uber：微服务测试策略

  • DOMA：2200 个微服务分类到 70 个领域（Uber Engineering）
  • BITS：后端集成测试策略，每千次代码变更事故数减少 71%（Uber Blog）
  • 影子测试：每秒约 2000 万次评估，匹配率超过 99.999%

四、前沿趋势（2025-2026）

AI 代码审查爆发

市场从 2024 年的 5.5 亿美元爆发增长至 2025 年的 40 亿美元（Qodo）。

工具定位关键特性
CodeRabbit轻量级 PR 审查46% 运行时 Bug 检测准确率，$12-24/月/开发者
Qodo企业级跨仓库审查多仓库上下文引擎，$30-45/月/用户

使用 AI 代码审查的团队将审查时间减少 40-60%，同时提高缺陷检出率（Qodo）。

多代理协作成为常态

2026 年 2 月，所有主要工具集中发布多代理能力。Gartner 报告多代理系统查询激增 1445%（AI Automation Global）。

架构模式从”独立助手”演变为专业化代理团队——Planner、Architect、Implementer、Tester、Reviewer。

DORA 2025 悖论

  • AI 多完成 21% 的任务，多合并 98% 的 PR
  • 但组织级交付指标保持平稳——75% 的工程师使用 AI 工具，但大多数组织看不到可衡量的绩效提升
  • AI 放大现有系统质量——拥有成熟 DevOps 的组织收益更大，基础差的组织反而被放大问题（DORA 2025）

供应链安全

  • 开源恶意软件检测同比增长 73%（ReversingLabs）
  • SBOM 从合规检查表演变为可操作的安全资产
  • EU CRA 强制要求 SBOM 作为市场准入条件
  • 达到 SLSA Level 2 可在数周内完成（cosign + Syft + Kyverno + GUAC + GitHub OIDC）

新兴工具

工具类型关键特性
Turborepo构建编排Rust 核心，减少 70% 构建时间
Nx构建智能平台AI Agent 集成（一键配置 CLAUDE.md），文件级 affected 分析
Dagger可编程 CI/CDDocker 创造者构建，管线即代码（Go/Python/TS）
Devbox开发环境Nix 的友好界面，40 万+ 包版本
mise版本管理asdf 的 Rust 替代，零开销调用，原生安全验证

五、实操指南：最小可行 Harness（优先级排序）

P0：绝对必须（第 1-2 周，投入产出比最高）

步骤组件投入时间
1AGENTS.md / CLAUDE.md：Build/Test 命令、架构概览、安全规则、编码约定（~100 行）2-4 小时
2可复现的开发环境：Devbox / Docker / Nix，支持 per-worktree 隔离1-2 天
3机械化 CI 检查：Linter + Formatter + 类型检查 + 依赖规则1-2 天
4版本管理：采用 mise 统一管理所有语言版本 + 环境变量 + 任务运行2 小时
5进度追踪：每个会话结束时 git 提交 + progress 文件2 小时
6安全护栏：最小权限凭证、受控出口、审计日志半天

P1：最好有（第 3-4 周）

组件附加价值
AI 代码审查（CodeRabbit/Qodo）审查时间减少 40-60%
结构化日志 + 可观测性运行时行为验证（非仅静态分析）
构建编排（Turborepo/Nx）并行构建、缓存优化
浏览器自动化集成Chrome DevTools Protocol，端到端验证

P2：锦上添花（第 5 周+）

组件适用场景
多代理编排（Claude Code Teams / Cursor 并行代理）复杂任务并行处理
AI 测试生成（Diffblue / Qodo）覆盖率提升，自动回归检测
供应链安全（SBOM / Sigstore / SLSA）受监管行业
Policy as Code（OPA / Kyverno）K8s 生产环境
内部开发者门户（Harness IDP / Port.io / Backstage）100+ 人工程团队

六、OpenAI 的五大 Harness Engineering 原则

  1. Agent 看不到的东西就不存在：将所有决策推入仓库中的 markdown 和 schema
  2. 问”缺少什么能力”而非”agent 为什么失败”：关注环境而非 prompt
  3. 机械化执行优于文档记录：通过 linter 和自动化测试而非书面指南
  4. 给 Agent 装上眼睛：将监控和 UI 工具直接连接到 agent 运行时
  5. 地图而非手册：提供简洁的架构概览而非详尽文档

七、关键成功因素

  1. AI 放大效应：先建立坚实的工程基础再引入 AI 工具——否则 AI 只会放大现有的混乱（DORA 2025）
  2. 熵管理：代理忠实复制所有模式（包括坏的），必须通过自动化清理和 CI 强制执行管理模式漂移
  3. 注意力稀缺性反转：人类注意力成为瓶颈而非计算资源，偏好快速检测 + 低成本回滚
  4. 稳定性优先于速度：DORA 十年研究的核心结论
  5. 文化与技术并重：工程化治理本质上是组织变革

核心结论

编写好代码的时代正在结束，设计好环境的时代已经开始。

Harness Engineering 的本质：设计让代码能够被可靠地编写、测试、集成和部署的环境，而不是编写代码本身。更强大的模型让 harness engineering 变得更重要而非更不重要——更多的自主性需要更好的护栏。

Graph View