智能体 Harness 速查表：组件、文件、常见问题与启动清单

Harness 的五个子系统

从零搭建的顺序：反馈 → 指令 → 状态 → 环境 → 工具。

Harness 文件

AGENTS.md 骨架

# 项目：支付后端（FastAPI、PostgreSQL）

## 启动
docker compose up -d && ./scripts/init.sh

## 验证
make check   # 代码检查、类型、单元测试、arch-check
make e2e     # 端到端场景

## 完成定义
- make check 和 make e2e 退出码为 0
- 功能通过脚本 scripts/verify.sh 设为 passing
- PROGRESS.md 已更新

## MUST
- 数据库访问只能通过仓储
- 密钥只能来自环境变量

## 文档
- docs/payments.md——涉及支付和退款的任务
- docs/migrations.md——修改数据库结构的任务

功能状态

验证层级

只有通过最高层级之后，才有资格宣布“完成”。绿色的单元测试不等于完成。

将规则机械化

#!/usr/bin/env bash
fail=0
if grep -rn "from app.db" app/services/; then
  echo "WHY: 服务层不直接访问数据库"
  echo "FIX: 使用 app/repositories/ 中的仓储"
  fail=1
fi
exit $fail

常见问题与解决方法

长任务中的角色

自主工作的预算

• 目标用一句话描述（例如：让所有功能都达到 passing）。
• WIP=1，每个功能有时间和尝试次数的上限。
• 指标单调上升，出现回归立即回滚。
• 迁移、基础设施、资金：升级给人处理。
• 多次评审失败之后，用干净的上下文重新开始该功能。

智能体启动清单

1. 存在 AGENTS.md：技术栈、启动方式、验证命令、完成定义。
2. make check 在干净的克隆上通过。
3. 环境可复现：锁文件，Docker 或 devcontainer。
4. 智能体拥有所需的命令权限，危险的命令被禁止或放在沙箱中。
5. 至少有一个覆盖主要场景的端到端测试。
6. 存在 PROGRESS.md，并规定会话开始时先读取它。
7. 功能列表中有状态，且只有一个处于 active。
8. passing 状态由脚本设置。
9. 检查信息中包含 WHY 和 FIX。
10. 任务有验收标准，并明确了范围边界。
11. 明确哪些事项需要人来决定。
12. 在改动之前计算了 verification gap，以便之后比较。

Harness 指标

总结

Harness 是一个闭环，而不只是一个文件：指令、工具、环境、状态和反馈。从验证开始，让 AGENTS.md 保持简短，把“完成”的判定交给脚本，并定期审查 Harness。所有这些都在 Harness 工程课程中，汇聚到一个基于实际项目的完整 Harness 上。