Vibe Coding 下的效率定义与规范建设
三个优化项目，116 份文档，3 天交付------当 AI 能几分钟生成几百行代码时，传统的"代码行数/人天"已经失效。我们需要重新定义效率，更需要建立规范，防止脱缰。
一、效率不是"AI 写得多快"，而是"正确交付多快"
2026 年 6 月，我在 ScienceClaw 平台上连续完成了三个优化项目：并发测试工具（concurrent-tester） 、Token 日志采集 、Skill 刷新性能优化 。它们共同验证了一件事：vibe coding 的真实效率 ≠ AI 生成代码的速度，而是 "从需求到生产稳定运行的总时间，减去除错和返工的时间"。
| 项目 | 传统预估 | Vibe Coding 实际 | 返工比例 | 主要返工原因 |
|---|---|---|---|---|
| 并发测试工具 | 3--5 天 | 2 天 | ~15% | Pod 动态发现、超时配置 |
| Token 日志采集 | 2--3 天 | 12.7 小时 | ~20% | usage-only chunk 解析、logger 双通道 |
| Skill 刷新优化 | 5--7 天 | 3 天 | ~10% | 哨兵值设计争议、并行同步 |
数据清晰地显示：当返工比例控制在 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 下的效率？我的答案是：
效率 = (AI 生成速度 × 正确率) - (人机沟通成本 + 返工成本)
当正确率足够高、返工率足够低时，vibe coding 就是超级生产力；反之则是灾难。而正确率和返工率，取决于你是否建立了清晰的协作规范，以及你是否具备元能力来驾驭 AI：
- 失效分析 ：AI 报错时，不是简单地"让它重试"，而是定位根因（如
_git_clone无超时），然后让 AI 针对根因修复。 - 系统抽象：把"异步刷新+静默更新"模式抽象后，要求 AI 在不同模块复用，避免重复造轮子。
- 规范定义 ：把成功的协作模式固化为
AGENTS.md、PR 模板，让 AI 和团队都遵守。
五、结语
vibe coding 不是万能钥匙，也不是洪水猛兽。它是一匹烈马------跑得极快，但你需要时刻控缰。
在过去三个优化项目中，我用 3 天交付了传统模式需要 2 周的工作量，靠的正是这四条铁律。如果你也想让 AI 成为你的"超级实习生"，而不是"脱缰的野马"，不妨从今天开始，在项目根目录写下你的第一版 AGENTS.md。
念念不忘，必有回响。
AI 放大的不是代码量，而是你的判断力。规范，就是让判断力不被速度淹没的护栏。