vibecoder Skills+Harness双层架构实践

AI辅助研发的硬约束闭环：vibecoder Skills+Harness双层架构实践

当团队开始用AI写代码时，最怕的不是"AI不会写"，而是"AI写得不符合规范却流入生产"。我们设计了一套Skills+Harness双层架构，让AI生成的代码天然贴近平台标准，不符合规则时无法流入交付流程。

一、问题背景

我们团队管理着集团2000+微服务，随着AI辅助研发工具（Claude、CodeBuddy、Cursor等）的普及，一个矛盾越来越突出：

• AI擅长"写代码"，但不了解你们团队的架构规范、分层约束、质量门禁
• 开发者使用AI，生成速度快了，但架构违规率反而上升了
• 平台方想管控，但传统"规范文档+人工Review"的模式根本跟不上AI的生成速度

本质问题是：AI只负责"会不会做"，没有人负责"做得对不对"。

二、核心思路：Skills+Harness双层架构

我们的解法是把AI协同研发拆成两个明确的关注点：

┌─────────────────────────────────────────┐
│           Skills 能力层                  │
│   承载具体研发动作                        │
│   工程初始化 / 模块装配 / 模板生成         │
│   OpenAPI治理 / 组件接入 / 规则检查       │
│   → 解决"会不会做"                       │
└─────────────────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────┐
│           Harness 治理层                 │
│   承载硬约束与反馈闭环                    │
│   架构约束 / 质量门禁 / 流程关卡          │
│   → 解决"做得对不对、能不能过"           │
└─────────────────────────────────────────┘

核心原则：

• Skill负责"会不会做" —— 把研发动作标准化、可组合
• Harness负责"做得对不对" —— 把平台标准变成硬约束，不合格代码无法流入交付流程
• 配置层负责差异化 —— 不同业务团队可以在允许范围内覆盖平台默认配置

三、Skills层：把研发动作标准化

我们拆了一组可组合的Skill，而不是一个单体入口：

Skill	职责	典型场景
skill-router	统一路由与编排	用户说"帮我新建工程"，自动识别意图路由到对应Skill
project-init-skill	创建新工程	基于标准脚手架生成DDD基线工程
module-assemble-skill	装配模块	把"我需要SSO+BPM"映射为真实依赖、配置和目录结构
template-generate-skill	生成代码骨架	生成Controller/Service/DTO/Repository模板代码
openapi-governance-skill	接口标准化	校验API定义、生成OpenAPI文档和SDK
k8s-troubleshoot-skill	K8s服务排查	诊断测试环境Pod/Service/Ingress问题
rule-check-skill	校验生成结果	调用Harness侧规则，执行结构/依赖/接口/命名检查

关键设计：rule-check-skill不是独立校验，而是调用Harness侧规则。这意味着Skills不持有规则，规则全部沉淀在Harness层，Skill只是规则的执行入口。

典型流程

以"新建工程"为例：

1. 用户通过Claude/CodeBuddy/平台入口发起请求
2. skill-router 识别意图，路由到 project-init-skill
3. project-init-skill 基于标准脚手架创建DDD基线工程（轻量分层 or 完整领域建模）
4. module-assemble-skill 按需装配SSO/BPM等模块
5. rule-check-skill + Harness执行架构约束、质量门禁、流程校验
6. 不合格？反馈回流，AI修正后重新校验；合格？流入交付流程

四、Harness层：把规范变成硬约束

这是整个体系的核心。如果Harness只是文档+提示词，它就是软约束，没人会真正遵守。

我们把Harness分为三类，每一类都通过具体机制落地：

4.1 架构级Harness

目标：保证生成工程天然符合目标架构

落地方式	说明
DDD基线脚手架	新工程不是从零拼装，而是基于预置脚手架创建，天然包含正确的分层结构
轻量分层/完整领域建模模板	两套标准模板覆盖简单CRUD和复杂业务场景
模块装配边界检查	防止跨层调用（如Controller直接调用Repository）
包结构与依赖边界检查	校验import关系是否符合分层约束

