Claude Code 和 Codex 已经够强了，问题不在模型，在你的仓库。没有入口文件、没有架构约束、没有当前任务——agent 进来两眼一抹黑，写出来的东西自然偏。
苏米注：这个工具做的就是把仓库改造成 agent 能顺畅工作的环境。
问题是这样来的
把任务丢给 Claude Code，它开始噼里啪啦写代码。写完一看方向错了。它不知道有个专门的 utils/ 目录，不知道这个模块不能直接访问数据库，不知道上周刚重构了那块逻辑。
于是花 20 分钟解释背景，它重写，还是偏，再解释……
今年二月 OpenAI 发了一篇文章叫 Harness Engineering，核心观点是：agent 能不能好好工作，很大程度上取决于仓库有没有给它准备好"工作环境"。他们内部用这套方法，让 agent 承担了相当一部分实际开发工作。
不是零人工干预——人负责决策和审查，agent 负责执行。分工很清晰：
| 人类负责 | Agent 负责 |
|---|---|
| 目标和验收标准 | 读文档理解仓库 |
| 架构决策 | 写代码、跑测试 |
| 安全审查 | 开 PR、响应 review |
| 最终合并 | 根据反馈修改 |
一条命令初始化
安装之后，在你的项目目录里跑：
harness init跑完之后，项目里多了这些：
your-project/
├── CLAUDE.md ← Claude Code 自动读取
├── AGENTS.md ← Codex / 其他 agent
└── .harness/docs/
├── architecture/ ← 系统架构
├── product/ ← 产品需求
├── quality/ ← 质量标准
├── security/ ← 安全规范
└── plans/active/ ← 执行计划你填好这些文档，agent 进来读一遍，就知道这个项目是干什么的、架构怎么分层、什么不能动、当前在做哪个任务。
执行计划：让 agent 知道"现在在做什么"
计划存成 JSON 文件，带状态机（pending → in_progress → done）。Agent 每次开始工作先读计划，做完一步更新状态，下次继续不用从头解释。
harness plan create "实现用户认证" "添加 JWT"
# → Created: EP-20260401-120000
harness plan list
# EP-20260401-120000 [0/3] 实现用户认证harness check：机械化验收
很多"质量检查"工具其实只是打印一行"✓ passed"，背后什么都没跑。harness check 是真的跑：
Project type: nextjs
──────────────────────────────
✓ [PASS] harness-docs (2ms)
✓ [PASS] lint (1843ms)
✗ [FAIL] test (4201ms)
✗ should return 401 for invalid token
Results: 2/3 checks passed自动检测项目类型（Next.js / Node / Python / Go / Rust），选对应的 lint 和 test 命令。失败就 exit 1，直接卡掉 CI。不是"建议你测试一下"，是没过就不让合并。
harness audit：量化 agent 可读性
✓ Architecture documentation +20
✓ Principles / quality standards +15
✓ AGENTS.md +10
✓ CLAUDE.md +5
✗ Active execution plans 0/15
✓ Test directory +20
✓ Linter configuration +10
✗ CI/CD workflows 0/5
[███████████████░░░░░] 80/100
✓ Excellent — highly readable for agents把仓库对 agent 的友好程度量化成 0-100 的分数。文档没更新、没有执行计划、没有 CI——分数会掉。分数掉了，agent 工作质量也会掉。
苏米注：这个评分机制很实用，可以定期检查仓库的 agent 可读性，及时发现文档过期、缺少测试等问题。
harness garden：代码卫生检查
自动检测并报告：
- 📌 90 天未更新的文档（过期信息比没有信息更危险）
- 📌 重复定义的工具函数——debounce / formatDate 写了三份
- 📌 未经 schema 验证的 API 响应
- 📌 setTimeout 里的硬编码数字
完整工作流
- harness init — 生成文档骨架
- 填写文档 — 描述架构、需求、约束
- harness plan create — 创建执行计划
- claude / codex — Agent 读文档、写代码、开 PR
- harness check && harness audit — 验收
- 人类 review 并合并
步骤 4 就是你正常用 Claude Code 或 Codex，不需要换工具。Harness 做的是让步骤 4 变得更顺。
如图，cc 会使用 harness skill 将所有任务列出；然后会启动多个并行的 Agent 去执行任务，最后做优化、测试、验收。有点类似 cc 的 plan mode 或者 cc teams 的模式。
总结
Harness Engineering 的核心价值在于：通过标准化的文档结构和自动化工具，让 AI Agent 能够快速理解项目背景、架构约束和当前任务，从而减少反复沟通的成本，提高代码生成质量。
最佳实践：
- 用
harness init快速搭建文档骨架 - 定期运行
harness audit检查可读性分数 - 用
harness check作为 CI 卡点，确保质量 - 通过
harness garden清理技术债务