176 lines
6.6 KiB
Markdown
176 lines
6.6 KiB
Markdown
---
|
||
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 编码错误（已安装）
|