Harness Engineering：打造 AI 编程助手的工作环境

我在多个项目中积极使用 AI 智能体（Cursor、Claude Code 等）。最初，让智能体来写代码这件事本身就足够令人惊叹。但随着我将这些工具更深地集成到实际项目中，我不断遇到反复出现的问题。

每次打开新会话，智能体就会忘记项目的约定规范

它今天重复的错误，正是我们昨天已经解决过的

智能体生成的代码质量在不同的会话之间波动剧烈

在管理多个项目时，我必须为每个项目重复相同的设置

这些问题的根源并不在于智能体缺乏智能，而在于智能体所处的环境没有得到正确的配置。随着 2026 年的到来，这一问题在整个行业蔓延开来，并开始被系统化地冠以"安全工程（Harness Engineering）"的名称。

在首次将安全工程应用于公司项目后，我亲身体验到了它的效果，并决定将同样的结构应用于个人项目。在这个过程中，我感到需要一份"能够快速将任何项目转换为安全工程结构的参考文档"，这促使我写下了本指南。

本指南不仅解释安全工程的概念，还涵盖了根据项目类型应该应用什么。从个人博客到多智能体自动化系统，本指南结构化地帮助你设计一个与项目规模和复杂度相匹配的安全工程结构。

1. 什么是安全工程（Harness Engineering）？

安全工程是一门确保 AI 智能体安全可靠运行的基础设施设计学科。"Harness"（安全工程）一词源自马具，用于控制马匹的力量，引申为引导 AI 智能体强大但不可预测的力量朝着正确方向发展的系统。

"模型是商品。安全工程才是护城河。" — harness-engineering.ai

为什么现在是做安全工程的时机？

2025 年是证明 AI 智能体能够编写代码的一年

2026 年是我们认识到关键不在于智能体本身、而在于安全工程的一年

LangChain 仅通过改变安全工程（不修改模型本身）就将 Terminal Bench 2.0 分数从 52.8% 提高到 66.5%。OpenAI Codex 团队构建了超过 100 万行代码的生产级应用程序，却没有手动编写一行代码。

与相关概念的对比

2. 安全工程的核心组件

2-1. 上下文工程（Context Engineering）

确保智能体在正确的时间拥有正确的信息。

• 仓库级本地文档（架构规范、API 规范、样式指南）
• 编码项目特定规则的 CLAUDE.md 文件（或 AGENTS.md）
• 互联的设计文档（linter 自动验证链接有效性和文档新鲜度）
• 智能体可访问的观测数据（日志、指标、追踪）
• 智能体启动时的目录结构映射
• CI/CD 管道状态和测试结果

核心原则：从智能体的角度来看，任何在上下文中无法访问的东西都不存在。Google Docs、Slack 讨论串或人脑中的知识对系统是不可见的。仓库必须是唯一的事实来源。 — OpenAI

2-2. 架构约束（Architectural Constraints）

不要告诉智能体"写好代码"，而是要机械地强制执行好代码的标准。

Types → Config → Repo → Service → Runtime → UI

每一层只能从其左侧的层导入，通过结构化测试和 CI 验证来强制执行。

约束执行工具：

• 确定性 linter — 自动标记违规的自定义规则
• 基于 LLM 的审计器 — 审查其他智能体代码的智能体
• 结构化测试 — 针对 AI 生成代码的架构测试
• Pre-commit 钩子 — 代码提交前的自动检查

矛盾的是，约束解决方案空间反而能提高智能体的工作效率。当智能体可以生成任何东西时，它们会浪费 token 探索死胡同。当安全工程定义了清晰的边界时，智能体能够更快地找到正确的解决方案。 — NxCode

2-3. 护栏（Guardrails）

在技术层面控制 AI 智能体的输入和输出，以预防性地阻止超出设计目的范围的行为。

• 输入阶段：检测 / 阻止提示注入或机密信息泄露
• 输出阶段：自动过滤有害内容或幻觉

2-4. 验证循环（Verification Loops）

在允许进入下一步之前，在每个步骤验证智能体工作的结构。这是安全工程中投资回报率最高的组件。

# 验证循环模式（伪代码）
def run_agent_with_verification(task, tools, cost_ceiling):
    context = assemble_context(task)
    total_cost = 0

    while not task.is_complete():
        action = agent.plan(context, tools)
        result = execute_tool(action)

        verification = verify_output(result, action.expected_schema)
        if not verification.passed:
            if verification.retry_recommended:
                result = retry_with_backoff(action, max_retries=3)
            else:
                return TaskResult(status="failed", reason=verification.reason)

        total_cost += result.tokens_used
        if total_cost > cost_ceiling:
            return TaskResult(status="budget_exceeded", partial=context)

        context = update_context(context, result)

    return TaskResult(status="complete", output=context.final_output)

