别让AI瞎猜了：用Harness Engineering 终结无限返工

公众号名称：爱奇艺技术产品团队

作者名称：数据库团队

发布时间：2026-05-14 12:02

这两年，越来越多的研发团队已经把AI编程工具带进了日常工作。有人用它补代码，有人让它写测试，有人拿它查文档、搭脚手架、整理方案，也有人开始让agent直接进入仓库，完成一轮搜索、修改、验证和回写。

表面上看，问题似乎已经从“要不要用AI”变成了“用哪个工具”。但真正落到交付时，大家很快会碰到另一层更现实的问题：AI的局部产出可以很快，真正进入研发流程却没那么容易。

很多返工并不是因为模型完全不会写代码，而是因为任务在交给agent之前，依据没有准备完整。页面结构还在变，状态没有补齐，接口边界没有说清，验证口径不统一，结果记录也没有固定落点。这样一来，agent只能靠上下文里零散的信息去猜。第一次也许能猜中，第二次、第三次就开始偏。代码看起来越来越多，协作成本也跟着上来了。

所以这篇文章想讨论的，不是怎样把提示词写得更复杂，也不是单纯推荐某一组工具，而是一个更接近研发现场的问题：

本文问题：怎样把AI放进一个更稳定、更可协作、更可验证、也更容易留下经验的研发流程里。

我把这套做法概括为Harness Engineering。

**概念定义：**harness在这里指一套让agent能稳定参与研发的工程安排：有任务入口、有执行依据、有工具边界、有验证反馈、有结果记录。

很多时候，团队对agent的期待其实很直接：

最好能多做一点
少问一点
出错少一点

但这三个期待背后对应的并不是单纯的模型能力，而是工程条件：

**多做一点：**上下文和工具是否完整。
**少问一点：**边界、非目标和验收方式是否清楚。
**出错少一点：**验证和回写是否形成稳定链路。

**核心结论：**agent要可靠参与研发，不能只靠模型回答。项目需要给它准备任务入口、执行依据、工具边界、验证反馈和结果记录。

理论篇：从Prompt到Harness

01__#

为什么Prompt不够了

1.1 局部生成不等于稳定交付

如果只看局部，今天的AI编程工具已经足够能干。它会补函数、会改样式、会写测试，甚至会顺着仓库上下文做一轮看起来像样的实现。但研发真正关心的从来不是“能不能生成一段代码”，而是这段代码能不能进入现有流程、能不能被别人接住、能不能在后续迭代里继续维护。

前端场景里，这个问题通常表现得更早。知道“想做一个什么页面”，不代表页面结构已经稳定，也不代表视觉边界、状态覆盖和实现方式已经对齐。如果只有一段自然语言描述，agent往往会同时猜三件事：

页面长什么样
有哪些状态
代码应该怎么拆

首版做出来并不难。难的是后面继续改的时候，设计稿、状态演示和真实页面慢慢开始分叉。

后端的问题看上去不一样，本质却相似。很多任务一开始只有一句话，比如“做一个同步工具”“补一条处理链路”“把这个流程接起来”。这类描述说清了目标，却没有说清边界：

运行模式是什么
输入输出是什么
失败怎么处理
验证怎么做
结果应该记在哪里

agent当然也能先写一个版本，但这种“先跑起来再说”的方式，很难直接进入可交付状态。

提示词在这里能解决一部分问题。我们可以把背景写得更长，把要求列得更细，把“不要做什么”补充进去。但prompt通常是一次性的，它很难承担持续验证，也无法自动阻止坏模式扩散。

更常见的情况是，团队开始不断加长prompt：

补背景
补规则
补口径
补历史失败经验

短期看这有帮助，长期看会出现两个问题：

问题	结果
prompt变成新的口头传统	只有少数人知道哪些话必须加、哪些规则不能漏
prompt仍然脱离项目本身	换一轮上下文、换一个工具入口，经验就容易丢失

所以问题并不只在AI，而在协作链路里缺少统一入口、稳定依据、执行边界和反馈链路。

方式	解决什么	解决不了什么
Prompt Engineering	这一轮怎么说清楚	项目里如何持续做对
Harness Engineering	任务如何进入项目、执行、验证、回写	不替代人的需求判断和架构取舍

