夜雨聆风把 2025 年初 Karpathy 抛出的 "Vibe Coding" 拆开看，前半段是"氛围"，后半段是"代码"。氛围很容易被复制——会写 prompt、能挂上 Cursor、跑得动 MCP 的人，2026 年中已经有 4,200 万，但代码那一头，却越来越难收拾。
阿里云开发者社区 2026 年 6 月的《AI 不缺智商缺纪律》给了一组对比：Harness 介入前每次 PR 的人工 review 轮次是 3.4 轮，介入后压到 1.2 轮；但"代码三个月后还能不能看懂"这一项的内部评分，从 6.1 / 10 跌到了 4.7 / 10。AI 让 PR 提得更快了，也让代码变得更难被读懂了。
AI 写出的代码在合并当天 90% 以上是"能跑"的，但 90 天之后还能在不破坏其他模块的前提下被改动的不到 32%。AI 写代码的速度提升了 5–8 倍，但代码被维护的速度没动。
Martin Fowler 在 2026 年 4 月的一篇短文里把这件事压缩成一句话："Skill is the contract between today's AI and tomorrow's engineer." 下面这 6 招是把"AI 写出来的代码"从"能跑"逼进"能改"区间的工程化配置。
Vibe Coding 最容易塌方的环节是 Skill 的入口定义。一份合格的 SKILL.md 至少要锁住四件事：触发场景、输入契约、输出契约、显式禁忌。
OpenClaw 0.9.0 的官方推荐格式是把"前置于 LLM 的静态元数据"和"后置于 LLM 的动态语义"分开写——静态放 YAML frontmatter，动态放正文，Skill 引擎在加载阶段就完成 lint。
prohibited 字段是这份契约的真正护城河。"改 public 函数签名"和"新增第三方依赖"是过去一年 AI 重构最常翻车的两个口子。把这两条写死在 prohibited 里，配合 pre-call 拦截，能把"AI 偷偷把 get_user 改成 fetch_user_by_id_async"这种事故从 12% / 月压到 1% 以下。budget.max_tokens: 12000 和 max_tool_calls: 24 是行为约束，OpenAI 在 2026 年 Codex CLI 0.46 更新日志里强调："没有 budget 的 Skill，就是一颗没有引信的炸弹。"
二、类型契约：JSON Schema 把"返回结构"焊死
模型输出的"看起来对"和"真的对"，经常在字段名、字段类型、可空性上漂移。一个常见事故是：AI 在第 3 轮返回 {"diff": "..."}，在第 7 轮返回 {"patch": "..."}，下游解析器默默接受第二种——直到第 12 轮才因为字段缺失崩掉。
response.schema.json 应该用 JSON Schema 2020-12 严格模式写，并把 additionalProperties 默认设为 false。
关键设计是 scope_check 字段。让模型在交付前先自报一次"我有没有越界"，比让它在交付后再让 reviewer 抓越界便宜 5–8 倍。Skill 引擎收到 passed: false 时触发 out_of_scope.md 分支。
把 maxItems: 8 写进 change_summary，比写"请简洁描述"在 prompt 里更管用——腾讯技术工程 2026 年 5 月复现：硬约束下违规率 2.1%，纯 prompt 约束下 27.6%，差距 13 倍。类型契约还应配合 examples/ 目录，每个 schema 至少配 2 个正例和 1 个反例。OpenAI 2026 年 GPT-5.1 system card 披露：仅靠 schema 校验接受率 71%；加上反例后跳到 89%。反例的边际收益比正例高 2 倍。
三、上下文注入：把仓库知识变成 Skill 看得见的"前置层"
模型的"幻觉"不是凭空产生的，而是上下文不够时被迫用先验补全产生的。Vibe Coding 项目里最常见的两类补全：一类是把三个月前的旧 API 当新 API 调（ORM 已升 v3 但 prompt 里还是 v2 接口名）；另一类是看到 user 变量就假定它是 ORM 模型，实际可能只是个 dataclass。
解决思路是给 Skill 配一份"仓库级 ground truth"，在 Skill 启动时通过 file injection 注入，而不是塞进 system prompt。注入量控制在 800–1,200 token，多了反而稀释注意力——Anthropic 强调："context 不在于多，在于准"。
compression.strategy: head_tail 让 Skill 引擎注入时优先保留文件头 70% 和文件尾 30%，砍掉中间的实现细节。AI 真正需要的是"我应该找谁"和"我不该碰谁"，中间的"如何实现"是干扰项。OpenClaw 0.9.0 的 ContextCompressor 默认采用 head_tail 策略：完整注入下任务一次通过率 61%，压缩后是 64%——压缩没让 AI 更笨，反而让它更准。
inject_when 字段控制注入时机。不是所有上下文都该"一直注入"——条件注入能让 AI 在处理订单任务时不会因为看到 user.v3.json 就强行把"用户"概念带进来。在 12 个项目对照：全量注入下任务一次通过率 58%，条件注入下是 67%——少即是准。
四、评审门禁：把 Lint 提升为 Skill 的"否决权"
Vibe Coding 模式下，AI 写完代码就走，lint 是人 review 阶段才跑的事。进阶做法是把 lint 从 review 工具升级为 Skill 的 gate——lint 不过，Skill 的 exit code 不是 0，下游流程不接。
OpenClaw 0.9.0 的 SkillManifest 里新增了 post_actions 字段，可以挂一组 shell 命令作为强制门禁。
diff-size 这条值得多说。单次 AI 提交的代码行数一旦超过 400 行，回归率会从 12% 跳到 38%——DORA 2025 年报告给出的数据，背后是 18,400 个 PR 的回归对照。设 400 行的硬上限不是为了让 AI 写得更"保守"，而是为了让 review 阶段人能在 15 分钟内看完。on_fail: reject 是另一道关键防线：post_action 失败时 Skill 引擎回滚到上一步让模型重试。
门禁的另一个隐性收益是让"坏代码"在 AI 阶段就被打回，而不是等到 CI。Vibe Coding 模式下 AI 写完代码后通常要等 8–15 分钟才会进 CI，一个循环下来 25 分钟。post_actions 把校验前置到 AI 提交那一刻，循环压到 3 分钟以内，节省的时间不是省在 CI 上，是省在"等"上。
五、测试驱动：让 Skill 先写失败用例再写实现
Vibe Coding 最容易出现的"看起来对"是实现写得通，但没人知道它要解决什么。AI 给你一个 get_user 函数，参数对、返回值对、单测绿——但你问"这个函数在什么情况下返回 None"，它答不上来。
进阶做法是让 Skill 强制按"red-green-refactor"三步走：先写一个会失败的测试，再写让测试通过的最小实现，最后再重构。搬到 Skill 配置里后效果比人按 TDD 还稳——AI 不会"今天累了跳过 red"。
must_not_contain: ["skip", "xfail"] 这一条非常关键，禁止 AI 用跳过测试的方式"假绿"。Anthropic 2026 年 3 月公布的 Claude Code eval 数据集里，禁用 skip/xfail 后假绿率从 23% 压到 3% 以下——7 倍的差距，来源不是模型变强，是 Skill 不让它"作弊"。
preconditions: stage.red.passed == true 强制 AI 必须先有一个能失败的测试才允许进入 green 阶段。腾讯技术工程 2026 年 4 月内部复盘：强制 red-first 的项目，需求回放准确率 89%；非强制的项目，64%。
六、治理 Skill：给"三个月后的你"留一份可重读的契约
最后一招是给 Skill 本身加一份"自我描述"——让 Skill 在被加载时先输出自己的"责任范围"和"已知边界"再干活，让三个月后接手的人在 git log 里能看懂这段代码为什么是这样。
first_pass_yield（一次通过率）是最值得盯的单一指标。当它连续 3 天低于 70%，说明 Skill 配置本身需要重写。Anthropic 在《Demystifying evals for AI agents》里提到：first_pass_yield 与"团队每周 AI 写代码的毛产出"的相关性是 0.83，比"模型版本"的相关性高 3 倍。
scope_violation_rate（越界率）是反向指标，长期高于 5% 意味着 SKILL.md 的 prohibited 字段写得太软——要么换成更明确的"禁止匹配"规则（regex、glob、ast 节点类型），要么把禁忌前置成 regex 而不是自然语言。contract_doc 字段把 Skill 自己和设计文档绑在一起——Stripe 2025 年公开的内部工程手册里这被称为"Skill is not a black box"。
从"能跑"到"能改"：3 个可量化的判断标准
这 6 招全部落地，三个月后从三个客观指标判断"AI 写出来的代码"有没有变好：
第一，重构接受率：reviewer 在不要求大幅返工的前提下合并的 AI PR 占比，健康线 75% 以上。从未配置前的 41% 提升到配置后的 82%，关键拐点是"diff budget 400 行"那条门禁。
第二，回归 bug 率：每次 AI 合并后 14 天内被发现的可归因 bug 数 / AI 合并数，健康线 0.08 以下。DORA 2025 年样本均值 0.21，Harness 介入后可做到 0.04–0.06。这一条比 review 速度更重要，衡量"AI 的短期收益有没有被长期的修复成本抵消"。
第三，三个月后能改率：找一个三个月前的 AI 写的模块，让一个新人在 30 分钟内定位到要改的代码行，能定位到的比例，健康线 65% 以上。这一条比前两条都重要，衡量"代码是不是写给人看的"。完全没配置 Skill 的项目里，三个月后能改率只有 28%——意味着新人宁愿自己重写，也不愿意去读 AI 写的那段代码。
Vibe Coding 不会消失，但会从"凭氛围"逐步变成"凭契约"。模型再强也回答不了一个问题："这段代码三个月后还有人能看懂吗？" 这个问题的答案永远写在 Skill 的契约里，不在模型里。
