AutoDev —— 一套真正能自动化开发的基础设施

Harness Engineering：一个把"谈需求"和"守规矩"彻底分开、让 AI 自动化开发从玩具走向工程的基础设施。

一段熟悉的灾难

你打开 Claude 或者 Codex，丢过去一句："帮我做个命令行计算器"。

三秒钟后，模型给了你一个 800 行的 Python 项目：完整的 GUI 框架抽象、一个支持插件的运算引擎、Redis 缓存集成、一份热情洋溢的 README------以及一句轻描淡写的"如果你想加单元测试，我可以再写一份"。

而你只是想要一个能在终端里输入 2+3 然后看到 5 的小工具。

或者反过来：你写了一份三千字的需求文档，详细到连 C++20 标准、-fvisibility=hidden、平台抽象层只能放在 src/platform/ 都说清楚了。模型读完，欢快地写出了一份用 Python 实现的、带 try/except 控制流的、所有平台代码散落在业务逻辑里的版本。

每个用 AI 写代码超过一周的人，都收藏过这两种灾难。

这不是模型不够聪明

我曾经以为这是模型的问题------Sonnet 不行就上 Opus，Opus 不行就等下一代。但越用越发现，再强的模型也救不了一种局面：两件本质不同的事情被强行揉进同一个 prompt 里。

第一件事叫任务澄清：把人脑里"我想要个东西"的模糊欲望，翻译成机器可以无歧义执行的契约。这件事需要对话、追问、来回权衡，本质是发散的。

第二件事叫约束执行 ：把项目的工程规范------C++20、不用异常、平台代码隔离、错误处理走 Result<T, E>------变成代码生成时不可逾越的红线。这件事需要确定性、可重复、可机器校验，本质是收敛的。

把这两件事塞进一个 prompt，结果就是：模型一边猜你的意图，一边猜你的规矩，两个都猜不准，并且它没有办法告诉你它在猜。

我决定不再试图用更长的 prompt 解决这个问题，而是从架构上把它切开。

这就是 Harness Engineering 的起点。

切三刀，让每一层只做一件事

复制代码

┌──────────────────────────────────────────┐
│  skills/auto-dev                          │  ← 跟人谈
│  和你对话，把模糊想法磨成规范化的任务文档        │
├──────────────────────────────────────────┤
│  harness-runtime                          │  ← 跑得稳
│  消费任务文档，跑流水线，管重试，写状态           │
├──────────────────────────────────────────┤
│  harness-cpp / harness-python / ...       │  ← 守规矩
│  栈特定的不变量、文件布局、角色检查清单            │
└──────────────────────────────────────────┘

三层之间有一条铁律：信息只往下流，状态不向上回传。

auto-dev 不知道任务最终怎么执行，runtime 不知道任务怎么聊出来的，harness 不知道是谁在调用它。每一层都只对自己那一件事负责。

听起来像 SOA 的老调子？等你看下面的细节就明白了，魔鬼藏在边界的形状里。

第一层：auto-dev --- 一个只会"问问题"的 skill

auto-dev 是一个 Claude Code skill，它的全部职责只有两件：

跟你对话，澄清需求
写出一份合格的任务文档，然后闭嘴

它绝不做的事：不维护任务执行状态，不偷偷调模型帮你跑代码，不在交付之后回头改任务定义。它的输出是一份 markdown 文档，有严格的 schema：

复制代码

## Goal       ← 一句话目标
## Inputs     ← 输入是什么
## Outputs    ← 产出是什么
## Acceptance Criteria  ← 怎么算完成
## Constraints          ← 工程约束（语言、harness、后端、git 目标...）
## Status     ← ready 才会被 runtime 接收

文档没写完？runtime 不收。约束没声明？runtime 不收。Status 不是 ready？runtime 不收。

所有歧义都必须在入队前消化干净。 这不是繁琐，这是把"猜"这个动作从执行环节里彻底剔除。

第二层：harness-runtime --- 一个只会"按文档执行"的引擎

任务文档进入 runtime 后，世界变得无聊地确定：

task_queue.json 是任务记录的唯一真相
status.json 是 worker 的当前快照
每个 pipeline 阶段（architect → implementer → tester）独立解析后端
失败重试、断点恢复、git commit 交付，统一在 runtime 处理

最关键的一条规则：runtime 永远不重新解释任务。文档怎么写，它就怎么执行。你写错了？任务失败，但失败发生在你能看见的地方------而不是模型偷偷帮你"理解"成了别的意思。

而 runtime 里我自己最得意的一处设计是：每个阶段独立选择执行后端。

复制代码

## Constraints
- architect_execution_mode: provider
- architect_provider: deepseek
- architect_model: deepseek-reasoner

- implementer_execution_mode: cli
- implementer_cli_command: codex exec -c approval_mode=full-auto -o {output_file} -

- tester_execution_mode: cli
- tester_cli_command: codex exec -c approval_mode=full-auto -o {output_file} -

这一段配置说的是：

设计阶段用 deepseek-reasoner------便宜，擅长想清楚结构
实现阶段用本地 codex CLI------可以直接在我自己的机器上动文件、跑命令
测试阶段继续用 codex------它对 shell 环境更熟