这就是Harness Engineering要解决的问题。

02__#

Harness Engineering的第一性原理

2.1 第一性原理：从写代码转向跑完整链路

Harness Engineering背后的第一性原理，可以先从研发现场看：

**第一性原理：**当模型越来越会写代码后，瓶颈不再只是“谁来写”，而是任务有没有说清、边界有没有定住、验证能不能跑、结果有没有人接。

代码生成会越来越便宜，但下面这些事仍然消耗人的注意力：

需求澄清
优先级判断
验收定义
架构取舍
质量判断

agent-first的研发方式不是让人退出，而是让人把注意力放在更值得判断的地方。

人的注意力应该放在判断上，而不是反复补同一类上下文：

**目标怎么定：**不要反复解释项目背景。
**边界怎么收：**不要每次口头补规则。
**反馈怎么跑：**不要每次手动提醒跑测试。
**风险怎么判断：**不要反复修同类review问题。
**经验怎么写回项目：**不要把结论只留在一次对话里。

agent能不能稳定工作，也不只取决于模型本身。它能看到什么文档，能调用哪些工具，能不能运行测试，能不能读取反馈，能不能知道什么算完成，这些都会影响它能接手到什么程度。

agent能看到什么、能调用什么，决定了它实际能完成什么。

来源：OpenAI Harness Engineering。

对agent来说，可以简单理解成三句话：

无法访问的知识，基本等于不存在。
无法执行的工具，基本等于没有。
无法验证的目标，很难持续修正。

工程信息越容易被agent找到、执行和检查，它能做的事就越接近一个真实工程师能接手的任务。

OpenAI的Harness Engineering实践，最值得借鉴的也在这里。它强调的不是“模型能生成多少代码”，而是当agent开始参与更多软件开发环节时，团队需要把过去靠人记、靠人判断的东西放进系统里。

过去依赖人的地方	放进 harness 后
记住项目背景	写进`AGENTS.md`、README、docs
临场判断边界	写进plan的 `Scope` / `Non-Goals`
手动提醒质量	变成test、lint、review gate
本机验证一次	写进runbook和验证摘要
口头同步结果	回写任务系统、PR/MR或文档

继续加长prompt只能解决一轮对话的问题。Harness Engineering更关心的是，项目本身能不能提供稳定的入口、边界、验证和反馈。

2.2 最小可用harness的组成

落到项目里，可以先抓三件事：

1.隐性知识要变成可发现的上下文如果一个约束只存在于某个人的经验里，agent基本无法稳定遵守。项目入口、目录说明、架构边界、接口约定、命名规则、验证方式，都应该尽量进入仓库或任务系统。

2.反馈要变成可执行的入口“注意质量”“跑一下测试”这类提醒不够稳定。更好的做法，是把验证命令、runbook、Storybook、contract diff、lint、review gate等变成明确入口。

3.规则要逐步从提醒升级成检查不是所有规则都能一开始机械化，但重复出现的review问题不应该永远靠人提醒。可以先登记在项目约束里，再逐步变成linter、脚本、测试或CI gate。

一套最小可用的harness，至少要组织起五类东西：

类别	例子
任务约束与规则	目标、范围、非目标、验收口径
工具执行与运行入口	Makefile、脚本、测试命令、运行说明
上下文和计划工件	`AGENTS.md`、docs、plan
权限控制与失败恢复	停止条件、回滚策略、风险说明
验证、评审与结果记录	runbook、review gate、PR/MR、任务回写

一次生成不能构成工程能力，可持续的能力来自一条能跑完的链路：

agent写完代码后进入运行环境，用DevTools等反馈继续修正。

来源：OpenAI Harness Engineering。

也可以把两者的分工再压缩成一张表：

问题	Prompt Engineering	Harness Engineering
背景怎么说清楚	写进prompt	写进项目入口和docs
约束怎么提醒模型	加提示词	写进plan、规则、gate
输出格式怎么限定	给格式要求	写进协作协议和回写格式
代码怎么验证	提醒跑测试	提供可执行验证入口
经验怎么复用	复制旧prompt	写回仓库、任务系统或 PR/MR