"最高投资回报率"意味着相对于投入的努力效果最大。在所有安全工程组件中，验证循环以最少的努力提供了最大的质量改进。

• 实施成本：每步额外 50-150ms 延迟，几十行代码
• 效果：任务完成率从 83% 提升到 96%（不改变模型或提示词）

如果你正在为第一次构建安全工程，并且疑惑"我应该先构建什么？"——从验证循环开始，它具有最高的性价比。

2-5. 成本封套管理（Cost Envelope Management）

设置每任务预算上限，由安全工程强制执行，无论智能体的意图如何。

成本封套不仅仅是财务控制——它们也是可靠性信号

任务达到其预算上限意味着它运行异常（上游响应错误、上下文漂移、工具集成错误等）

2-6. 熵管理（Entropy Management）

定期清理在 AI 生成的代码库中随时间累积的熵。

• 文档一致性智能体 — 验证文档与当前代码匹配
• 约束违规扫描器 — 重新扫描已通过之前检查的代码
• 模式执行智能体 — 识别 / 修复与既定模式的偏差
• 依赖审计器 — 追踪 / 解决循环或不必要的依赖

2-7. 上下文积累（Accumulated Context）

一种跨仓库内会话持久累积知识、发现的模式和正在进行的决策的结构。由于智能体本质上是无状态的，所有上下文在会话结束时都会消失。安全工程正是为了弥补这种"失忆症"。

上下文的三条时间轴：

静态上下文在项目创建时编写，动态上下文在运行时自动生成。累积上下文介于两者之间——一种随着智能体工作累积而增量增长的知识层。

累积上下文的实现模式：

<project root>/
├── docs/
│   └── decisions/                    # 架构决策记录（ADR）
│       ├── 001-static-site-generator-choice.md
│       └── 002-deployment-strategy.md
├── .memory/                          # 智能体记忆
│   ├── learnings.md                  # 模式、失败原因、实践知识
│   ├── current-focus.md              # 当前兴趣、优先级
│   └── session-notes/                # 每个会话的摘要（可选）
│       └── 2026-04-04.md

工具原生记忆支持：

Claude Code 有自动记忆功能，会自动保存会话中发现模式，但 Cursor 需要通过 .cursor/rules/ 和 Notepads 进行手动知识管理。使用不依赖任何特定工具的基于仓库的记忆（上面的 .memory/ 模式）可以从任何工具访问。

最佳实践：

• 记录失败原因和解决方案，这样智能体"不会重复同样的错误"
• 在结束会话前，养成将"本会话学到了什么"提交到仓库的习惯
• 累积上下文也需要熵管理——定期清理过时或失效的笔记

2-8. 可观测性与评估（Observability & Evaluation）

• 可观测性：结构化地追踪智能体做了什么、为什么做、以及每一步发生了什么
• 评估：自动化管道，持续根据定义的标准测量智能体性能

3. 安全工程应用级别

安全工程的应用深度因项目规模和复杂度而异。

Level 1：基础安全工程（个人开发者）

• 包含项目约定的 CLAUDE.md 文件（Cursor 通过 .cursor/rules/ 引用）
• 用于 linting 和格式化的 pre-commit 钩子
• 智能体可用于自我验证的测试套件
• 清晰一致的目录结构和命名约定
• 用于跨会话知识积累的智能体记忆（.memory/）

适用于个人博客、文档站、个人工具和副项目，在这些场景中单个 AI 智能体直接由用户指令。

Level 2：团队 Harness（小型团队）

• CI 强制执行的架构约束
• 通用任务的共享提示词模板
• 由 linter 验证的文档即代码
• 专门针对 AI 智能体生成 PR 的代码审查清单
• AI 智能体角色边界和变更范围限制

适用于多人在同一仓库使用 AI 智能体的场景。重点在于防止 AI 智能体之间的冲突，并将代码质量差异降至最低。

Level 3：生产 Harness（工程组织）

• 自定义中间件层（循环检测、推理优化）
• 可观测性集成（AI 智能体读取日志和指标）
• 定时运行的熵管理 AI 智能体
• Harness 版本控制与 A/B 测试
• AI 智能体性能监控仪表板
• AI 智能体死锁升级策略