一个任务，三个后端，三种成本曲线。便宜的活给便宜的模型，贵的活给贵的，每个阶段各司其职。这种自由度在"一个 mega-prompt 走天下"的世界里是想都不敢想的。

第三层：harness-* --- 一摞"项目宪法"

每个技术栈对应一个 harness-* 包。以 harness-cpp 为例，它定义了一整套 C++ 项目的不变量：

复制代码

C++20，所有平台统一，禁止降级
RAII 强制，业务代码里看不到 new/delete
平台特定代码只能在 src/platform/，不许 #ifdef 散落
错误处理用 std::expected 或 Result<T, E>，禁止异常做控制流
公共 API 默认隐藏，必须显式 export

加上六种角色（架构师 / 实现者 / 构建工程师 / 测试 / 审查 / 移植工程师）的决策树和检查清单，加上机械化 lint，加上代码审查协议------一整套"这个项目永远成立的规则"。

任务文档里只要写一句 harness: harness-cpp，runtime 就会自动把这些约束拼进每个阶段的 prompt 里。模型不需要"记住"项目规范------规范作为上下文每次都被重新送进它的视野。

这就是为什么模型不再"忘记"你的规矩：因为我们根本不指望它记住。

大任务怎么办？把它拆开

实际工程里最容易翻车的是大任务。你想做一个完整的拼图小游戏？让模型一次把图片上传、切块算法、拖拽逻辑、对齐吸附、计时器、排行榜、胜利检测全写完？要么 context 爆炸，要么写到一半失忆，要么出来一坨能跑但读不懂的东西。

Harness 的解法是：让 architect 阶段除了输出 design.md，还可以输出一份 subtasks.json。runtime 检测到这个文件，就进入子任务循环：

复制代码

architect → 拆解为 N 个子任务
  ↓
  对每个子任务：
    architect (子设计) → implementer → git commit → tester(可选)
    失败重试 → 超过上限 → 跳过并记录
  ↓
最终报告：N 完成 / M 跳过 / K 重试

每个子任务的 git commit 都按 [subtask k/N] 标题 格式落盘。出问题翻 git log，精确到子任务。不需要让模型写一份"它做了什么"的总结------commit 历史就是它做了什么。

这也意味着任务可以恢复。中间挂了？下次接着上一个完成的 commit 跑就行。

为什么这套设计值得存在

如果你只是偶尔让 AI 写个一次性脚本，确实用不上这一套。但只要符合下面任意一条，分层就开始有回报：

同一类任务会反复跑------把约束沉淀进 harness，下次不用再说一遍
代码必须符合特定工程规范------把规范变成上下文而不是寄希望于模型自觉
任务大到一次跑不完------任务拆解 + per-subtask commit 让流程可观察、可恢复
你想混用多个模型------每个阶段独立选后端，便宜的活给便宜的模型

更深层的价值是契约思维：

任务文档是契约。 Harness 是契约。 Runtime 是执行者。

每一层都对一件事负责，每一次失败都能精确归因------是任务没说清，还是约束没守住，还是执行环境出问题。这跟"写个 mega-prompt 然后祈祷"的工作流，完全是两个世界的事情。

现状：能跑通，但还在长

诚实地说，这是一个仍在演化的项目。当前能跑通的部分：

✅ auto-dev skill 完整可用
✅ runtime 支持 provider / CLI 双后端、阶段独立路由
✅ 任务拆解 + per-subtask git commit
✅ harness-cpp 提供完整的 C++20 约束包和六种角色
✅ --validate-task-doc / --queue-json / --status-json 等机器可读视图
✅ 断点恢复、失败重试、stale 任务自动清理

正在路上的：

⏳ 更多 harness 包（Python / Go / Rust 暂时还没专属约束）
⏳ benchmark 任务集合的实测数据
⏳ 更聪明的失败归因和重试策略

最后一点话

我做这个项目，是因为我相信 AI 编程的下一步竞争不是哪个模型更聪明 ，而是谁能把模型嵌进真实的工程流程里而不出乱子。

模型会越来越强，这是确定的。但模型不会替你想清楚需求，不会替你定义"什么叫做完了"，不会替你守住你项目的工程底线。这些事情需要工程基础设施去承载------而不是塞进 prompt 里碰运气。

Harness Engineering 是这个方向上的一次实践。它可能不是最终形态，但它把"谈需求"和"守规矩"彻底分开了------而我相信，这是一切真正可工程化的 AI 开发流程的起点。

仓库地址

🔗 GitHub : https://github.com/zytc2009/Harness_engineering

欢迎 fork、试用、提 issue、拍砖。

快速上手：

复制代码

git clone https://github.com/zytc2009/Harness_engineering.git
cd Harness_engineering
# 读 README.md（或中文版 README_CN.md）
# 然后试着跑：
python harness-runtime/main.py --add "[Goal] 一个 hello world [Language] Python"
python harness-runtime/main.py --drain

如果这套东西帮到了你，或者让你看明白了一点 AI 工程化的可能形状，那它就值得存在。