关键：架构约束不是靠人Review发现的，而是通过脚手架和模板先天保证，再通过校验脚本后天拦截。

4.2 质量级Harness

目标：把质量要求从"建议"变成"门禁"

落地方式	说明
JaCoCo覆盖率	测试覆盖率不达标，流水线直接失败
gitleaks密钥检测	代码中不允许出现密钥/Token，提交前拦截
编译与单元测试	编译不过/测试不过，不可能进入代码评审
OpenAPI规范校验	接口定义不符合规范，SDK生成会失败
依赖合规检查	不允许引入未审批的三方依赖

4.3 流程级Harness

目标：把AI生成结果纳入正式研发闭环

落地方式	说明
Git Hooks	commit前自动执行结构检查、lint、gitleaks
CI校验	PR提交后自动触发完整质量门禁
失败反馈回流	校验失败时，把错误信息反馈给AI工具，自动修正

流程级Harness的闭环：这是最关键的一环。不是"检查→报错→人改"，而是"检查→报错→反馈AI→AI修正→重新检查"，形成自动化闭环。

AI生成代码 → Git Hooks前置检查 → CI完整校验
     ↑                              │
     │         失败反馈回流          │ 失败
     └──────────────────────────────┘
                                    │ 通过
                                    ▼
                             流入交付流程

五、配置层：团队差异化的安全网

不是所有团队都一样，但也不能让差异化稀释平台标准。我们采用三层配置模型：

配置层级	作用	示例
平台默认配置	全公司统一标准	默认脚手架版本、默认代码模板、必须遵守的规则
业务团队配置	团队级差异化要求	可选模块白名单、命名规范差异、OpenAPI校验级别
工程实例配置	单工程个性参数	工程名、模块清单、轻量分层or完整领域建模

关键约束：工程实例配置不允许突破平台和团队白名单边界。团队配置只能在平台允许的范围内覆盖，不能关闭必选规则。

六、效果与数据

首批试点后：

• 工程初始化：人天级 → 分钟级，开发者不再需要手动搭建脚手架和配置依赖
• 架构违规率下降70%+：不是靠人Review发现的，而是Harness自动拦截的
• 零合规事故：gitleaks在提交前拦截了多次密钥泄漏，JaCoCo门禁保障了测试覆盖率
• AI生成代码可管控：不合格代码无法流入交付流程，从根源消除了"AI乱写"的风险

七、踩坑与反思

坑1：Skills与Harness边界不清

早期我们把一些校验逻辑写在了Skill里，导致规则散落在各处。后来明确：Skill只持有动作逻辑，规则全部沉淀在Harness层。rule-check-skill只是Harness规则的执行入口，不持有规则本身。

坑2：业务团队配置过于自由

第一批给了业务团队太大的配置自由度，结果有的团队直接关闭了质量门禁。后来加了白名单约束：必选规则不可关闭，可选规则可在允许范围内调整。

坑3：没有硬门禁，Harness退化成软约束

如果Harness只有文档和提示词，开发者会直接忽略。必须有Git Hooks + CI校验形成硬门禁，不通过就无法提交/合并，这才是真正的闭环。

坑4：缺少试点项目验证

模板和规则如果只在设计阶段，很容易理想化。必须找1-2个真实项目接入，用实际反馈修正模板和规则，否则上线后大量误报会让开发者反感。

八、总结

AI辅助研发的治理问题，核心不是"限制AI"，而是"让AI在正确的轨道上跑"。Skills+Harness的双层架构，本质上是用工程化手段解决了AI时代的研发治理问题：

• Skills让AI"会做"——标准化研发动作，可组合、可复用
• Harness让AI"做对"——硬约束闭环，不合格代码无法流出
• 配置层让团队"可控差异"——不稀释标准，但允许合理定制

这套体系目前还在持续迭代中，欢迎交流。