如果把这个原则落到一个普通项目里，起点不是先做一个复杂平台，而是先让仓库具备一套最小可用的harness：有入口地图，有计划协议，有验证入口，有项目约束登记，也有结果回写的位置。

方法篇：把协作链路放进项目

03__#

把协作链路放进项目里

3.1 先固定信息落点

很多团队在使用AI时，会把大量信息放在对话里：

项目背景
任务范围
实现偏好
验证方式
注意事项
上次失败原因

这样做启动很快，但难以复用。下一次换一个agent、换一个同事、换一个任务，这些信息又要重新拼起来。

Harness Engineering的一个核心动作，就是把这些临时上下文移到更稳定的位置。

在一个项目里，可以先把信息落点分清楚。

信息位置	主要负责
任务系统	目标、范围、状态、责任和反馈
仓库	设计依据、计划、验证入口、项目约束和结果记录
PR/MR	代码变更、评审讨论、CI结果、合并和留痕
agent工具	搜索、修改、执行、验证和回写

关键不是把某个系统称为“唯一来源”，而是让每类信息都有清楚的位置。

3.2 从任务入口到评审收口

任务状态不要散在聊天里。
执行依据不要只停留在口头说明里。
验证结果不要只存在本机终端里。
评审结论不要只停留在临时对话里。

一项复杂任务在harness里的流转，可以简化成下面这条链：

流转位置	主要问题	产出物
任务入口	为什么做，做什么，不做什么	目标、范围、非目标、验收口径
计划冻结	真实入口在哪里，如何改，如何停	plan、风险、验证方式、回滚策略
agent执行	按什么路径搜索、修改、运行、修复	代码变更、测试结果、过程记录
验证评审	结果是否可信，风险是否可接受	verify摘要、review结论、剩余问题
回写收口	后续如何追踪，经验如何复用	PR/MR说明、任务状态、文档更新

这样拆开以后，agent不需要凭空理解整个组织流程。它只需要在每个位置完成明确动作：

1.从任务入口拿目标。

2.从计划里拿边界。

3.从仓库里找实现依据。

4.从验证入口读取反馈。

5.把结果写回团队能看到的位置。

基于这个目标，我目前使用的harness模板，把项目里的基础内容分成几类：

类别	典型文件	作用
入口地图	`AGENTS.md`	告诉agent和工程师项目是什么、入口在哪里、验证命令是什么
控制面文档	`docs/harness/`	说明任务如何推进、边界如何记录、如何判断是否收口
计划协议	`.agent/PLANS.md`、`.agent/plans/`	约束复杂任务如何写计划
测试、验证和gate	`docs/test/`、`scripts/harness/`	放runbook、脱敏结果摘要和最小检查入口
agent扩展层	`.agent/prompts/`、`.agent/guides/`	放标准prompt、维护循环、review口径、linter接入建议

这样做的目标，不是让项目目录显得更复杂，而是让agent每次进入项目时，都能沿着同一套路径找到依据、边界、验证和结果记录。

04__#

初始化后的目录结构与使用方式

4.1 初始化前先让agent解读模板

https://github.com/SisyphusSQ/harness-template

为了把上面的想法落到普通项目里，模板初始化后的目录可以保持相对克制。它不是要替换原项目的工程结构，而是在原项目旁边补一层协作和验证入口。

如果你拿到的是随文附带的harness模板压缩包，不建议第一步就复制文件。更合适的方式，是把压缩包和目标项目一起交给agent，让它先读模板、再读项目，最后给出初始化方案。

推荐流程：

把harness模板压缩包和目标项目路径一起交给agent。
先要求agent只解读，不修改目标项目。
让agent输出初始化方案：会新增什么、会修改什么、会保留什么、有哪些风险。
根据目标项目的技术栈、任务系统、验证命令和团队约定，选择需要初始化的层级。
确认方案后再执行初始化，并在完成后运行项目验证命令和harness检查。

模板包提供的是一套可复用的项目结构，不是一组必须原样照搬的文件。落到项目里时，agent应该先理解模板，再理解目标项目，最后再把两者对齐。

模板目录把入口、计划、约束、验证和脚本放到项目内，方便后续任务复用。

