---

一. Harness Engineering 简介

       Harness Engineering 是构建用于 模型执行、评测、实验管理和结果分析的基础设施（evaluation / testing harness） 的工程实践。它创建了一个统一的环境（通常称为评估或测试工具），可以跨不同的AI代理进行自动化测试和性能基准测试。

       更通俗一点说，AI Agent 是单独的个体工作者，Harness Engineering 就是将他们聚集在一起的平台。它将复杂的业务任务分解为特定的功能，并将其分配给不同的代理，最终自动化和简化整个工作流程。

---

二. 为什么要用 Harness

• 无论底层模型能力如何提升，AI Agents 在实际研发流程中存在的四个结构性缺陷。这些缺陷源于 LLM 的工作机制，无法通过单一手段彻底消除：

  • 风险一

    规则遗忘
            项目规范以自然语言写入的 Rule 文件。但随着上下文窗口填充率升高，Agents 对规则的遵守度显著下降——上下文越复杂，规则衰退越明显。

  • 风险二

    约束规避
            Agents 天然倾向于推动任务完成而非严格遵循约束。常见表现为”等价替换“、”特殊情况豁免“、”历史原因保留“等看似合理的绕行策略。

  • 风险三

    自审失效
            单一 Agents 同时承担多种业务角色时，天然倾向于确认自身输出的正确性，可能会导致其中角色的业务输出结果不准确。比如单个 Agents 同时承担需求分析、编码实现、测试验证时，可能只会注重自身输出内容，而非发现并上报问题。

  • 风险四

    虚报完成
            Agents 可能再未完整执行验证步骤的情况下报告”测试通过“、”构建成功“。在缺少真实验证的情况下，人工难以区分真实完成与幻觉式完成。

---

三. 核心架构：Harness 五层体系

Harness 五层体系，是让 AI Agents 协作办公的核心架构，如下为架构各个层级与模块之间的对应关系表

Harness 五层体系 (基础设施)	包含的业务概念 (上层逻辑/工具)	核心作用
约束层 (Constraint)	Rules、Skills、Specs、Codebase Guide、Agents	划定红线、提供SOP、注入业务与工程知识、角色制衡
状态层 (State)	Memory	解决失忆、持久化上下文与任务进度
工具层 (Tool)	MCP Server、Workflow、Scripts	标准化接口、任务编排、赋予 AI 动手能力
校验层 (Validation)	Scripts(硬校验)、Quality	机器验证、质量把控
环境层 (Environment)	(无直接对应，底层支撑)	沙箱隔离、安全兜底

1. Harness 架构的核心理解

        在 Harness 架构中，系统被划分为多个层级（如约束层、状态层等），每个层级下包含多个职责明确的模块（如 Rules 行为约束、Agents 角色制衡等）。为了支撑这一架构，Harness 采用了“基于约定的目录结构（Convention over Configuration）”设计，即每个模块的实现文件必须严格存放在对应的标准目录中。

• 这种高度结构化的物理路径映射，主要为了实现两大核心工程目标：

  • 实现“渐进式披露”与按需加载（Progressive Disclosure）：

            通过将庞大的知识库拆分到不同的目录和文件中，AI 在启动时只需加载全局入口文件（如 AGENTS.md）。
    
           当任务触发特定意图时，系统会根据路径去对应目录中读取所需的模块文件。这有效避免了将所有规范一次性塞入上下文导致的 Token 溢出，确保了 AI 的专注度与响应效率。

  • 实现“作用域隔离”与上下文安全（Scope & Context Isolation）：

            标准化的目录结构天然支持了配置的作用域划分。系统可以清晰地区分项目级配置（随代码库提交，约束整个团队）和用户级配置（存放在本地全局目录，仅约束个人偏好）。这种物理上的隔离确保了 AI 在不同项目、不同用户之间切换时，能够精准匹配相应的规则，防止上下文污染和越权操作。

