本文来自花椒技术部真实工程实践。如果你也在关注 AI 工程化、企业 Agent、MCP、Skill 或研发工具链，文末有「花椒技术交流群」入口，欢迎一起交流。
AI 写代码已经不是新鲜事。
在真实研发里，真正麻烦的也往往不是"能不能生成一段代码"，而是生成之后怎么进入团队交付：
- AI 是否理解当前项目的目录、框架、组件和历史约束；
- 前后端接口字段、状态、异常分支是否有统一来源；
- 生成代码之后，单测、E2E、Review 和真实环境验证谁来兜底；
- 哪些判断可以交给 AI，哪些必须由人确认；
- 经验沉淀下来之后，下一个项目能不能复用。
这篇文章复盘一次 H5 活动项目里的 Harness Engineering 试点。
我们没有上来做一个大而全的平台，而是先在一个真实项目里跑通最小闭环：
text
方案设计 -> 接口协议 -> 开发 -> 测试 -> 联调 -> 提测本次最终团队一共沉淀了 13 个 Skill，覆盖服务端、前端和测试三个方向。我们正在整理具体每一类的示例,会打包成一份更详细的说明。整理好之后会第一时间同步到「花椒技术交流群」,感兴趣的可以先加群蹲一下～
1. 旧模式的问题：AI 只能局部提效，不能稳定交付
很多团队最开始用 AI Coding，路径都差不多：
text
需求描述 -> 开发者临时补上下文 -> AI 生成代码 -> 人工修改 -> 联调测试这个方式在个人开发里很好用。问题是，一旦进入团队项目，AI 需要的不只是当前一句需求，而是一整套工程上下文。
旧模式里主要有三个痛点。
1.1 项目事实依赖个人经验
过去活动开发主要依赖研发个人经验：问同事、翻旧代码、复制历史实现、人工判断组件怎么接。
同一类活动，不同人做出来的目录组织、组件拆分、接口接入方式可能并不完全一致。经验留在人脑里，AI 只能基于当前对话猜。
这会带来一个很直接的问题：
text
人能靠经验兜住的上下文，AI 未必知道。1.2 前后端协作依赖临时沟通
H5 活动项目通常需要服务端接口和前端页面并行推进。
如果接口字段、状态、异常分支、版本变化主要靠聊天同步，短期能跑，但文档容易失真。
我们在这次试点里遇到过一个很典型的问题：某个接口实际上变更了多次，但协议文档里的版本记录没有完整反映其中一次字段变化。
这类问题对熟悉项目的人来说，可能只是"再问一句"的成本；但对 AI 来说，协议不准确，就意味着它会基于错误上下文继续生成。
1.3 测试和 Review 容易后置
AI 可以加快实现速度，但如果测试、Review 和真实环境验证仍然后置，问题还是会集中暴露在联调和提测阶段。
所以我们这次要解决的不是"让 AI 多写点代码"，而是另一个问题：
text
能不能让 AI 在团队研发流程里稳定参与，而不是只在某个开发者本地临时帮一把？先看一张对比图。
这张图想表达的不是"新模式完全替代旧模式"，而是把原来靠个人经验、临时沟通和后置补测兜住的环节，逐步变成项目事实、接口协议、测试反馈和人工边界共同支撑的工程机制。
2. 核心思路：给 AI 一套可以工作的工程环境
我们理解的 Harness Engineering，不是再写一个更长的 Prompt。
它更像是为 AI 参与研发准备一套工作环境：
| 能力 | 解决的问题 | 本次试点里的做法 |
|---|---|---|
| 项目事实 | AI 不知道项目上下文 | 用项目文档、上下文目录和项目说明沉淀框架、目录、规范、历史模块 |
| 接口协议 | 前后端协作输入不稳定 | 服务端维护接口契约文档，前端基于协议版本拆任务和联调 |
| Skill 资产 | 经验难复用 | 将框架规范、通用能力、测试资产、Review 检查项沉淀为 Skill |
| 测试反馈 | 质量验证后置 | 将单测、E2E、代码 Review 和半自动真实环境验证前移 |
| 人工边界 | AI 容易越权或误判 | 需求拆解、关键业务判断、真实环境验收、高风险操作仍由人确认 |
本质上，工程师的工作从"检查 AI 输出"前移到了"设计 AI 可以使用的上下文、约束和验收标准"。
3. H5 项目的最小闭环架构
这次试点没有覆盖上线、自动发布、自动回滚，也没有验证全自动开发。
我们只验证到提测前的研发闭环，整体架构可以抽象成下面这张图。
这里最关键的是两条回流：
- 测试和 Review 发现的问题，需要回到 Skill 或项目规范里；
- 联调和真实环境发现的协议差异，需要回到接口契约文档里。
如果没有回流，Harness 只是一堆静态文档；有了回流，它才会逐步变成团队可复用的工程环境。
4. 前后端双线流程：不是串行等接口，而是协议驱动并行
H5 活动项目里，前后端最容易互相卡住。
过去常见模式是：服务端先出接口，前端边问边接，字段不清楚就临时沟通，异常分支遗漏了再补。
这次我们把协作主线放到接口契约上。
这套流程里，接口契约文档不是附件，而是前后端协作的主线。
服务端负责维护接口字段、状态、异常分支和版本变更；前端基于协议版本拆任务、写页面、准备联调；AI 在中间读取稳定输入，而不是凭需求描述猜字段。
5. 接口契约示例：让 AI 看到稳定输入
以榜单能力为例。
服务端先把"榜单"这类通用能力沉淀成可复用 Skill。这个动作不是单纯写一段实现，而是把榜单模块里反复出现的接入方式、字段理解和协作约束整理成可复用资产。
Skill 落地后的几天内，服务端基于这类能力生成了前端对接文档，文档里明确接口字段、状态和异常分支。前端拿着这份文档，很快就完成了榜单接口联调。
如果没有这套机制，前端通常需要翻聊天记录、临时找接口负责人确认字段含义，或者根据旧项目实现猜当前接口该怎么接。
这条链路可以抽象成下面的接口契约闭环。
一个脱敏后的接口契约文档可以长这样：
markdown
# xx-rank-frontend-integration.md
# 前后端接口对接契约文档
使用本技能把后端接口事实整理成前端可执行的对接契约文档。输出目标不是普通 API 字段清单，而是让前端同学知道什么时候调、怎么传、取哪些字段、忽略哪些字段、失败和空态怎么处理、联调时检查什么。
## 输出位置
- 生成或补全文档时，先确认目标项目根目录，并把 Markdown 文件写入 `<项目根>/docs/delivery/`。
- 默认文件名使用 `<业务或模块名>-interface-contract.md`；项目已有命名规则时遵循项目规则。
- 如果用户提供的草稿不在 `docs/delivery/`，补全文档时在 `docs/delivery/` 创建或更新 canonical 文档，并把原草稿仅作为输入来源。
- 不把前端对接契约文档写入业务代码目录、`docs/context/`、`docs/architecture/`、当前技能仓库或临时目录；用户明确要求其他路径时，先指出这与技能规则冲突并取得人工确认，未确认前不写入其他路径。
- 无法确认目标项目或无法写入 `docs/delivery/` 时，先暴露缺口，不要把正文输出伪装成已落盘文档。
## 执行顺序
1. 先收集接口事实：需求文档、后端代码、proto、Apifox、接口返回示例、已有文档和联调口径。
2. 区分事实与推断；字段名、类型、必填、登录态、环境域名、错误码和响应结构必须来自证据或明确标记待确认。
3. 确认目标项目根目录和 `<项目根>/docs/delivery/`；目录不存在时在目标项目内创建，再生成或补全文档。
4. 读取 `references/contract-doc-pattern.md`，按固定结构生成或补全文档。
5. 从前端开发视角补齐契约：调用入口、调用顺序、参数来源、最小消费字段、字段忽略规则、异常兜底、联调检查项。
6. 对变更类文档维护 `doc_version`、当前版本、本次改动和变更记录；不要让旧口径与当前口径并存而不说明优先级。
7. 输出前做自检：前端是否能只看文档完成接入；后端是否能据此确认接口责任；测试是否能据此联调验收；文件是否位于目标项目 `docs/delivery/`。
## 必需输入
- 接口业务目标和前端使用场景。
- Method、Path、环境域名、Content-Type、登录态和请求来源。
- 请求字段及来源：登录态、页面上下文、上一步接口、服务端配置、客户端生成或固定常量。
- 响应结构、前端必须消费字段、可忽略字段和调试/埋点字段。
- 空列表、空对象、`errno != 0`、重复请求、旧数据、配置缺失、未登录等处理口径。
- 联调时前后端需要共同确认的最小检查项。
缺少高风险信息时先暴露缺口，不要编造接口事实。可以先输出带 `待确认` 标记的文档草案，但要明确继续开发的风险。
## 输出原则
- 面向前端开发写作：每个字段都要说明前端怎么用，而不只是后端怎么返回。
- 优先写"最小消费字段"，避免要求前端强依赖完整响应对象。
- 对新增字段说明兼容关系：历史字段是否不变、新前端是否必须读取、旧前端不读取是否受影响。
- 对可忽略字段给出处理口径：默认忽略、仅调试、仅埋点、后续需求再读取。
- 对异常场景写前端动作：展示失败兜底、隐藏入口、重新拉取、停止二次请求、按空态处理或上报联调问题。
- 对链式请求写清楚上一步输出如何成为下一步输入，以及中断条件。
- 对时间、环境、幂等、防重、登录态和字段命名差异保持精确，不写模糊描述。
## 配套资料
- `references/contract-doc-pattern.md`：前后端接口对接契约文档的结构、字段说明、写作规则和自检清单。AI 需要的不只是"有一个榜单接口"，而是字段、状态、异常分支、版本变化和人工确认点。
如果协议只记录当前字段，不记录变更历史，一旦中途发生字段调整，AI 很容易沿着旧上下文继续生成。
所以这次复盘后，我们对接口契约有一个明确结论：
text
接口协议不能只描述"现在长什么样"，还要描述"这次变了什么、影响谁、谁确认过"。6. Skill 资产：不是项目结束后归档，而是在过程中被调用
这次试点里，Skill 不是写完项目后的总结材料，而是直接参与研发过程。
我们把 Skill 分成几类：
| Skill 类型 | 解决的问题 | 用在什么阶段 | 公开示例 |
|---|---|---|---|
| 框架规范类 | AI 不知道项目目录、框架、组件约束 | 项目接入、开发前上下文初始化 | 前端活动框架规范、服务端框架约束 |
| 通用能力类 | 重复模块每次从 0 接入 | 模块开发、联调准备 | 榜单、活动配置、消息接入等通用能力 |
| 接口契约类 | 前后端协议不稳定 | 服务端出协议、前端拆任务 | 接口字段、状态、异常分支、版本规则 |
| 测试资产类 | 测试账号、测试路径、用例经验分散 | 单测、E2E、真实环境验证 | 测试数据准备、关键路径验证 |
| Review 类 | 人工 Review 关注点不稳定 | 代码审查、提测前检查 | 代码 Review 检查项、风险提示 |
Skill 的价值不是"名字很多"，而是它能不能回答三个问题：
text
它解决哪类问题？
它适用于什么范围？
它当前是新增、更新，还是复用？这类 Skill 最大的作用，是把过去"问一下某个熟悉项目的人"变成更稳定的工程输入。
当然，Skill 也不是越多越好。
如果 Skill 过时，AI 会放大过时经验；如果适用范围没写清楚，AI 会把局部经验错误迁移到新场景。
所以 Skill 必须有生命周期：新增、使用、反馈、更新、下线。不能只沉淀，不治理。
7. Skill 如何进入流程：一张分层图
可以把这次试点里的 Skill 使用方式理解成三层。
这张图里，人不是被替换掉，而是从"最后救火"前移到"定义上下文、协议和验收标准"。
AI 做的是加速执行和辅助检查，人负责判断哪些输入可信、哪些输出可以进入项目。
8. 实操入口：AI 不是上来就写业务代码
这次试点里，一个很重要的动作是先让 AI 进入项目现场，而不是直接丢一句需求让它开写。
前期动作类似这样：
text
帮我基于 master 分支，检出一个分支，我要做某 H5 活动需求。然后再让它初始化项目上下文：
text
使用项目上下文初始化 Skill，帮我初始化一下项目。这两句看起来普通，但背后的顺序很重要：
text
先建立工作分支
-> 再加载项目规则
-> 再读取上下文
-> 再拆任务
-> 最后才进入业务代码生成如果一上来就让 AI 写页面，AI 很容易只围绕当前需求文本生成局部代码；但真实项目里，代码要符合目录、组件、接口、测试和 Review 规则。
所以我们把"初始化上下文"作为进入项目的第一步。
9. 测试前移：不能把质量问题都留到提测后
AI 辅助开发会提高实现速度，但也会把质量风险前置。
如果测试仍然后置，最终只是把问题从开发阶段搬到了联调和提测阶段。
可以把测试前移理解成这条链路：
这里的边界要写清楚：
- AI 可以生成测试建议，但不能决定测试范围；
- E2E 可以覆盖关键路径，但不能替代真实环境验收；
- 半自动验证可以提高效率，但不应默认进入高风险自动化流程；
- 真实环境中的端侧表现、异常数据和发布风险仍需人工确认。
10. 本次跑通了什么
本次试点完成了从方案设计、接口协议、开发、测试、联调到提测的完整链路验证。
可以公开表达的结果主要有四类。
10.1 协作方式变化
前后端协作从主要依赖口头沟通，转向更多依赖接口协议文档和版本推进。
10.2 Skill 资产进入研发过程
这些 Skill 不只是项目结束后的归档，而是在实现、测试建议、审查辅助和协作同步中被调用。
10.3 测试和 Review 更早介入
单元测试、E2E 测试和 AI Review 进入开发流程，成为提测前质量把关的一部分。
这不代表 AI 可以替代测试或 Review，而是让明显漏项和基础风险更早暴露。
10.4 暴露了协议和 Skill 治理问题
这次也暴露了两个需要继续改进的问题：
- 接口协议不能只记录当前字段，还要记录版本差异和影响范围；
- Skill 不能只沉淀，还要持续更新，否则会放大过时经验。
这些问题反而是试点最有价值的部分。它说明 Harness Engineering 不是一次性搭个文档目录，而是一套需要持续治理的工程机制。
11. 最后
这次实践给我们的判断很明确：
AI Coding 要进入团队研发流程，不能只依赖生成能力。
只有代码生成，没有这些机制，AI 很容易停留在局部提效；有了这些机制，AI 才有机会参与完整交付链路。
这次 H5 项目只是一个最小闭环，不是终局。
但它至少验证了一件事：中型技术团队不一定要从"平台化大工程"开始做 AI 工程化。先选一个真实项目，把上下文、协议、Skill、测试和人工边界跑通，往往比先画一张宏大的平台蓝图更有价值。
花椒技术交流群
还在孤军研究 AI 工程化、AI 编程、Agent 落地，没人同行交流、没人拆解实战？
这里汇聚一线技术从业者，专注代码评审、企业内部 AI 助手真实实战落地。
想紧跟 AI 前沿动态、交流工程落地经验、少走踩坑弯路，欢迎直接加入「花椒技术交流群」。
群内专属福利拉满：每日精选研发向 AI 行业日报、文章独家延伸资料、文中未展开的技术细节，全部同步共享。
若二维码失效，可添加微信：LZ_Aug25，备注「技术群」，我会手动拉你进群。