一个典型初始化结果大致如下：

这个目录不是为了在项目旁边再建一套“文档工程”。这些文件的作用，是让项目本身更容易被agent使用，也更容易被团队协作维护。

文件或目录	使用时机	常见误用
`AGENTS.md`	agent进入项目、工程师快速接手任务时	写成项目百科，导致真正入口被淹没
`docs/harness/control-plane.md`	需要说明任务如何收集、冻结、切分、实现、验证、评审和回写时	只写流程名，不写实际判断条件
`docs/harness/project-constraints.md`	需要登记项目级规则和检查状态时	把尚未机械化的规则说成已强制执行
`.agent/PLANS.md`	任务超出单轮上下文、需要冻结范围时	只写流程口号，不写真实代码入口
`docs/test/`	需要复用验证步骤、记录副作用和结果时	只贴终端输出，不说明前置条件和判断口径
`scripts/harness/`	需要把结构检查、计划检查、review gate固定下来时	把业务测试全部塞进harness检查里

AGENTS.md是入口地图，负责导航和边界说明。.agent/PLANS.md和.agent/plans/TEMPLATE.md是复杂任务的计划协议。模板要求计划写真实实现，而不是只写“开发、测试、回写”。

后端任务尤其要写清：

真实入口
输入从哪里来
核心对象是什么
哪些模块负责什么
失败时如何停止和恢复
如何验证和回写

如果团队同时使用Superpowers这类技能化工作流，可以把它看成harness的执行层补充。

harness与Superpowers的分工：

**harness：**负责项目入口、计划协议、验证入口、项目约束和结果回写。
**Superpowers：**负责写计划、测试驱动、系统化调试、代码评审和完成前验证。

两者不应该变成两套互相竞争的规则，而应该按同一条链路配合。

4.2 初始化后的使用方式

1.先从AGENTS.md、docs/harness/ 和plan里读取项目依据。

2.再按技能化工作流完成实现与验证。

3.最后把结果写回任务系统、PR/MR 或仓库文档。

初始化之后，推荐的使用方式也可以很简单：

1.先读AGENTS.md，找到项目入口和验证命令。

2.复杂任务不要直接开改，先按 .agent/PLANS.md 写计划，冻结本轮范围、非目标和验收方式。

3.在计划里写清真实实现链路，不用harness流程图替代业务实现图。

4.执行时按计划推进，遇到范围变化先更新计划，而不是顺手扩大任务。

5.收口前执行项目验证命令、harness检查和review gate，把结果同步回任务系统、PR/MR或仓库文档。

结果是，agent的工作不再只是一次对话里的产出，而是进入了项目自己的记录、检查和验证体系。

实践篇：前端、后端与工具分层

05__#

前端案例：从 Pencil 到 Storybook，再到真实页面

工具	作用	可替代组件
Pencil	先把页面怎么摆、信息先后顺序和主要操作画出来，方便团队在写代码前把方向对齐。这里更像是“草图/线框图阶段”，不限定必须用Pencil这个工具	Figma
Storybook	前端组件开发与验证工具，用来独立展示组件状态、交互、边界场景和异常态，作为进入真实页面前的组件级验证入口。	项目内组件Demo页

5.1 前端三层：设计、状态、实现

前端最容易把Harness Engineering的价值看清楚，因为页面交付天然就分层。至少有三层需要分别接住：

执行依据层
状态暴露层
交付实现层

前端协作效率，很多时候就取决于这三层有没有先后站稳。

前端从设计结构，到状态暴露，再到真实页面接入的三段式路径。

层次	典型载体	作用
执行依据层	`Pencil`、设计结构文件、设计说明	固定页面目录、组件层级、变量映射、关键状态和交互边界
状态暴露层	`Storybook`、story文件	显示`Default`、`Empty`、`Loading`、`Error`、权限态、操作反馈态
交付实现层	真实页面、路由、接口接入	处理路由接入、权限逻辑、接口对接和页面联调

如果没有执行依据层，agent和工程师虽然都能开始写，但实现会持续漂移。大家面对的不是同一组约束，而只是同一句需求描述。

