一套外置于 AI Agent 的约束 + 反馈 + 演化系统,让 AI 写出来的代码能上生产环境。 通用骨架版本——适用于任何编码项目类型(Web、小程序、后端、移动端、CLI 等)。
如果你用过 Cursor / Claude Code / GitHub Copilot 写代码,大概率遇到过以下情况:
- AI 写代码很快,但整体性、架构性会丢失 —— 越写越散
- 代码冗余,经常需要清理一遍
- 每次新会话 AI 都要重新理解项目,重复对话
- AI 写完声称"完成",实际跑不通或有 bug
- AI 不熟悉你项目的特定规则(命名、格式、不能用某些 API 等),要反复纠正
- 同样的错误反复犯——AI 不会记忆,你以为说过的话它不会真的"记住"
这些不是 AI 不够聪明,是它缺乏外部约束和反馈机制。
Harness 就是这套外部机制——它是给 AI 用的工厂车间:有规则、有流程、有质检、有返工通道。AI 是工人,harness 是厂房。
之前:用户口头说"加个 X"、"调整下 Y"——结果代码越改越散
现在:模糊概念用 requirement-crystallizer(或类似工具)结晶为 PRD,锁定方向,再走流程。对话的方向性碰撞集中在 crystallizer 内,流程内只允许局部修正不允许大方向漂移。
之前:评审就是找 bug,代码"能跑就行",越积越冗余
现在:
- Reviewer 守底线:bug、规范、合规、闭环违反 — 挡合并
- Critic 找上限:简洁、复用、抽象、深度优化 — 给建议(按需触发)
两个角色不能合并 — 同一个 Agent 既要严守底线又要激进找优化,通常什么都做不好。
之前:每次写代码都凭"当前直觉",写出来就是惯性的延伸
现在:
- Explorer 横向打断惯性:方案不明显时做对标(按需触发)
- Simplify-pass 纵向定期清理:每完成 N 个需求做一次全项目精简
- Harness-evolution 持续沉淀:用户纠错累积 5 次后强制沉淀
Harness 不是越多越好,合适才好。 过度约束会:
- 让 Agent 走形式而不是真正思考
- 把好想法往中庸方案上拉(因为对标的都是现成方案)
- 让文档管理消耗 Agent 的注意力,挤压写代码的精力
- 让小需求也被强行拖到 6 份文档,效率低下
所以本模板内置了自适应机制:
接到需求,Agent 第一件事是判断档位:
| 档位 | 适用 | 流程 | 文档 |
|---|---|---|---|
| S | 改 typo / 调样式 / 修小 bug | 编码 → reviewer → 完成 | 1 份 |
| M | 加新组件 / 改现有功能 / 接新接口 | 6 阶段 | 3-4 份 |
| L | 新模块 / 架构改动 / 敏感场景 | 完整 10 阶段 + explorer + critic | 5-7 份 |
Agent 可以提议"这个我觉得可以简化",但必须先告知用户、得到同意后才执行。
- 闭环逻辑 (
rules/closed-loop.md)——代码健康最低线 - 执行和评判分离——一个 Agent 不能既写又审
- 能力边界——不知道就说不知道,不能编造
- 错误工程化沉淀(5 次阈值)
harness-template-v1.0/
├── README.md ← 你正在读
├── SETUP-GUIDE.md ⭐ 新项目特化指南(必读)
├── CLAUDE.md ← Agent 入口(进项目第一眼看到的)
├── planning/ ← 给"人"用的项目规划目录
│ ├── README.md
│ └── _template/ ← 通用规划模板
│ ├── 01-pre-launch-questions.md (立项问题骨架)
│ ├── 02-feature-list.md (功能清单骨架)
│ └── 03-tech-decisions.md (技术决策清单)
└── harness/ ← 给 Agent 用的执行约束
├── README.md
├── agent-owner.md ← 编排中枢(项目背景留模板)
├── rules/ ← 项目级硬约束
│ ├── closed-loop.md (闭环逻辑,完全通用)
│ ├── coding-style.md (通用编码规范)
│ ├── platform-specific.md (占位:你填平台特定规则)
│ └── compliance.md (合规通用骨架)
├── skills/ ← 任务级 SOP
│ ├── feature-coding.md (功能/页面/路由开发)
│ ├── module-coding.md (模块/组件开发)
│ ├── api-integration.md (外部接口接入)
│ ├── explorer.md (探索家,完全通用)
│ ├── reviewer.md (评审守底线,完全通用)
│ ├── critic.md (批评家找上限,完全通用)
│ ├── simplify-pass.md (周期精简,完全通用)
│ ├── harness-evolution.md (反馈循环,完全通用)
│ └── deploy-checklist.md (发布检查骨架)
├── knowledge/ ← 业务上下文(待你填)
│ └── README.md
└── changes/ ← 每个需求全流程留痕
├── README.md
└── _template/ (单需求模板,完全通用)
├── 01-requirement.md
├── 02-tasks.md
├── 03-plan.md
├── 04-code-review.md
├── 05-deploy.md
└── notes.md
第一次拿到模板,请立刻打开 SETUP-GUIDE.md 读完。它会教你:
- 怎么把模板复制到你的项目
- 怎么填项目背景
- 怎么写 platform-specific 规则
- 不同项目类型的特化建议(Web / 小程序 / 后端 / CLI 等)
- 轻量启动路径(分 4 周渐进引入)
每次发现 Agent 犯了错:
- ❌ 不要靠口头叮嘱"下次注意"
- ✅ 工程化消除 — 加进 rules / skills / knowledge
规范的每一行都对应一个真实踩过的坑。
不要写"代码质量良好",要写:
lint 错误数 = 0 AND 类型检查错误数 = 0 AND 单元测试通过率 = 100% AND 测试用例数 > 0
一切不能被机器验证的约束在 Agent 执行中都是无效约束。
编码 Agent 和评审 Agent 必须是不同的角色。让一个 Agent 又写又审等于没审。
每次用户纠正 Agent,Agent 都必须执行 harness-evolution.md 的捕获-计数-沉淀流程。5 次为阈值。
closed-loop.md 是判断代码"健康度"的核心原则。每段代码必须有明确的:来源、去处、作用。
每完成 N 个需求或每月触发一次 simplify-pass.md。不还技术债,迟早被压垮。
✅ 适合:
- 想要 AI 编码达到生产质量
- 项目有一定持续性(不是一次性脚本)
- 有规范化诉求或团队协作场景
- 用 Cursor / Claude Code / Codex / GitHub Copilot 等 AI 编码工具
- 写一次性脚本、demo、原型(用 harness 太重)
- 完全不在意代码质量,只追求 ship 速度
- 项目超小(< 100 行代码)且不会迭代
- v1.0:首个通用版本,从微信小程序 harness 抽象而来
- 后续会根据多种项目类型的实践反馈持续演化
Harness 不是给 Agent 加镣铐,是给 Agent 配工具。装备齐全,作战有效;装备过重,寸步难行。请根据你的项目实际情况,选择合适的"装备配置"。