适用于 AI 智能体自主执行流水线、大规模对接外部 API，且 AI 智能体判断错误直接导致财务/运营损失的 系统。

4. 将 Harness Engineering 应用于你的项目

4-1. 服务特性分析

在设计 Harness 之前，先通过以下问题识别目标项目的核心特性：

基于这些答案，将项目分类为以下类型之一，以确定需要应用哪些阶段：

4-2. 风险识别

根据项目特性，识别无 Harness 运行可能发生的风险：

对于 A 类（个人项目），风险 2、7、8 最相关，Phase 1~2 Harness（规则文件、pre-commit hook、AI 智能体记忆）就足够了。随着向 C~D 类推进，风险 1、3~6 变得更加关键，需要 Phase 3+ 的 Harness。

4-3. Harness Engineering 设计

将项目仓库配置为 AI 智能体的单一事实来源。推荐的目录结构：

<project root>/
├── CLAUDE.md                          # AI 智能体行为规则入口
├── ARCHITECTURE.md                    # 顶层系统架构图
├── .cursor/
│   └── rules/
│       └── general.mdc                # 将 Cursor 连接到参考的 CLAUDE.md
├── docs/
│   ├── design-docs/                   # 功能设计文档
│   ├── api-specs/                     # API 端点规范
│   ├── references/                    # SDK/框架参考
│   └── quality/                       # 质量标准

将 CLAUDE.md 维护为目录表，而非百科全书（控制在约 100 行）

将所有设计决策记录为仓库内的文档（不用 Slack / Google Docs）

从 AI 智能体的视角看，无法搜索到的信息等于不存在

适用于：B 类及以上项目（团队 / Web 应用）。对于单 AI 智能体个人项目，基于 glob 的规则文件和 pre-commit hook 已足够。

根据项目特性，明确界定 AI 智能体的行为边界。

1）每个 AI 智能体的角色边界

明确界定每个 AI 智能体可以做什么和不能做什么：

<Agent Name> (<Role>)
  - Allowed: <此 AI 智能体可执行的任务列表>
  - Forbidden: <此 AI 智能体绝对不能执行的任务列表>

设计角色边界的核心原则：

最小权限：每个 AI 智能体仅拥有其角色所需的最小权限

隔离：分离数据查询/分析 AI 智能体与执行/修改 AI 智能体

需要审批：高风险操作（财务影响、数据变更、外部系统调用）必须经过审批阶段

2）输入/输出护栏

输入：外部数据源响应验证、上下文隔离验证

输出：变更范围限制、幻觉过滤

流水线：阶段间数据 Schema 验证、标识符一致性检查

3）任务成本上限

按任务类型定义成本上限（每个项目单独配置）：
  - 简单查询/分析：baseline × 1
  - 复杂分析/诊断：baseline × 2
  - 完整流水线执行：baseline × 10
  - 报告生成：baseline × 5
  - 涉及外部 API 调用的任务：baseline × 3

→ 超出上限时：停止任务 + 告警 + 升级

应用层级：所有项目类型均可使用，但实现深度有所不同。

A 类（个人）：pre-commit hook 和构建验证作为自我验证。

B 类（团队）：将自动化测试、lint 和 PR 审查集成到 CI/CD。

C~D 类（自动化 / 企业）：需要 AI 智能体自我验证 + 人工在环（Human-in-the-Loop）的双层/三层结构。

推荐使用双层结构实现验证循环：

1）AI 智能体自我验证

流水线步骤执行
  → AI 智能体生成结果
  → 自我验证结果（数据完整性、Schema 合规性）
  → 失败时自动重试（最多 3 次）
  → 成功后传递到下一步

2）人工验证（Human-in-the-Loop）

高风险操作通过运维工具请求审批

操作员批准/拒绝

被拒绝时，将反馈传递给 AI 智能体以建议替代方案

3）输出验证循环

同样将验证循环应用于 AI 智能体生成的输出：

AI 智能体创建草稿 → 验证（自动化或人工） → 被拒绝时自动重写

适用于：C 类及以上项目（多 AI 智能体 / 自动化）。对于用户手动指挥单个 AI 智能体的项目不必要。

对于多 AI 智能体系统，将中间件应用于流水线：

流水线执行请求
  → ContextIsolationMiddleware   （上下文隔离，防止数据污染）
  → CostEnvelopeMiddleware       （成本上限检查，超限阻断）
  → LoopDetectionMiddleware      （防止重复任务处理）
  → InputValidationMiddleware    （输入数据完整性验证）
  → [AI 智能体执行]
  → OutputValidationMiddleware   （结果 Schema 验证、变更范围限制）
  → ApprovalGateMiddleware       （风险评估，高风险时路由到审批）
  → ExecutionAuditMiddleware     （执行历史记录）