Storybook的价值不在于替代设计稿，而在于把运行状态显式摆出来，让评审和回归围绕现成页面行为展开。状态如果只留在设计稿或个人脑海里，后续讨论就会越来越依赖记忆，返工也会越来越随机。

当前两层已经提供稳定依据时，agent的位置才会变得清楚：它不是凭一句描述直接“生成页面”，而是在既定结构和既定状态之上补实现、补细节、补接线。

从harness的视角看，三类信息各有落点：

信息落点	典型载体	回答的问题
执行依据	Pencil 和设计说明	页面应该是什么结构、有哪些关键对象、哪些状态必须覆盖
状态暴露与验证入口	Storybook和story文件	这些状态是否真的能运行、能评审、能回归
交付实现	真实页面、路由和接口接入	这个页面是否已经进入正式业务路径

复杂页面任务在进入实现前，计划文件至少应该回答这些问题：

本轮页面范围是什么，是否包含弹窗、抽屉、批量操作、详情页或二级页面？
需要覆盖哪些状态，哪些状态只做占位，哪些状态本轮不做？
组件层级是否已经从设计结构里固定，还是允许在实现中调整？
Storybook里要暴露哪些story，评审时看哪些入口？
真实页面接入哪些路由、权限、接口和埋点？
如果接口还没准备好，mock数据、字段假设和后续替换位置在哪里？

**前端场景的关键点：**设计不要只冻结“长相”，还要冻结状态。状态不要只存在于设计稿里，还要进入可运行环境。agent不应该凭一句描述生成页面，而应该在结构和状态都明确后补实现。

这也是为什么前端场景里最直接的变化通常不是“生成速度更快”，而是返工更少。结构先冻结，状态先暴露，agent、工程师和评审围绕的是同一组对象，而不是各自理解的预期。

06__#

后端案例：从 docs、plan、verify到实现与验证

6.1 后端三层：依据、验证、实现

后端表面上没有Pencil和Storybook，但协作链路并没有因此变短，只是把对应的位置换成了另一组工件。让事情稳定下来的，往往是先把执行依据、验证口径和失败边界说清楚。

后端也可以对应拆成三层：

层次	常见载体	解决什么问题
执行依据层	docs、设计说明、接口说明、README、plan	运行模式、输入输出、异常口径、非目标范围、回滚方式
状态暴露层	验证脚本、mock 环境、试运行结果、可复现命令	什么条件下算成功，什么条件下算失败
交付实现层	实现、测试、联调、收口	代码是否进入正式业务路径

很多任务之所以反复，并不是因为代码太难，而是因为执行语义没有冻结。运行模式、输入输出、异常口径、非目标范围、回滚方式没有提前写清，agent的产出就很容易停在“看起来可以跑”，却还进不了交付。

后端任务中，docs、plan、terminal、logs、repo和review共同组成验证反馈循环。

更稳的做法，是先在任务系统里明确范围和责任，在仓库文档里补齐接口与设计说明，在计划工件里写清。

更稳的做法，是先在任务系统里明确范围和责任，在仓库文档里补齐接口与设计说明，在计划工件里写清Scope、Non-Goals、Validation、Rollback，然后再让agent进入实现与测试。

例如，一个同步工具类任务，如果只写“实现同步功能”，agent只能猜运行入口、配置来源、错误处理、重试方式和验证命令。更好的计划应该回答几个问题：

入口命令是什么，谁会触发它？
输入来自配置、参数、文件、API 还是消息？
核心对象在哪里装配，哪些字段必须校验？
service、repository、gateway或adapter各自负责什么？
失败时是重试、跳过、停止还是回滚？
成功与失败分别用什么命令或runbook验证？
结果要写回哪里？

后端任务尤其需要把“完成”的判断拆开。因为很多后端能力不是页面上马上能看到的，它可能是一条命令、一个定时任务、一个消费链路、一个API、一个数据同步过程，或者一组配置驱动的行为。

验证层次	应回答的问题	典型证据
静态检查	代码结构、类型、lint、配置是否符合项目规则	lint 输出、类型检查、编译结果
单元验证	核心函数和边界条件是否正确	单测结果、关键case列表
链路验证	入口、输入、处理、输出是否连通	命令执行记录、接口请求记录、mock环境结果
失败验证	异常、超时、重试、回滚或停止策略是否符合预期	错误日志、失败 case、恢复步骤
回写验证	结果是否同步到任务系统、PR/MR 或文档	验证摘要、剩余风险、后续事项

