SpecCoding + Harness：把 Vibe Coding 从「灵感」钉成「可交付」

老李 · 架构复盘：真正该想清楚的，不是「会不会用 Claude Code」，而是 Spec 管什么、Harness 卡什么、人机边界在哪、Review 三关怎么过、如何落到 CI。

一、痛点引入

欲穷千里目，更上一层楼。

老李在微软小冰做 KA 交付时，见过同一种翻车：需求口头对一下，Cursor 开干，半小时出一堆「能跑」的代码。联调一开，边界条件全炸；安全扫一眼，密钥硬编码；架构评审更狠------直连库、绕过网关、分层被揉成一锅。

这不是模型不够聪明，是缺少规格与护栏。Vibe Coding 把「写代码」变快了，却把「写对、写稳、写合规」的风险前置到每一个 PR。团队越依赖 AI IDE，越需要一套能复核、能审计、能进流水线的方法。

核心观点：AI 加速的是生成，Spec + Harness 加速的是可控交付。

二、是什么

名不正，则言不顺。

SpecCoding（规格驱动编码）：先把「要什么 / 不做什么 / 验收标准」写成可执行规格，再让 AI 按规格生成与改写。它不是写一堆文档给人看，而是把意图钉成机器可读的约束面------OpenSpec、任务清单、接口契约、测试用例，都是 Spec 的形态。

Harness（约束 harness）：给 AI Coding 套上「缰绳」------目录边界、依赖白名单、禁止模式、Skill/Rules、评审检查项、自动化门禁。Harness 约束的是行为空间，不是灵感本身。

横向对比：

不是什么：不是「禁止 vibe」，也不是「再造一套瀑布文档」。是把 vibe 收进规格，把规格收进门禁。

三、为什么用

工欲善其事，必先利其器。

老李的判断很直白：没有 Spec，AI 只会优化「看起来像对」；没有 Harness，Review 永远跟不上生成速度。

使用意义：

可复核

：被问到「你怎么保证 AI 代码架构合规」时，答案不是「我仔细看了」，而是「规格里写了分层与依赖边界，Harness 与 CI 会拦」。
可复用

：Spec/Rules 已在 Claude Code、Cursor 落地；对 Kiro 是同构可迁移，不是「三套工具都管过舰队」。
可度量

：门禁失败率、Review 打回类型、合入时长------能进看板就进，没数就先别吹「效能体系」。

典型场景：微服务新接口、Agent 编排节点、RAG 检索链路改造、私有化交付定制------越是「能生成但易漂移」的活，越该先 Spec 再 Coding。

四、架构图

万法归一，一以贯之。

人机分工边界一句话：人定方向与硬问题，机提效率与草稿量，门禁做最后的机械执行。

Review 三关（实践必过）：

五、安装配置步骤（Claude Code / Cursor）

千里之行，始于足下。

最小可跑 harness，不追求一次装全宇宙。

1）仓库落规则（两边共用）

bash 复制代码

.cursor/rules/architecture.mdc   # 分层、依赖、禁止项
.cursor/skills/<domain>/SKILL.md # 可复用技能
CLAUDE.md                        # Claude Code 项目指令
openspec/                        # 变更规格与任务

2）Cursor ：Settings → Rules 指向 architecture.mdc；Skills 放领域流程（如 Agent 节点开发）；对话先贴 Spec 链接再开改。

3）Claude Code ：根目录 CLAUDE.md写清「先读 Spec、禁止越层、改完跑最小验证」；用 /compact前先把验收点写进 Spec，避免上下文被压扁后丢约束。

4）本地自检钩子（示意）

bash 复制代码

# pre-commit：格式 + 单测冒烟 + secret 粗检
pre-commit run --all-files

5）CI 门禁：PR 必过单测、静态检查、secret scan；架构规则失败则阻断合并。人审三关通过后才允许合入统一基建分支。

讲真，老李一开始也嫌写 Spec 慢。后来发现：少写 20 分钟规格，常换回 2 小时联调事故------这账太好算。

六、实战演示（对齐简历）

纸上得来终觉浅，绝知此事要躬行。

6.1 微软小冰日常：需求 → 指令 → 编码 → Review

时段：2025.07 -- 2026.07。日常用 Claude Code / Cursor 走通：需求拆解 → 指令生成 → 编码联调 ；对 AI 产出做正确性 / 安全 / 架构合规 Review 后再交付。同周期 DigitalHuman 把 ASR/TTS/LLM/LiveKit 全链路延迟从 2s → 500ms 、可用性 99.9%------那是平台工程账；Spec/Harness 解释的是「AI 加速时怎么不把契约冲烂」，两笔账别混成一句。

操作节奏（可复述的日常节奏）：

把模糊需求压成 Spec：目标、非目标、接口、验收用例。
用 IDE 按 Spec 生成差分，禁止「顺手重构无关模块」。
人过三关：用例是否覆盖边界；有无密钥与越权；是否越层、是否绕过网关。
合入前走 CI；失败不谈 vibe，只谈哪条规则没过。

6.2 AgentX：Java Agent 编排 + Python DAG

AgentX 是企业级 AI Agent 平台：Java 侧 Agent 推理编排 + MCP 工具调用；Python 侧 DAG Workflow + 拖拽设计器。研发过程同样用 Claude Code / Cursor 提效，但对生成代码做架构合规 Review------例如编排状态机是否可恢复、工具调用是否经 MCP、是否把密钥写进节点配置。

这和「会喊 AI 写 CRUD」不是一档事：平台级代码允许 AI 起草，不允许 AI 擅自改契约。

6.3 岗位对齐：甜心智能 Vibe Coding 流水线

对齐 JD 的完整链（已落地前两环，后两环是同构心智）：

Claude Code / Cursor（已用）→ Review 三关 → 统一基建提交 → 自动化门禁；Kiro 按同构规则可迁入

人定方向与硬问题，机提效率。老李把小冰与 AgentX 的习惯平移：Spec 进仓库，Harness 进 Rules，门禁进 CI------工具可以换，方法不散。

七、洞见三条

见微知著，观过知仁。

洞见 1：Spec 是契约，不是说明书

写给 AI 的规格要「可判定」：有输入输出、有失败态、有验收命令。写「尽量高可用」等于没写；写「p99 ≤ 500ms，失败重试 2 次」才能进门禁。

洞见 2：Harness 约束行为空间，不约束创造力

白名单依赖、禁止直连 DB、强制走网关------这些是缰绳。Prompt 里的创意可以野，合入路径必须窄。窄路径才扛得住团队规模。

洞见 3：Review 三关里，架构合规最容易被 vibe 冲掉

正确性有测试兜底，安全有扫描兜底；架构漂移往往「也能跑」，所以最危险。老李的习惯：架构规则失败直接红灯，不许用「下个迭代再还」换合入。

八、总结 + 实践清单

知其然，更要知其所以然。

一句话：Vibe 负责速度，Spec 负责方向，Harness 负责边界，Review 负责硬问题，CI 负责不信任任何人------包括 AI 和你自己。

方法论速查表

行动号召：下一个需求先写半页 Spec，再开 Claude Code / Cursor；把三条架构禁止项写进 Rules；让 CI 替你挡掉「能跑但不该合」的差分。速度会回来，翻车会少。