Vibe Coding 上线之后：一次 150+ commit 的复盘

演示里 vibe coding 很爽：自然语言描述需求，几秒就出一版能跑的代码。真正麻烦的是上线以后。

我参与的一个多服务集成功能：用 AI 辅助开发，功能第一周就能演示，但修到生产可用断断续续花了一个多月，累计 150+ commits，其中大约六成是 fix——回归、边界、字段名对不上、并发坑。能力不是问题，缺的是工作方式。

一句话概括我后来信的原则：

AI 写出来的代码，质量上限 ≈ 你给它的规格有多完整。

下面是按那次复盘整理出来的经验和教训。

六类常见翻车

那次 post-mortem 里，问题大致落在这六类，后面复杂功能里也反复撞见：

1. 接口契约漂移

同一概念拆到多个模块、多个 AI session 里实现时，命名各自为政。数据模型里是 user_identifier，API 变成 user_id，前端又写成 userId。AI 没有跨会话记忆，没人盯就会散。

表现： 联调时才发现字段对不上；前端空白或显示错数据。

2. 外部系统的边角料

训练数据里有通用文档，没有你们线上那版 SDK 的怪脾气。空字符串被拒、锁名最长 64、非法 ID 抛的是 validation 而不是 not-found——文档往往写得轻描淡写。

表现： 本地 happy path 全绿，生产里冒出没处理过的异常。

3. 内部基础设施的隐性约定

审批流在非生产环境会跳步、异步任务要等事务提交后再发、分布式锁 key 有长度限制……这些东西通常不在 AI 能读到的文档里。它会按「通用正确」来写。

表现： 单测/隔离测都过，进 staging 端到端就怪。

4. 并发语义想当然

看起来像有保护的 ORM 调用，常常没有。update() 按状态过滤再改计数，可能返回「匹配 1 行」——匹配了，但未必改了。行锁挡不了两个并发 insert 同时通过 uniqueness 检查。

表现： 重复记录、压测才爆的 race；单测过、真并发挂。

5. 状态机只写了成功路径

AI 默认优化 happy path。超时但其实成功了、失败后重试、部分成功——副作用往往不对齐。成功路径清了临时缓存，超时恢复路径忘了清，脏数据靠 TTL 慢慢毒害下游。

表现： 异常恢复后状态不一致；偶发、难复现。

6. 前后端字段靠猜

后端还没给出真实响应样例，前端就按「感觉」猜字段名；中途后端改名，前端没跟上。十几个字段 × 几个弹窗，尾巴很长。

表现： UI 空白 / undefined；表单提交的 key 对不上。

心智模型要换一下

默认模型是：「AI 写代码，我 review。」——对应的就是高 fix 率。

更稳的模型是：你是架构，AI 是执行力很强的工程师。brief 完整时它很猛；brief 有洞时，它会用「看起来很合理」的猜测填满。

麻烦就在「看起来合理」：过得了 code review，过不了生产。

规格工作看起来像开销，其实是杠杆最高的一步。多花一小时把约束写清楚，往往能少掉后面一串 fix commit。

可落地的流程

Phase 0 — 设计前先自己查（先别开 AI）

约束要从一手来源来，不能交给 AI「猜」。

外部系统约束清单（每个会调到的服务）：

• 参数类型、格式、长度限制
• 空 / null / 畸形参数时的真实行为（主文档常省略）
• 错误分类：哪些是 not-found、哪些是非法输入、哪些可重试
• 幂等：同一创建接口调两次是否安全

用 SDK 源码或小实验验证，别只问 AI。

内部基建核对：

• 非生产环境审批/工作流是否跳步？
• 触发异步任务时，事务提交顺序怎么要求？
• 分布式锁 key 格式与长度上限？
• 你们 ORM 的 update 返回的是「匹配行」还是「变更行」？

找最接近的现有实现： 读一遍。项目真实惯例、可模仿的模板、和内部基建打交道的已知安全写法，往往能覆盖六七成你需要的 pattern。

Phase 1 — 设计会话（只出规格，不写实现）

单独开一个 session，明确禁止写实现代码：

I am designing a new feature module. In this session, produce only a
design document — no implementation code.

