---
name: harness-engineering
description: "Master methodology for designing AI Agent work environments. Use when designing constraints, feedback loops, control planes, quality gates, or durable execution for Codex agents. Encodes the full Harness Engineering paradigm."
---

# Harness Engineering — 核心方法论

> Harness = 约束 + 反馈 + 控制平面 + 持久执行

## 🔧 四大核心组件

### 1. 约束系统 (Constraints)

定义 Agent 行为边界和输出质量。四层金字塔：

| 层级 | 内容 | 本项目落地 |
|---|---|---|
| **L1 架构约束** | 接口合约、包结构、命名规范、禁止模式 | AGENTS.md 铁律、全链路清单 |
| **L2 代码质量** | 圈复杂度、代码风格、类型提示、文档要求 | 编译门禁 + 语法检查 |
| **L3 安全约束** | 敏感信息检测、权限检查、输入验证 | 配置文件不可硬编码 |
| **L4 业务规则** | 领域逻辑、数据一致性、事务边界 | 全链路数据流验证 |

**关键原则：**
- 约束越底层越自动（编译检查），越上层越需要人工裁决
- 约束冲突时：安全 > 架构 > 质量 > 业务
- 约束应随信任度动态调整（信任度模型见下文）

### 2. 反馈系统 (Feedback Loop)

测试 → 失败 → Agent 修复 → 重测。分三层：

| 层级 | 速度 | 覆盖范围 | 失败处理 |
|---|---|---|---|
| **L1 编译检查** | <30 秒 | 语法、类型、签名 | 立即阻断，Agent 自行修复 |
| **L2 数据流验证** | <5 分钟 | 全链路字段、Mapper XML、DTO | Agent 修复，必要时上报 |
| **L3 人工审查** | 10-30 分钟 | 架构、设计、业务正确性 | 驳回 / 指导 / 批准 |

**反馈设计铁律：**
- 反馈必须可行动（指出：文件 + 行号 + 错误类型 + 修复方向）
- 反馈越及时越好（L1 即时 → L2 分钟 → L3 小时）
- 失败后先回滚到最近检查点，再重试

### 3. 控制平面 (Control Plane)

任务调度和 Agent 协调的核心机制：

```
┌─────────────────────────────────────────────┐
│  控制平面三层架构                            │
│                                             │
│  战略层（人类主导）                          │
│  ├── 设定目标、审批关键决策                   │
│  └── 异常升级处理                            │
│                                             │
│  战术层（Control Plane 主导）                 │
│  ├── 任务分解 + 规划                        │
│  ├── update_plan / checklist_write           │
│  └── 依赖协调 + 资源分配                     │
│                                             │
│  执行层（Agent 自主）                        │
│  ├── 代码生成、测试执行                      │
│  ├── apply_patch / exec_command              │
│  └── 错误恢复 + 检查点保存                   │
└─────────────────────────────────────────────┘
```

### 4. 持久执行 (Durable Execution)

长时任务的检查点恢复机制（详见 `$durable-execution` 技能）：

- 每个关键步骤保存检查点（`update_plan` 进度）
- 失败后从最新检查点恢复，不从头开始
- 幂等设计：同一操作重复执行结果一致

## 📋 工作流程

### 标准工作流：Plan → Generate → Validate → Review

```
收到任务
  │
  ├→ 1. 计划（Plan）
  │   ├── 分解步骤（checklist_write + update_plan）
  │   ├── 评估复杂度 / 风险
  │   └── 设定检查点里程碑
  │
  ├→ 2. 生成（Generate）
  │   ├── 并行探索（spawn_agent × N）
  │   ├── 约束优先：先加载 AGENTS.md 和相关规则
  │   └── 增量修改：只动必要文件
  │
  ├→ 3. 验证（Validate）
  │   ├── L1 编译检查（mvn compile / python3 -c py_compile）
  │   ├── L2 数据流验证（全链路检查清单）
  │   └── L3 人工审查（提交 diff 给人类）
  │
  └→ 4. 审查（Review）
      ├── 提交前 self-review（对照约束逐条检查）
      ├── 生成变更摘要
      └── 提交 / 推送
```

### 异常流程

```
编译失败 → 分析错误 → 撤销本次修改 → 从检查点恢复 → 重试
持续失败（3次） → 上报人类 → 等待指导
```

## 🎯 质量门禁（Quality Gates）

| 门禁 | 触发时机 | 通过条件 | 失败动作 |
|---|---|---|---|
| L1 编译 | 每次修改后 | 编译通过 | 立即修复 |
| L2 全链路 | 提交前 | 数据流完整 | Agent 修复 |
| L3 审查 | PR 提交 | 人类批准 | 驳回/指导 |
| L4 回归 | 合并后 | 无回归 | 紧急修复 |

## 🔐 分层信任模型

| 信任等级 | 特征 | 自动化程度 |
|---|---|---|
| L1 怀疑 | Agent 错误率高，人工逐行审查 | <20% 自动 |
| L2 试探 | Agent 稳定，抽样审查 | 40-60% 自动 |
| L3 信任 | Agent 可靠，关注结果 | 70-85% 自动 |
| L4 委托 | Agent 成为伙伴，人类管战略 | 90%+ 自动 |

**当前项目状态：** L2 试探级（编译门禁自动 + 全链路验证 + 人工终审）

## 📐 约束设计模式

### 1. 肯定模式 — 必须遵守的规则
```
必须实现 XXX 接口
代码覆盖率必须 > 90%
每个公共方法必须有类型提示
```

### 2. 否定模式 — 禁止的行为
```
禁止直接操作数据库（必须通过 Repository）
禁止硬编码密码/密钥
禁止使用 eval()
```

### 3. 边界模式 — 限制范围
```
圈复杂度 <= 10
每函数行数 <= 50
单文件修改 <= 5 个
```

### 4. 优先级模式 — 冲突处理
```
安全 > 架构 > 质量 > 性能 > 便利
```

## ⚠️ 常见陷阱

| 陷阱 | 表现 | 解决 |
|---|---|---|
| 过度约束 | Agent 被束缚，效率低 | 从最少约束开始，按需增加 |
| 约束冲突 | 多个规则互相矛盾 | 确定优先级顺序 |
| 反馈延迟 | 编译太慢，Agent 等待 | 分层测试，快速失败 |
| 控制不足 | Agent 自由度过高 | 增加检查点和门禁 |
| 跳过验证 | 直接提交未验证代码 | 门禁自动化，阻塞提交 |

## 📚 相关技能

- `$durable-execution` — 检查点、幂等性、事件溯源
- `$closed-loop-testing` — 质量门禁、测试策略、反馈循环
- `$constraint-design` — DSL 设计、策略模式、约束编排
- `$review-audit` — 审查工作流、审计追踪、合规检查
- `$full-chain-fix` — 全链路数据流修复（已安装）
- `$karpathy-guidelines` — 减少 LLM 编码错误（已安装）