本文来自花椒技术部真实工程实践。如果你也在关注 AI 工程化、企业 Agent、MCP、Skill 或研发工具链，文末有「花椒技术交流群」入口，欢迎一起交流。
AI 写代码已经不是新鲜事。
在真实研发里，真正麻烦的也往往不是“能不能生成一段代码”，而是生成之后怎么进入团队交付：
- AI 是否理解当前项目的目录、框架、组件和历史约束；
- 前后端接口字段、状态、异常分支是否有统一来源；
- 生成代码之后，单测、E2E、Review 和真实环境验证谁来兜底；
- 哪些判断可以交给 AI，哪些必须由人确认；
- 经验沉淀下来之后，下一个项目能不能复用。
这篇文章复盘一次 H5 活动项目里的 Harness Engineering 试点。
我们没有上来做一个大而全的平台，而是先在一个真实项目里跑通最小闭环：
方案设计 -> 接口协议 -> 开发 -> 测试 -> 联调 -> 提测
本次最终团队一共沉淀了 13 个 Skill，覆盖服务端、前端和测试三个方向。我们正在整理具体每一类的示例,会打包成一份更详细的说明。整理好之后会第一时间同步到「花椒技术交流群」,感兴趣的可以先加群蹲一下～
1. 旧模式的问题：AI 只能局部提效，不能稳定交付
很多团队最开始用 AI Coding，路径都差不多：
需求描述 -> 开发者临时补上下文 -> AI 生成代码 -> 人工修改 -> 联调测试
这个方式在个人开发里很好用。问题是，一旦进入团队项目，AI 需要的不只是当前一句需求，而是一整套工程上下文。
旧模式里主要有三个痛点。
1.1 项目事实依赖个人经验
过去活动开发主要依赖研发个人经验：问同事、翻旧代码、复制历史实现、人工判断组件怎么接。
同一类活动，不同人做出来的目录组织、组件拆分、接口接入方式可能并不完全一致。经验留在人脑里，AI 只能基于当前对话猜。
这会带来一个很直接的问题：
人能靠经验兜住的上下文，AI 未必知道。
1.2 前后端协作依赖临时沟通
H5 活动项目通常需要服务端接口和前端页面并行推进。
如果接口字段、状态、异常分支、版本变化主要靠聊天同步，短期能跑，但文档容易失真。
我们在这次试点里遇到过一个很典型的问题：某个接口实际上变更了多次，但协议文档里的版本记录没有完整反映其中一次字段变化。
这类问题对熟悉项目的人来说，可能只是“再问一句”的成本；但对 AI 来说，协议不准确，就意味着它会基于错误上下文继续生成。
1.3 测试和 Review 容易后置
AI 可以加快实现速度，但如果测试、Review 和真实环境验证仍然后置，问题还是会集中暴露在联调和提测阶段。
所以我们这次要解决的不是“让 AI 多写点代码”，而是另一个问题：
能不能让 AI 在团队研发流程里稳定参与，而不是只在某个开发者本地临时帮一把？
先看一张对比图。
flowchart LR
subgraph Old["旧模式：依赖个人经验"]
O1["需求拆解<br/>人工经验为主"] --> O2["局部生成<br/>临时提示词驱动"]
O2 --> O3["人工联调<br/>口头沟通同步"]
O3 --> O4["测试补测<br/>问题集中后置"]
end
subgraph New["新模式：Harness + Skill 驱动"]
N1["项目事实沉淀<br/>Skill 化经验"] --> N2["协议驱动开发<br/>接口文档定版本"]
N2 --> N3["测试前移<br/>单测 + E2E 先行"]
N3 --> N4["提测交付<br/>问题前置发现"]
end
O3 -. "Harness Engineering 介入" .-> N2
这张图想表达的不是“新模式完全替代旧模式”，而是把原来靠个人经验、临时沟通和后置补测兜住的环节，逐步变成项目事实、接口协议、测试反馈和人工边界共同支撑的工程机制。
2. 核心思路：给 AI 一套可以工作的工程环境
我们理解的 Harness Engineering，不是再写一个更长的 Prompt。
它更像是为 AI 参与研发准备一套工作环境：
| 能力 | 解决的问题 | 本次试点里的做法 |
|---|---|---|
| 项目事实 | AI 不知道项目上下文 | 用项目文档、上下文目录和项目说明沉淀框架、目录、规范、历史模块 |
| 接口协议 | 前后端协作输入不稳定 | 服务端维护接口契约文档，前端基于协议版本拆任务和联调 |
| Skill 资产 | 经验难复用 | 将框架规范、通用能力、测试资产、Review 检查项沉淀为 Skill |
| 测试反馈 | 质量验证后置 | 将单测、E2E、代码 Review 和半自动真实环境验证前移 |
| 人工边界 | AI 容易越权或误判 | 需求拆解、关键业务判断、真实环境验收、高风险操作仍由人确认 |
本质上，工程师的工作从“检查 AI 输出”前移到了“设计 AI 可以使用的上下文、约束和验收标准”。
3. H5 项目的最小闭环架构
这次试点没有覆盖上线、自动发布、自动回滚，也没有验证全自动开发。
我们只验证到提测前的研发闭环，整体架构可以抽象成下面这张图。
flowchart LR
Req["业务需求拆解"] --> Plan["技术方案确认<br/>AI 多轮辅助 + 人工拍板"]
Plan --> Harness["项目接入 Harness<br/>初始化项目上下文"]
Harness --> Skill["Skill 资产加载<br/>框架规范 / 通用能力 / 测试资产"]
Skill --> Contract["接口契约文档<br/>字段 / 状态 / 异常 / 版本"]
Contract --> Dev["前后端开发<br/>AI 辅助生成 + 人工拆分"]
Dev --> Test["单测 / E2E / AI Review"]
Test --> Verify["人工联调与真实环境验收"]
Verify --> Submit["提测"]
Test -. "问题回流" .-> Skill
Verify -. "协议差异 / 风险回流" .-> Contract
这里最关键的是两条回流：
- 测试和 Review 发现的问题，需要回到 Skill 或项目规范里；
- 联调和真实环境发现的协议差异，需要回到接口契约文档里。
如果没有回流，Harness 只是一堆静态文档；有了回流，它才会逐步变成团队可复用的工程环境。
4. 前后端双线流程：不是串行等接口，而是协议驱动并行
H5 活动项目里，前后端最容易互相卡住。
过去常见模式是：服务端先出接口，前端边问边接，字段不清楚就临时沟通，异常分支遗漏了再补。
这次我们把协作主线放到接口契约上。
flowchart TB
subgraph FE["前端"]
FE1["业务需求拆解"] --> FE2["技术方案确认"]
FE2 --> FE3["页面 / 功能开发<br/>Harness + Skill"]
FE3 --> FE4["单测 / E2E"]
FE4 --> FE5["AI Review + 人工 Review"]
FE5 --> FE6["联调 / 提测准备"]
end
subgraph BE["服务端"]
BE1["业务需求拆解"] --> BE2["技术方案确认"]
BE2 --> BE3["通用能力沉淀<br/>Skill 化"]
BE3 --> BE4["接口契约文档"]
BE4 --> BE5["功能开发<br/>Harness + Skill"]
BE5 --> BE6["单元测试"]
BE6 --> BE7["AI Review + 人工 Review"]
end
BE4 -. "协议版本 / 字段 / 异常分支" .-> FE3
FE6 -. "联调问题 / 字段差异" .-> BE4
这套流程里，接口契约文档不是附件，而是前后端协作的主线。
服务端负责维护接口字段、状态、异常分支和版本变更；前端基于协议版本拆任务、写页面、准备联调；AI 在中间读取稳定输入，而不是凭需求描述猜字段。
5. 接口契约示例：让 AI 看到稳定输入
以榜单能力为例。
服务端先把“榜单”这类通用能力沉淀成可复用 Skill。这个动作不是单纯写一段实现，而是把榜单模块里反复出现的接入方式、字段理解和协作约束整理成可复用资产。
Skill 落地后的几天内，服务端基于这类能力生成了前端对接文档，文档里明确接口字段、状态和异常分支。前端拿着这份文档，很快就完成了榜单接口联调。
如果没有这套机制，前端通常需要翻聊天记录、临时找接口负责人确认字段含义，或者根据旧项目实现猜当前接口该怎么接。
这条链路可以抽象成下面的接口契约闭环。
flowchart LR
S1["服务端通用能力<br/>Skill 化"] --> S2["生成 / 维护<br/>前端对接文档"]
S2 --> F1["前端基于协议<br/>拆分任务"]
F1 --> F2["页面开发<br/>接口接入"]
F2 --> J1["联调验证"]
J1 --> D1["字段差异<br/>状态差异<br/>异常分支遗漏"]
D1 -. "回写版本记录和影响范围" .-> S2
S2 --> AI1["AI 辅助开发 / Review / 测试建议"]
AI1 --> F2
一个脱敏后的接口契约文档可以长这样：
# 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 很容易沿着旧上下文继续生成。
所以这次复盘后，我们对接口契约有一个明确结论：
接口协议不能只描述“现在长什么样”，还要描述“这次变了什么、影响谁、谁确认过”。
6. Skill 资产：不是项目结束后归档，而是在过程中被调用
这次试点里，Skill 不是写完项目后的总结材料，而是直接参与研发过程。
我们把 Skill 分成几类：
| Skill 类型 | 解决的问题 | 用在什么阶段 | 公开示例 |
|---|---|---|---|
| 框架规范类 | AI 不知道项目目录、框架、组件约束 | 项目接入、开发前上下文初始化 | 前端活动框架规范、服务端框架约束 |
| 通用能力类 | 重复模块每次从 0 接入 | 模块开发、联调准备 | 榜单、活动配置、消息接入等通用能力 |
| 接口契约类 | 前后端协议不稳定 | 服务端出协议、前端拆任务 | 接口字段、状态、异常分支、版本规则 |
| 测试资产类 | 测试账号、测试路径、用例经验分散 | 单测、E2E、真实环境验证 | 测试数据准备、关键路径验证 |
| Review 类 | 人工 Review 关注点不稳定 | 代码审查、提测前检查 | 代码 Review 检查项、风险提示 |
Skill 的价值不是“名字很多”，而是它能不能回答三个问题：
它解决哪类问题？
它适用于什么范围？
它当前是新增、更新，还是复用？
这类 Skill 最大的作用，是把过去“问一下某个熟悉项目的人”变成更稳定的工程输入。
当然，Skill 也不是越多越好。
如果 Skill 过时，AI 会放大过时经验；如果适用范围没写清楚，AI 会把局部经验错误迁移到新场景。
所以 Skill 必须有生命周期：新增、使用、反馈、更新、下线。不能只沉淀，不治理。
7. Skill 如何进入流程：一张分层图
可以把这次试点里的 Skill 使用方式理解成三层。
flowchart TB
subgraph L1["第一层：项目事实"]
A1["框架规范"]
A2["目录结构"]
A3["组件使用约束"]
A4["历史模块经验"]
end
subgraph L2["第二层：协作协议"]
B1["接口契约"]
B2["版本记录"]
B3["字段差异"]
B4["联调确认点"]
end
subgraph L3["第三层：质量反馈"]
C1["单测建议"]
C2["E2E 路径"]
C3["Review 检查项"]
C4["真实环境验收记录"]
end
User["开发者 / 技术负责人"] --> A1
User --> B1
User --> C1
A1 --> AI["AI 辅助开发"]
B1 --> AI
C1 --> AI
AI --> Output["方案 / 代码 / 测试建议 / Review 报告"]
Output --> Human["人工确认边界"]
Human -. "经验回流" .-> A4
Human -. "协议回流" .-> B2
Human -. "质量回流" .-> C3
这张图里，人不是被替换掉，而是从“最后救火”前移到“定义上下文、协议和验收标准”。
AI 做的是加速执行和辅助检查，人负责判断哪些输入可信、哪些输出可以进入项目。
8. 实操入口：AI 不是上来就写业务代码
这次试点里，一个很重要的动作是先让 AI 进入项目现场，而不是直接丢一句需求让它开写。
前期动作类似这样：
帮我基于 master 分支，检出一个分支，我要做某 H5 活动需求。
然后再让它初始化项目上下文：
使用项目上下文初始化 Skill，帮我初始化一下项目。
这两句看起来普通，但背后的顺序很重要：
先建立工作分支
-> 再加载项目规则
-> 再读取上下文
-> 再拆任务
-> 最后才进入业务代码生成
如果一上来就让 AI 写页面，AI 很容易只围绕当前需求文本生成局部代码；但真实项目里，代码要符合目录、组件、接口、测试和 Review 规则。
所以我们把“初始化上下文”作为进入项目的第一步。
9. 测试前移：不能把质量问题都留到提测后
AI 辅助开发会提高实现速度，但也会把质量风险前置。
如果测试仍然后置，最终只是把问题从开发阶段搬到了联调和提测阶段。
可以把测试前移理解成这条链路：
flowchart LR
Code["AI 辅助生成代码"] --> Unit["单元测试<br/>逻辑验证"]
Unit --> E2E["E2E<br/>关键路径验证"]
E2E --> Review["AI Review + 人工 Review"]
Review --> Real["真实环境验收<br/>人工触发"]
Real --> Submit["提测"]
Unit -. "发现逻辑问题" .-> Code
E2E -. "发现流程问题" .-> Code
Review -. "发现规范 / 风险问题" .-> Code
这里的边界要写清楚：
- 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，备注「技术群」，我会手动拉你进群。