适用于：C 类及以上。对于手动使用的项目，AI 智能体记忆和 Git 历史提供了足够的可观测性。

范围：所有项目类型均可使用，但范围有所不同。

A~B 类：定期清理 .memory/learnings.md、链接验证即可。

C~D 类：专用 AI 智能体定期执行质量审计。

[定期任务 — 每个项目按需选择/配置]
  - Prompt 漂移检测器：监控系统提示词与实际输出之间的一致性
  - 数据完整性检查器：验证所引用的数据/设置仍然有效
  - 输出质量审计：验证自动生成的结果基于实际数据
  - 工具函数一致性检查：验证工具定义与外部服务 Schema 同步

4-4. Harness Engineering 应用路线图

你不需要按顺序应用所有阶段。根据项目类型分类，选择并仅应用你需要的阶段。

A 类 — 个人博客 / 文档站 / 个人工具

Phase 1: CLAUDE.md（或 .cursor/rules/）、ARCHITECTURE.md、Pre-commit hooks
Phase 2: .memory/learnings.md、current-focus.md、docs/decisions/
         → 仅这两个阶段即可完成一个环境，
           使 AI 智能体持续理解项目并在会话间积累知识。

B 类 — 团队 Web 应用 / SaaS 后端

Phase 1~2:（与 A 类相同）
Phase 3: CI 强制执行的架构 lint、AI 智能体生成代码的 PR 审查清单、
         变更范围限制
         → 减少团队成员之间的代码质量差异，
           并防止过度的 AI 智能体变更。

C 类 — 多 AI 智能体自动化系统

Phase 1~3:（通过 B 类应用）
Phase 4: AI 智能体间数据隔离中间件、成本上限管理、
         死循环检测与自动停止
Phase 5: 定时任务的重复执行防护（幂等键）、
         外部 API 配额管理、失败重试策略
         → 实现"受控自主"。

D 类 — 生产级企业系统

Phase 1~5:（通过 C 类应用）
Phase 6: 实时仪表板、自动化熵管理 AI 智能体、
         AI 智能体输出 A/B 测试
Phase 7: 从重复模式中学习自动审批阈值、
         AI 智能体性能基准测试套件、
         Harness 配置版本控制与回滚
         → 构建可持续运营框架。

5. AI 智能体指令文件策略

"将 AI 智能体行为指令作为 markdown 放在仓库根目录"这一模式已成为事实标准。然而，每种工具识别的文件名各不相同：

用单一文件覆盖所有工具目前尚不可行。（截至 2026 年 4 月）

推荐策略：主指令文件 + 工具特定链接

根据你主要使用的 AI 工具选择主指令文件，让其他工具引用它：

模式 A：Claude Code 为主 + Cursor 为辅

CLAUDE.md                  ← 在此编写实际规则
.cursor/rules/general.mdc  ← "参见 CLAUDE.md"

模式 B：Cursor 为主 + Claude Code 为辅

.cursor/rules/<project>.mdc  ← 在此写入实际规则（alwaysApply: true）
CLAUDE.md                     ← "参见 .cursor/rules/"

选择你主要使用的 AI 工具作为主工具，把规则写在主工具的指令文件中，让子工具的指令文件仅作为轻量级参考。这样你就只需在一处管理规则。

6. AI 智能体记忆与上下文漂移

AI 智能体记忆与上下文漂移是同一枚硬币的两面。

上下文漂移是指随着对话越来越长，AI 智能体逐渐偏离最初目标的现象。应对策略包括：

会话分离：使用多个短小的、目的明确的会话，而非一个长会话。Claude Code 的 /compact 命令或开启新的 Cursor 对话就服务于这一目的。

通过记忆文件连接：在会话结束时将关键结论写入记忆文件，在下一个会话中引用它们。

利用规则文件优先级：记录在 .cursor/rules/（alwaysApply）或 CLAUDE.md 中的规则在每一轮对话中都会被注入，无论会话多长，因此核心约束必须放在规则文件中。

[长会话中的上下文漂移]
  会话开始 →（规则 + 目标清晰）→ 工作推进 → ... →（上下文窗口饱和）
    → 初始规则的影响力 ↓ → 漂移发生