**后端场景的关键点：**先写清入口、输入、边界和失败策略。验证不要只写单测，要覆盖链路和失败场景。结果要能被后来的人复用。

所以对后端来说，关键不在于把实现动作再往前提，而在于把验证动作更早放进任务设计里。很多链路型任务真正决定能不能进入交付的，并不是“有没有代码”，而是“有没有一组团队共同认可的验证条件”。

07__#

工具不是重点，信息落点和职责分层才是重点

7.1 工具可替换，职责位置要稳定

前面两节分别用了前端和后端场景说明同一件事：工具名可以不同，但协作链里的位置其实高度相似。我们真正需要稳定下来的，不是某个固定产品组合，而是研发协作中的职责分层。

工具可以替换，但职责分层、架构边界和跨层约束不能缺位。来源：OpenAI Harness Engineering。

可以把常见工具放回同一条链路里看。

层次	典型工具或工件	主要作用
任务编排	Linear / JIRA / 其他 PMS	组织目标、范围、状态、责任人、验收条件和反馈
执行依据	Pencil / docs / design / plan	固定结构、边界、非目标、接口和验收条件
状态暴露与验证	Storybook / runbook / verify 命令	展示状态、复现问题、确认结果
agent执行	Codex / Cursor / Claude Code	搜索、修改、实现、测试、文档更新和结果回写
评审收口	GitHub / GitLab	承接diff、review、CI、讨论、合并和留痕

把Pencil、Storybook、Linear、Codex、Cursor、Claude Code放在同一段里讨论，很容易把问题带偏成工具选型。但从工程视角看，这里真正重要的不是产品，而是每一层承担什么职责。

层次	职责
任务编排层	定义目标、范围、责任人、优先级和验收口径
执行依据层	冻结结构、边界和非目标
状态暴露与验证层	把系统在不同条件下的行为显式展示出来
agent执行层	进入代码库和运行环境，完成搜索、编辑、执行、验证和回写
评审收口层	负责diff审查、CI 校验、评论讨论、合并和审计留痕

Harness Engineering要做的，就是把这些职责拆开、接稳，并让agent在自己应该工作的层面上发挥作用。工具完全可以替换，但任务编排、依据冻结、状态暴露、执行入口、验证反馈、评审收口这些位置不能长期缺位。

这也是为什么同一套方法可以同时适配Cursor、Codex、Claude Code或其他 agent工具：

工具负责执行能力。
harness负责工程条件。
任务入口、计划协议、验证入口和回写位置稳定后，工具替换带来的迁移成本会小很多。
如果所有规则都绑在某个工具的私有prompt里，工具一换，团队就要重新整理协作方式。

落地篇：从轻量harness到适用边界

08__#

从一套轻量harness开始落地

8.1 从最小harness开始

很多团队看到这里，第一反应可能是：这套东西是不是太完整了，落地成本会不会很高。

实际上，如果只是想从“个人会用agent”走到“团队能稳定协作”，起步不一定复杂。先把最容易反复出问题的几个位置固定下来就够了。

优先级	先固定什么	做法
1	任务统一入口	不要把所有工作都直接扔进聊天窗口，至少要有一个能承接目标、范围、背景、责任人和反馈的位置
2	仓库入口地图	根目录放一个简洁的`AGENTS.md`或同类文档
3	复杂任务计划	写清范围、非目标、入口、输入、组件职责、关键时序、错误处理和验证方式
4	可复用验证	前端用Storybook和页面联调说明，后端用README、Makefile、测试命令、runbook或verify脚本
5	项目规则登记	先区分文档说明、命令检查和CI gate，再逐步升级规则
6	结果回写	验证摘要、review结论、剩余风险、下一步动作要回到任务系统、PR/MR或仓库文档

轻量harness模板先解决的就是这些基础问题。团队不需要一开始就建设完整平台，可以先把任务入口、计划协议、项目约束、验证入口和结果记录固定下来。只要这些位置稳定，agent协作就会比只靠临时prompt更可控。