Feature summary: [一段话]

Constraints I have already verified:
[贴 Phase 0 结果]

Reference implementation from our codebase:
[贴最接近的现有代码摘录]

Produce the following sections, pausing for my confirmation after each:
1. Vocabulary table
2. Data model design
3. API contract (request/response fields)
4. State machine with side-effect matrix
5. Concurrency safety analysis

词表（Vocabulary table） 是整条链路里最重要的产物。确认前不要开写；确认后当不可变。

之后每个实现 session 都要把这张表塞进上下文。生成代码里字段名偏离表的，先改再往下走。

带副作用矩阵的状态机：

重点看最后一列：凡是落到「成功类」结果的路径，副作用要对齐。成功路径清了 cache key，其它成功类路径也必须清。

开写前的五问：

1. 兼容： 旧数据扛得住新校验吗？null / 缺字段怎么处理？
2. 入口是否一致： 某约束只在一个入口校验，批量、重试、后台任务是否同一套？
3. 生命周期： 删除/替换时清理是否用了完整唯一键？
4. 并发与发布窗口： 部署后、首次写入前，有没有危险窗口？
5. 职责边界： 有没有路径能绕过校验层？

Phase 2 — 按可验收单元写代码

每个 session 只做一个能验收的单元——能用真实调用或测试证明对了，再开下一个。

每个实现 session 开头贴的上下文：

## Session context

Task: [一句话，例如 Implement the retry endpoint for resource creation]

Vocabulary table (field names are immutable — flag any deviation):
[贴已确认词表]

Hard constraints:
- [外部约束]
- [内部基建约束]
- [并发保护要求]

Reference implementation: [贴相近代码]

Out of scope for this session:
- [明确排除项]

After implementation, produce a self-audit against these constraints before
declaring the work complete.

别一次要一整坨模块。分阶段：校验 → 核心逻辑 → 异常与边界。中间你过一眼再继续，误解的代价是一段，不是整文件。

Happy path 写完后，专门扫失败路径：

The happy path is implemented. Now audit the following failure scenarios
and identify which require additional handling in the current code:

1. What happens if [external service] returns a validation error vs. a
   not-found error vs. a timeout?
2. What happens if the async task dispatches but the process crashes before
   the database transaction commits?
3. What happens if two concurrent requests attempt to create the same resource?
4. What state is the system in if the task succeeds externally but fails to
   update the database?

Phase 3 — 联调按依赖顺序验

前端动工前，先对跑着的服务拿一份真实响应，贴进 PR：

curl -s -X GET "http://localhost:8080/api/resources/1" \
     -H "Authorization: Bearer <token>" | python3 -m json.tool

前端以这份 JSON 当权威类型，不要对着后端源码猜，更不要凭感觉。

跨多个外部系统时，由深到浅验：

1. 最底层外部资源是否真的建好、在对方控制台可见
2. 配置是否写进目标存储
3. 工作流/审批在各环境行为是否符合预期
4. 异步任务幂等（跑两遍不造重复资源）
5. 最后才接前端，且以上面证据为准

第 N 步没确认，不要开 N+1。整锅糊在一起再查，成本会陡增。

可复制模板

功能开工单（开 AI 前填）

# Feature Kickoff: [Feature Name]

## Summary
[一段话：做什么、为什么]

## External system constraints (verified from primary sources)
### [System A]
- Required parameter formats:
- Empty/null behavior:
- Error taxonomy:
- Idempotency guarantees:

### [System B]
(repeat)

## Internal infrastructure behavior
- Workflow/approval in non-production:
- Async task: transaction ordering:
- Distributed lock (key format, length):
- ORM semantics that differ from intuition:

## Reference implementation
- Closest existing feature:
- Key patterns to follow:

## Delivery decomposition
| Session | Scope | Acceptance criterion |
|---|---|---|
| 1 | | |
| 2 | | |

## Explicitly out of scope
- [List]

设计会话提示词

I am designing a new feature. In this session, produce only design
artifacts — no implementation code.

[Paste kickoff document here]

Produce the following, pausing for my confirmation after each:

1. Vocabulary table
   - Columns: Concept | DB field | API field | External system name | Constraints | Notes
   - Flag every case where the same concept has different names across systems

2. State machine with side-effect matrix
   - List every state and every valid transition
   - For each transition: trigger + complete list of side effects
   - Explicitly mark side effects that must be symmetric across all
     success-outcome transitions

3. Concurrency safety analysis
   - Enumerate every operation that could have concurrent execution
   - For each: describe the race condition if unprotected
   - Recommend the specific protection mechanism and explain why
     alternatives would not work

4. Pre-coding design review
   - Audit against: backward compatibility, interface completeness,
     data lifecycle, concurrency/deployment timing, responsibility boundaries
   - Rate each: Pass / Risk / Issue

实现会话上下文

## Session context — [Module name]

Task: [One sentence]

This session scope: [What to implement]
Out of scope: [What not to implement]

Vocabulary table (immutable — reject and flag any deviation):
[Paste confirmed vocabulary table]

Hard constraints:
[One constraint per line]

Reference pattern from our codebase:
[Paste relevant excerpts]

Delivery instructions:
- Implement in stages: validation first, then core logic, then edge cases
- After each stage, wait for my confirmation before continuing
- After completing all stages, run a self-audit against each constraint above
- Flag anything that required an assumption not covered by the constraints

写完后的自检（先让 AI 对自己输出跑一遍）

Audit the code you just wrote against each item below.
For each item: state Pass, Risk, or Issue with a one-line explanation.

[ ] Field naming: Every field name matches the vocabulary table exactly.
[ ] External API protection: No external API call can receive a null,
    empty string, or malformed identifier.
[ ] Concurrency protection: Every check-then-write uses the correct
    protection. Update return values are not used as concurrency signals.
[ ] Side-effect symmetry: Every success-outcome path does the same
    cleanup/notification as the primary success path.
[ ] Workflow integration: Accounts for non-production behavior in constraints.
[ ] Async task ordering: Dispatch after DB commit, not before.
[ ] Error taxonomy: not-found / invalid input / timeout handled differently.
[ ] Scope discipline: Nothing changed outside stated session scope.

后来反复踩过的写法（尽量别再来）

1. 一锅端 session — 一个对话从 model 写到 API 再写到异步任务。中间状态没法验收。改成：一 session 一可验收单元。
2. 命名边写边定 — 字段名在实现时才冒出来，全局必然分叉。词表先确认，偏离当 bug。
3. 约束靠猜 — 「AI 应该知道长度限制」「文档应该那样」。外部边角要用一手来源钉死并写进 brief。
4. 状态机乐观症 — 成功路径漂亮，失败恢复留脏状态。先画副作用矩阵，成功类路径对齐。
5. 看起来像并发保护 — 行锁挡不了并发 insert；update 返回值不是「已变更」。在约束里写明具体原语和为什么更简单的方案不行。
6. 接口靠猜 — 前端对着假想字段开发。先拿真实响应样例。
7. 基建惊喜 — 隔离能跑、staging 怪。内部行为写进 kickoff，当外部约束同等对待。
8. 上线后靠 fix 补规格 — 规格洞留给生产发现。设计评审里发现的问题，在设计里改，不要攒到 hotfix。

值不值

粗算那次：规格不够充分时，大约近百个 fix commit。按每个 fix 端到端（改、审、合、验、偶发 hotfix）四十五分钟量级估，就是几十人时，还会阻塞其他相关项目，影响进度。

前面 Phase 0 + 设计会话通常只要几个小时。少掉几个 fix 就回本了；做得认真时，联调层那类 bug 大半能在写第一行代码前消掉。

钱不是花在流程上，是把发现成本从生产挪回设计——设计阶段改一处几乎零成本。

收尾

AI 不知道你没告诉它的事。规格空白处的每一个「合理猜测」，都是等负载来撞的 latent bug。

Vibe coding 不是跳过设计的捷径，而是放大器：设计清楚时，出活又快又稳；设计糊时，出的是看起来很完整、洞却埋得很深的代码。功夫在 brief，不在 prompt 文采。

细节已做泛化。模板和流程适用于在生产环境里用 AI vibe coding 写代码的场景。