逐浪 · 第十一篇: Vibe Coding 下的效率定义与规范构建

Vibe Coding 下的效率定义与规范建设

一、效率不是“AI 写得多快”，而是“正确交付多快”

2026 年 6 月，我在 ScienceClaw 平台上连续完成了三个优化项目：并发测试工具（concurrent-tester）、Token 日志采集、Skill 刷新性能优化。它们共同验证了一件事：vibe coding 的真实效率 ≠ AI 生成代码的速度，而是 “从需求到生产稳定运行的总时间，减去除错和返工的时间”。

数据清晰地显示：当返工比例控制在 20% 以内时，vibe coding 效率是传统模式的 2–3 倍；但如果缺乏规范，返工率超过 50%，则还不如手写。

那么，这 20% 的返工如何控制？答案不在于“让 AI 更聪明”，而在于我们为 AI 设定的“驾驶规范”。

二、从三个案例看“脱缰”风险

案例 1：并发测试工具——动态环境下的“幻觉”

需求：写一个 Web 工具，能同时向 ScienceClaw 的 50 个 Pod 发送测试请求，并实时展示进度。
AI 快速生成了 FastAPI + Vue 前端、Dockerfile、K8s 部署 YAML。但在联调时发现：

• AI 默认使用固定 IP 列表，而 Pod 会重启、IP 会变；
• 超时设置缺失，一个 Pod 挂起会导致整个测试卡死。

问题：AI 生成了“功能正确”的代码，但忽略了生产环境的动态性。如果没有人工补上服务发现和超时控制，这个工具在生产环境根本不可用。

案例 2：Token 日志采集——两层根因，一层一层追

用户需要记录每次 LLM 调用的 token 消耗。AI 很快加好了 logger 和文件输出。但部署后 token 始终为 0。
排查发现：第一层，AI 没传 stream_options={"include_usage": True}；修复后 token 仍为 0。第二层，OpenAI 流式 API 的最后一个 chunk 是 choices=[] 只带 usage，AI 生成的 _parse_stream_chunk 直接 return None 丢弃了它。

问题：AI 是按照常规逻辑编写的，没有考虑到流式 API 的边界 case。如果不是人为加诊断日志逐层验证，这个问题可能永远发现不了。

案例 3：Skill 刷新优化——哨兵值的“多余”争议

在修复 usage-only chunk 时，我特意将 finish_reason 设为字符串 "null" 作为哨兵值，保证合并逻辑保留前面 chunk 的真实 finish_reason。代码评审时，有人建议改成更“Pythonic”的 None。
但我坚持保留 "null"，因为合并逻辑依赖这个值做判断：other.finish_reason != "null"。如果改成 None，None != "null" 为 True，就会把真实的 finish_reason 冲刷掉。

问题：AI 可以生成“看上去很美”的代码，但只有人才能理解隐含的合并语义。规范的作用，正是把这种“只有人知道”的坑固化下来。

三、人机协作的四条铁律

为了让 vibe coding 不变成“脱缰的野马”，我在这些项目中沉淀了四条必须执行的规范。

铁律一：方案先行，代码后行

每次让 AI 写代码之前，先要求它输出文字方案：改动点、影响范围、边界条件、回退策略。用另一个 AI（或你自己）审核通过后，再进入编码阶段。
效果：Token 日志项目中，AI 第一次给出的方案忽略了 stream_options，审核时被指出，避免了直接写出错误代码。

铁律二：约定“禁止区”与“允许区”

在 AGENTS.md 中明确写清楚：

• 禁止直接修改核心调度代码（需人工审核）
• 禁止删除现有单元测试
• 允许生成测试脚本、配置模板、文档初稿

AI 自动读取这个文件，就能在生成代码时自我约束。我在并发测试工具中，AI 自动绕过了核心的 skill_manager.py，只修改了测试脚本和前端——这正是规范文件的功劳。

铁律三：强制可观测性

AI 生成的代码必须自带诊断日志，至少包括：

• 关键分支的执行情况（如 [TOKEN-DIAG] captured usage-only chunk）
• 边界条件的命中（如 cache HIT 或 MISS）
• 错误时的详细上下文

这些日志让你在出现问题时，不需要猜 AI 到底干了什么。Token 日志项目中，正是 [TOKEN-DIAG] 日志让我确认 stream_options 生效了，才继续往下层排查。

铁律四：反例入库，持续训练

每次 AI 生成的代码导致线上问题，都将其简化成一个“反例”记录到内部 wiki，并注明：AI 当时是怎么写的、正确的是什么、为什么错。
这不仅能帮助团队成员识别类似陷阱，也能在后续的提示词中明确加上“注意：不要犯反例中的错误”。

四、vibe coding 元能力：人依然是方向盘

回到最初的问题：如何定义 vibe coding 下的效率？我的答案是：

当正确率足够高、返工率足够低时，vibe coding 就是超级生产力；反之则是灾难。而正确率和返工率，取决于你是否建立了清晰的协作规范，以及你是否具备元能力来驾驭 AI：

• 失效分析：AI 报错时，不是简单地“让它重试”，而是定位根因（如 _git_clone 无超时），然后让 AI 针对根因修复。
• 系统抽象：把“异步刷新+静默更新”模式抽象后，要求 AI 在不同模块复用，避免重复造轮子。
• 规范定义：把成功的协作模式固化为 AGENTS.md、PR 模板，让 AI 和团队都遵守。

五、结语

vibe coding 不是万能钥匙，也不是洪水猛兽。它是一匹烈马——跑得极快，但你需要时刻控缰。
在过去三个优化项目中，我用 3 天交付了传统模式需要 2 周的工作量，靠的正是这四条铁律。如果你也想让 AI 成为你的“超级实习生”，而不是“脱缰的野马”，不妨从今天开始，在项目根目录写下你的第一版 AGENTS.md。

念念不忘，必有回响。
AI 放大的不是代码量，而是你的判断力。规范，就是让判断力不被速度淹没的护栏。