[基于记忆的短会话策略]
  会话 1：工作 → 将结论写入记忆 → 结束会话
  会话 2：加载记忆 →（规则 + 之前的结论清晰）→ 继续工作

对于开发者自行管理的项目（博客、个人项目等），在仓库内使用 markdown 文件（docs/decisions/、.memory/）比重量级自动化记忆系统更为实用。只需指示 AI 智能体"将发现内容添加到 .memory/learnings.md"，就足以建立跨会话的知识连续性。

7. Pre-commit Hooks 与 AI 智能体

Pre-commit hooks 是在 .git/hooks/pre-commit 注册的脚本，会在 git commit 时自动运行，并在违反规则时阻止提交。

驾驭工程的核心原则："能机械化强制执行的，就不要依赖口头传达。"

与 AI 智能体的间接沟通：Pre-commit hooks 无法直接调用 AI 智能体。不过，AI 智能体读取 hook 错误信息并响应的结构已经可以工作。OpenAI Codex 团队正是利用这一点——在 linter 错误信息中嵌入修复指令，这样 AI 智能体读取错误、修复它，然后重新提交。

# 友好 AI 的错误信息示例
Error: line 42 - unused variable 'tempData'.
Fix: Remove the variable or use it in the fetchResult() call below.
Refer to docs/conventions/no-unused-vars.md for examples.

驾驭工程是一门设计系统的学科——通过约束、反馈循环、文档和生命周期管理，使 AI 智能体变得可靠。

应用范围因项目特性而异。个人项目只需 Phase 1~2，多 AI 智能体自动化系统可能需要 Phase 5，企业系统则需要 Phase 7。

你不需要从一开始就拥有一套完美的驾驭系统——按阶段逐步构建，从基础上下文文档开始。

将 AI 智能体记忆设计为驾驭系统的组成部分。由于 AI 智能体本质上是无状态的，需要通过基于仓库的记忆来补充跨会话的学习和知识积累。

构建灵活的驾驭系统。随着模型能力提升，过度设计会成为负担——保持一种可拆卸的结构，易于移除。

如果你正在首次为项目构建驾驭系统，不知道从何入手——从验证循环开始，这是投资回报率最高的选择。

实战应用：为本博客应用驾驭系统

在撰写本指南的同时，我也为这个博客项目（Ted Factory）同步应用了一套驾驭系统。作为一个 Type A（个人 / 静态）项目，我只应用了 Phase 1~2，以下是我实际配置的内容：

Phase 1 — AI 智能体指令 + 验证自动化

.cursor/rules/ted-blog-common-rules.mdc：主要的 Cursor 规则（写作风格、front matter、内容结构）

CLAUDE.md：Claude Code 的轻量级参考文件

ARCHITECTURE.md：项目结构文档

scripts/pre-commit：Hugo 构建验证、front matter 必填字段验证、韩文 / 英文对称性验证

Phase 2 — AI 智能体记忆

.memory/learnings.md：工作中发现的模式和诀窍

.memory/current-focus.md：当前兴趣和优先级

docs/decisions/：架构决策记录（ADR）

应用这两个 Phase 后我注意到的变化：

开启新会话时，AI 智能体立即理解项目约定（写作风格、front matter 结构、部署方式）

Pre-commit hooks 在提交前捕获 front matter 遗漏和构建失败，消除了"部署后才发现问题"的情况

得益于 .memory/learnings.md 中积累的诀窍，AI 智能体不会重复同样的错误

将 Phase 1~2 应用到一个个人项目大约需要一天。作为回报，得到的稳定性和一致性提升是相当可观的。如果你正在积极使用 AI 智能体，我相信这是最值得做的第一件事。

你可以通读本指南并按部就班地执行，但还有一种更简单的方式：把本文的 URL 给你的 AI 智能体，让它为你的项目应用驾驭工程。

像 Cursor 和 Claude Code 这样的 AI 智能体可以读取 URL、理解内容，并相应地为你的项目配置驾驭系统。当我为这个博客应用驾驭系统时，也采用了类似的方式——向 AI 智能体展示一份驾驭工程设计文档，并让它来应用这套结构。

在你想要应用驾驭系统的项目中，用 Cursor 打开该项目，然后在对话中输入：

https://tedfactory.com/en/notes/essays/harness-engineering-guide/
Please apply harness engineering to this project based on the document above.

在你想应用驾驭系统的项目根目录运行 Claude Code，然后输入：

https://tedfactory.com/en/notes/essays/harness-engineering-guide/
Please apply harness engineering to this project based on the document above.