后续再逐步补：

项目级linter
contract diff
E2E（End-to-End，端到端验证：从任务入口、计划协议、执行过程、验证入口到结果记录的完整链路检查，确认协作流程整体可跑通。）
外部系统readback
维护扫描
规则升级

顺序可以慢慢来，但方向应该清楚：把反复依赖人的判断，逐步写回到项目规则和检查入口里。

一个更稳妥的落地顺序可以分成三个阶段：

阶段 1：让agent找得到入口

先补AGENTS.md、验证命令和复杂任务计划模板，让agent进入项目后能快速找到任务入口、项目边界和验证方式。

阶段 2：让任务能被复盘和复用

固定plan、runbook、验证摘要和PR/MR回写格式，让一次任务结束后的结论能被后来的人继续使用。

阶段 3：让重复问题逐步机械化

登记项目约束，把高频review问题升级成lint、script、test或CI，减少同类问题反复依赖人工提醒。

这三个阶段不要求一次完成。更实际的做法，是先选一两个真实项目试运行：

前端可以从一个复杂页面或组件库开始。
后端可以从一个链路型工具或集成任务开始。
每次任务结束后，都补一次计划、验证和回写。

harness会逐步从模板变成项目自己的工作方式。

09__#

适用边界

9.1 判断边界：轻量还是完整

Harness Engineering不是要求所有事情都走一遍完整流程。

**适合轻量处理：**任务影响面小、验证方式直接明确，不需要完整harness流程。

一次性实验、纯脑暴、小范围草稿。
非核心逻辑的小修小补。
只影响单个小文件，且验证方式直接明确。

**适合启用harness：**任务会影响交付、协作或后续复用，需要提前固定依据、边界和验证。

有明确交付目标的页面或组件开发。
有接口、数据结构、测试或验证要求的后端任务。
涉及多个模块、多个状态、接口契约、数据迁移、权限边界或外部系统。
需要多人协作和评审，或希望把经验写回仓库和任务系统。

**仍然需要人判断：**让信息进入系统，不意味着人可以退出判断。

需求澄清、架构取舍、业务优先级。
风险判断、权限边界、安全策略。
同类问题是否进入项目约束登记，验证结果是否写入runbook或PR/MR。
后续需要交接、复盘或继续迭代时，关键决策应同步回任务系统或仓库文档。

这个边界很重要。Harness Engineering的目标不是把所有研发动作流程化，而是把高风险、高协作成本、高复用价值的部分系统化。越是短平快的事情，越应该保留轻量路径；越是会影响后续交付的事情，越应该提前准备依据、边界和验证。

附：辅助初始化Prompt

下面这段可以直接复制给agent，平时不需要逐字阅读。

你是我的研发协作 agent。我会提供一个 harness 模板压缩包，以及一个目标项目路径。
请按两个阶段工作。
阶段 1：只解读，不修改文件。
1. 解压或读取 harness 模板包，说明模板包中的核心目录和文件职责。
2. 读取目标项目的现有结构，包括 README、AGENTS.md、Makefile、package.json、go.mod、pyproject.toml、docs、scripts、CI 配置等实际存在的入口。
3. 判断目标项目适合初始化哪些 harness 内容：入口地图、控制面文档、计划协议、测试 runbook、项目约束登记、agent prompts/guides、脚本检查入口等。
4. 输出初始化方案，必须包含：
- 准备新增的文件
- 准备修改的文件
- 明确不覆盖或需要保留的文件
- 需要从目标项目实际情况推导的内容
- 初始化后的验证命令
- 可能的副作用和回滚方式
5. 在我确认之前，不要修改目标项目。
阶段 2：确认后再执行初始化。
1. 按确认后的方案初始化 harness 文件。
2. 保留目标项目已有的工程结构、构建方式、测试命令和团队约定，不要把模板内容机械覆盖到项目上。
3. 如果发现模板假设和项目实际情况冲突，先停下来说明冲突，不要自行扩大修改范围。
4. 初始化完成后，运行可用的验证命令，并给出结果摘要。
5. 最后输出一份初始化报告，包括已创建/修改文件、验证结果、尚未机械化的项目约束、后续建议。