• Harness 架构要活学活用

  如上所示，Harness 的五层架构体系中包含了众多功能模块（如：Skills、Agents等）。但在实际落地时，我们无需全量部署所有模块。最佳实践是根据具体的业务场景和需求进行按需配置，仅引入当前业务所需的模块，以实现系统的最优效能。

  • 举例如下

    如果我们需要在一个自动化测试的项目中引入 Harness 架构，那么大概率就不需要开发者这个角色，因为项目分离的缘故，到测试环节时，功能大概率已经开发完成了，我们只需要在现有功能的基础上进行功能检查即可。

---

2. 约束层 (Constraint)

• 核心作用：“立规矩”、“定角色” 和 “注入领域知识”。

  这一层的目的是解决 AI 瞎写代码、风格不一致的问题。
  

  • 实现方式：在项目根目录创建一个 AGENTS.md（或 CLAUDE.md）文件。AI Agent 启动时会自动读取该文件并注入系统提示词。
  • 具体配置：在文件中明确写出技术栈、代码风格（如“单函数不超过50行”、“禁止使用 print 调试”）、以及安全红线（如“禁止修改数据库迁移文件”）。
  • 进阶手段（自定义 Linter） ：目前了解程度不多，先简单了解，后续补充
    • Linter：代码静态检查工具

• 约束层有如下组成部分

  • Rules（行为约束） ：给 AI 制定规则，告诉它什么不可以做以及必须做什么。

  • Skills（标准操作） ：给 AI ”经验手册“，告诉它具体该怎么做

  • Agents（角色制衡） ：通过 Agents 定义不同的 Agent（如“生成者”与“审核者”），利用角色之间的相互制衡来实现更高级别的约束。

  • Specs（需求规范） ：告诉 AI 测试用例必须覆盖哪些业务场景和验收标准。

  • Codebase Guide（代码库指南） ：告诉 AI 当前项目的架构、目录结构和历史技术债，防止 AI 生成与现有架构冲突的代码。

  Rules（行为约束）

  Skills（标准操作）

  Agents（角色制衡）

  Specs（需求规范）

  Codebase Guide（代码库指南）

---

3. 状态层 (State)

状态层 (State) ➡️ 包含：Memory
状态层的核心是“解决失忆”和“上下文管理”，它完美对应了 Memory：
Memory（工程记忆）：状态层通过 Git 提交记录、PROGRESS.md 进度文件、向量数据库等手段，将 AI 的短期记忆转化为长期、可追溯的工程记忆。没有状态层，Memory 就只是虚无缥缈的 Prompt 上下文；有了状态层，Memory 就成了可以跨会话、跨任务复用的工程资产。

4. 工具层 (Tool)

工具层 (Tool) ➡️ 包含：MCP Server、Workflow、Scripts
工具层的核心是“赋予 AI 动手能力”和“连接外部世界”，它对应了执行层面的三个概念：
MCP Server（Model Context Protocol Server）：这是工具层最核心的底层实现。MCP 提供了标准化的协议，让 AI 能够安全地调用外部工具、读取数据库或访问文件系统。
Workflow（工作流）：工具层的编排逻辑。它决定了 AI 在什么时机、以什么顺序调用哪些 MCP Server 或脚本。
Scripts（脚本）：工具层的物理载体。AI 调用的 Shell 命令、Python 脚本、API 接口，都是 Scripts 的具体表现。

5. 环境层 (Environment)

环境层 (Environment) ➡️ 无直接对应（但支撑所有层级）
环境层（沙箱隔离、Docker、依赖锁定）是纯粹的基础设施。它没有直接对应的业务概念，但它是上述所有概念（MCP Server、Scripts、Workflow）能够安全运行的物理保障。没有环境层，Scripts 可能会删库，Workflow 可能会崩溃，Rules 也就失去了意义。

6. 校验层 (Validation)

校验层 (Validation) ➡️ 包含：Scripts（硬校验）、Quality
校验层的核心是“守住质量底线”和“提供客观反馈”，它对应了验证层面的概念：
Scripts（硬校验）：Lint 检查、单元测试、安全扫描等，都是通过具体的 Scripts 来执行的。这里的 Scripts 充当了“无情的机器裁判”，提供非黑即白的硬校验。
Quality（质量管控）：这是校验层的最终目标。无论是硬校验（Scripts）还是软校验（AI 评审），最终都是为了达成 Quality 管控的目的。

四. 全链路落地步骤与对应技术栈