开发了一个 Agent Skill：把 Vibe Coding 从「想到哪写到哪」，变成可恢复、可验证、可持续迭代的工作流

欢迎 Star、体验与贡献： 👉开源地址：https://github.com/sz-xiaohuolong/vibe-workflow

背景

先说结论：AI 已经很会写代码了，但「会写」不等于「会把项目做完」

这两年，我越来越频繁地使用 Codex、Claude Code 这类 Coding Agent 做真实项目。

刚开始的时候，体验确实很爽：

「帮我做一个录音软件。」

几分钟后，目录有了，页面有了，代码也有了。

但项目一旦从 Demo 进入真实开发，问题很快就会出现。

比如：

需求还没有想清楚，Agent 已经开始搭架构、写代码；
开发到一半随口说一句「顺便加个功能」，整个版本范围开始漂移；
新开一个会话，Agent 不知道昨天做到哪里，只能重新猜；
修一个 Bug 连续 Patch 多次，修 A 坏 B，代码越来越乱；
代码写完了，但测试没跑、Build 没过，Agent 仍然告诉你「Done」；
v0.1、v0.2、v0.3 的文档混在一起，旧需求重新污染当前上下文；
你只是让它改一个小功能，它却顺手碰了 Schema、权限甚至外部服务。

这些问题的共同点不是：

AI 不会写代码。

而是：

AI 缺少一套能够约束「什么时候做什么、什么时候必须停、什么才算完成」的软件工程工作流。

于是我做了 Vibe Workflow。

1. Vibe Workflow 是什么？

Vibe Workflow 是一个 Agent Lifecycle Orchestrator Skill。

它的职责不是重新发明一套 TDD、Debugging 或 Code Review 教程，而是站在这些专业能力之上，负责整个项目的生命周期编排。

我给它定了一个很简单的边界：

Grill Me 负责确认做什么；Vibe Workflow 负责可靠地把它做出来。

换句话说：

▼
text
复制代码
模糊想法
   ↓
Grill Me / Requirement Clarification
   ↓
冻结需求
   ↓
Vibe Workflow
   ↓
SPEC
   ↓
Technical Design
   ↓
Implementation Plan
   ↓
Build
   ↓
Verify
   ↓
Review
   ↓
Ship
   ↓
Maintain
   ↺

Vibe Workflow 可以作为统一入口。

如果它发现当前需求还没有冻结，就会停止工程活动，并把需求澄清路由给 grill-me 或等价能力；需求满足工程入口条件后，再继续后面的 SPEC、设计和实现。

这也是我最希望它解决的问题：

让用户不需要自己记「现在该调用哪个 Skill」，而是让 Workflow 根据项目状态完成编排。

2. 为什么我不想再用「一个超级 Prompt」管理项目？

很多 Vibe Coding 工作流最后都会变成一段越来越长的提示词：

▼
text
复制代码
先读需求
→ 再设计
→ 再编码
→ 记得测试
→ 不要乱改
→ 遇到 Bug 要分析
→ 记得更新文档
→ 记得 Git Commit
→ ...

问题在于，Prompt 越长，并不代表工程越可靠。

真正稳定的软件项目，需要的是：

状态；
事实源；
决策关卡；
可恢复的进度；
清晰的版本边界；
可验证的完成证据；
按需加载的上下文；
专业 Skill 之间的编排。

所以 Vibe Workflow 的核心思路不是：

给 Agent 更多指令。

而是：

给 Agent 一个可以运行的软件工程 Harness。

3. 整体架构：三层，而不是一个 Skill 包打天下

我把整个体系分成三层。

▼
mermaid
复制代码
flowchart TD
    A["用户想法 / 新版本需求"] --> B["Requirement Layer"]
    B --> C["Grill Me / Requirement Clarification"]
    C --> D["Frozen Requirement Baseline"]

    D --> E["Orchestration Layer"]
    E --> F["Vibe Workflow"]

    F --> G["Capability Layer"]
    G --> H["Brainstorming"]
    G --> I["Writing Plans"]
    G --> J["TDD"]
    G --> K["Systematic Debugging"]
    G --> L["Code Review"]
    G --> M["Verification"]

第一层：Requirement

负责把模糊想法问清楚，并冻结当前 Release 的产品范围。

第二层：Vibe Workflow

负责判断：

当前处于什么状态？
下一步应该做什么？
哪些动作允许 Agent 自主完成？
哪些事情必须等待人类确认？
应该调用哪个专业 Skill？
结果应该写回哪个项目事实源？

第三层：专业能力

例如 Superpowers 中的：

brainstorming
writing-plans
test-driven-development
systematic-debugging
requesting-code-review
verification-before-completion

Vibe Workflow 不复制它们。

它只负责：

When to invoke what, and where the result becomes durable project state.

4. 第一条铁律：工程开始之前，需求必须冻结

这是整个 Skill 最核心的设计。

新项目或新 Release 想进入 SPEC、技术设计或 Build，至少要满足：

▼
text
复制代码
Requirement Status == FROZEN
Open Questions == None
Current Release ID exists
Acceptance Goals are testable

如果没有满足，就不能因为用户说了一句：

「直接做吧。」

Agent 就开始脑补需求。

在 Vibe Workflow 里：

授权实现，不等于授权定义产品范围。

我把这条原则总结成了一句话：

What to build is frozen. How to build it is delegated.

「做什么」必须由人确认。

但「怎么实现」尽量交给 Agent 自己解决。

例如这些通常不需要反复问用户：

内部函数叫什么；
helper 怎么拆；
私有接口怎么组织；
测试文件放在哪里；
沿用现有项目规范时，目录怎么安排。

而这些必须经过 Human Decision Gate：

产品范围变化；
Requirement Change；
Public API Breaking Change；
Database Schema / Migration；
权限与安全模型；
破坏性操作；
新的外部付费服务；
Push、PR、Publish、Deploy、Release。

这解决了两个极端：

既不让 Agent 擅自替你做产品经理，也不让它为了一个变量名来问你三遍。

5. 一个项目不是一次 Prompt，而是多个 Release

真实项目一定会迭代。

比如：

▼
text
复制代码
Project
├── v0.1
├── v0.2
├── v0.3
└── v1.0

所以 Vibe Workflow 把 Release 作为主要生命周期单位。

每个版本都走一次完整但可裁剪的工程流程：

▼
mermaid
复制代码
flowchart LR
    A["REQUIREMENTS_FROZEN"] --> B["SPECIFIED"]
    B --> C["DESIGNED"]
    C --> D["PLANNED"]
    D --> E["BUILDING"]
    E --> F["VERIFYING"]
    F --> G["REVIEWING"]
    G --> H["READY_TO_SHIP"]
    H --> I["RELEASED"]

这意味着：

v0.1 有自己的冻结需求和 SPEC；
v0.2 有自己的冻结需求和 SPEC；
v0.3 也一样。

不会把所有版本一直追加在同一份 PRD 后面。

6. 为什么我用 SPEC，而不是继续堆一套大而全 PRD？

我希望 Agent 看到的是明确、可实现、可验证的产品行为。

所以在这个体系里：

`PROJECT_BRIEF`

负责回答：

这个 Release 到底要做什么？

包括：

Problem
Target User
Core Scenario
In Scope
Out of Scope
Constraints
Acceptance Goals
Requirement Status

`SPEC`

负责回答：

被冻结的需求，具体应该表现成什么行为？

例如：

▼
text
复制代码
REQ-003 Start Recording

AC-007
点击开始录音后进入 recording 状态。

AC-008
录制失败时必须显示明确错误，不能静默失败。

因此，SPEC 不是另一份重复 PRD。

它更像：

冻结需求面向工程实现和测试的 Effective Spec。

7. 历史版本和当前事实必须分开

这是我在长期使用 Coding Agent 后越来越重视的一点。

如果把所有东西都当成「Living Document」，历史会被不断改写。
如果把所有东西都按版本复制，Agent 又会被历史上下文淹没。

所以 Vibe Workflow 将文档分成两类。

Released Artifacts：保存当时发生了什么

例如：

▼
text
复制代码
docs/vibe/releases/v0.2/
├── PROJECT_BRIEF.md
├── CHANGE.md
├── SPEC.md
├── IMPLEMENTATION_PLAN.md
└── VERIFICATION.md

Release 完成后，历史 Artifact 原则上封存。

Living Documents：描述项目现在是什么样

例如：

▼
text
复制代码
docs/vibe/
├── PROJECT.md
├── TECH_DESIGN.md
└── PROGRESS.md

重大架构变化则通过：

▼
text
复制代码
docs/vibe/decisions/

持续记录。

这个模型可以概括成：

Released artifacts preserve history. Living documents describe current truth.

8. `PROGRESS.md`：让 Agent 真正支持「明天继续」

很多人说 Agent 有记忆。

但对软件工程来说，我更相信：

Repository is memory. Chat is conversation.

聊天是瞬时的。

仓库才是持久状态。

所以 PROGRESS.md 在 Vibe Workflow 里非常重要。

它负责记录：

▼
text
复制代码
Current Release
Current Requirement Baseline
Current Workflow State
Current Slice
Current Task
Last Stable Commit
Completed Tasks
Verification Evidence
Known Bugs
Blockers
Open Decisions
Next Task

这样今天关闭 Codex，明天重新打开，只需要：

▼
text
复制代码
$vibe-workflow 继续当前软件项目，并从仓库事实恢复正确状态。

Agent 会根据 Git、代码、测试和项目文档恢复当前状态，而不是靠聊天记忆猜。

9. Context Governor：不是上下文越多越好

这是我认为 Vibe Coding 很容易被忽略的一点。

很多时候，我们会下意识地认为：

「多给 Agent 一些上下文，总不会错。」

但长期项目里，大量历史信息本身就是噪声。

所以 Vibe Workflow 默认遵循：

Minimal Sufficient Context

例如当前任务只是「实现删除录音」，它应该优先读取：

▼
text
复制代码
AGENTS.md
PROGRESS.md
当前 Release 的 Effective SPEC
对应 REQ / AC
TECH_DESIGN 的相关部分
当前 Task
相关代码
相关测试

而不是默认读取：

▼
text
复制代码
全部历史 Release
全部 Bug
全部 Decision
整个 Git History
整个仓库

目标不是让 Agent「知道所有事情」。

而是让它：

知道完成当前任务所必需的事情。

10. Tiny / Bounded / Architectural：复杂任务严谨，简单任务不官僚

工程流程一旦做重，很容易走向另一个极端：

改一个按钮文案，也要写 5 份设计文档。

所以 Vibe Workflow 会同时判断：

▼
text
复制代码
Task Type
+
Task Complexity

任务类型包括：

▼
text
复制代码
NEW_PROJECT
FEATURE
BUG
REFACTOR
SPIKE
REQUIREMENT_CHANGE

复杂度包括：

▼
text
复制代码
Tiny
Bounded
Architectural

例如：

请求	分类	处理方式
「把 Start 改成 Record」	FEATURE + Tiny	精确修改、验证，不生成完整设计文档
「增加删除录音」	FEATURE + Bounded	Acceptance + Task Plan + Tests
「增加多设备云同步」	FEATURE + Architectural	需求冻结 + 设计决策 + 完整计划

我很喜欢这句话：

Complex tasks are rigorous. Simple tasks are not bureaucratic.

11. Decision Gate：风险不是看改了多少行代码

一个改动只有 1 行，也可能非常危险。

例如：

▼
text
复制代码
isAdmin = true

所以风险不能简单通过「代码量」判断。

Vibe Workflow 会优先检查：

Product
Schema
Security
Destructive Operation
External Service
Shipping

等 Decision Gate。

特别是 Schema 这类改变，不能出现：

▼
text
复制代码
Agent：
“为了实现功能，我顺手给 users 表加了两个字段。”

而应该先：

▼
text
复制代码
Investigate
   ↓
Proposal
   ↓
Options / Trade-offs
   ↓
Recommendation
   ↓
Explicit Human Approval
   ↓
Migration
   ↓
Verification

调查完成，不等于获得执行授权。

12. Circuit Breaker：AI 最危险的不是第一次写错，而是连续自信地写错

这一点我特别想做进 Skill。

典型 Vibe Coding Bug 修复流程：

▼
text
复制代码
改一个参数
↓
没好
↓
再改一个参数
↓
又坏一个地方
↓
再 Patch
↓
代码越来越乱

Vibe Workflow 加入了 Circuit Breaker。

当出现：

同类失败连续 3 次；
修 A 坏 B/C；
底层架构假设失效；
修改范围持续扩大；

就必须：

▼
text
复制代码
STOP PATCHING
   ↓
Preserve Last Known Good State
   ↓
Record Debug Snapshot
   ↓
Operational Status = REPLAN_REQUIRED
   ↓
Systematic Debugging / Redesign / Replan

它会区分：

Retry

和：

Replan

不是所有失败都值得「再试一下」。

13. Verification 和 Shipping 必须「两权分立」

这是另一个我非常坚持的设计。

▼
text
复制代码
Verification Status
=
客观证据说明了什么

Shipping Authorization
=
人类是否允许执行发布动作

比如：

「测试来不及跑了，先发，我承担风险。」

这是一个合法的业务决定。

但它不能把：

▼
text
复制代码
UNVERIFIED

改写成：

▼
text
复制代码
VERIFIED

在 Vibe Workflow 中：

人可以接受风险，但不能修改事实。

没有 fresh verification evidence，就不能声称：

▼
text
复制代码
DONE
FIXED
VERIFIED
READY_TO_SHIP

同时，Push、PR、Publish、Deploy、Release 仍然需要明确的人类授权。

14. Build 也不是「读完 SPEC，然后一次性写完整项目」

我更希望开发循环是这样的：

▼
mermaid
复制代码
flowchart TD
    A["Select Next Task"] --> B["Assemble Task Context"]
    B --> C["Inspect Existing Code / Tests"]
    C --> D["RED：先看到正确失败"]
    D --> E["Minimal Implementation"]
    E --> F["GREEN"]
    F --> G["Refactor"]
    G --> H["Task Verification"]
    H --> I["Inspect Diff / Review"]
    I --> J["Commit"]
    J --> K["Update PROGRESS"]
    K --> L["Next Task"]

每个版本内部还可以继续拆：

▼
text
复制代码
Project
  ↓
Release
  ↓
Phase（可选）
  ↓
Vertical Slice
  ↓
Task

尽量按照可运行、可测试、可提交的 Vertical Slice 推进，而不是先把所有数据库写完、再把所有后端写完、最后一起调试。

15. Bug 不应该重新走完整产品流程

如果只是普通 Bug：

▼
text
复制代码
Bug Report
   ↓
Reproduce
   ↓
Evidence
   ↓
Root Cause
   ↓
Regression Test
   ↓
Fix
   ↓
Verify

但如果调查后发现：

不是实现错了，而是 SPEC 本身定义错了。

那么：

▼
text
复制代码
BUG
↓
REQUIREMENT_CHANGE

必须重新经过 Requirement Change Gate。

这可以避免 Agent 为了「修 Bug」偷偷改产品定义。

16. 它不是 Superpowers 的替代品，而是编排层

Vibe Workflow 当前已经为专业 Skill 预留了明确的路由。

例如：

场景	推荐能力
Requirement 不完整	`grill-me` 或等价 Requirement Clarification
Architectural Design	`superpowers:brainstorming`
多步骤 Implementation Plan	`superpowers:writing-plans`
Feature / Bug / Refactor	`superpowers:test-driven-development`
Bug / Test Failure	`superpowers:systematic-debugging`
重要 Task / Feature	`superpowers:requesting-code-review`
完成声明之前	`superpowers:verification-before-completion`

这也是整个 Skill 的定位：

Vibe Workflow 负责生命周期；专业 Skill 负责专业动作。

17. Before vs After：几个最典型的使用场景

场景	普通 Coding Agent	Vibe Workflow
模糊需求让它「直接做」	开始脑补产品和架构	Requirement Gate 未通过，先澄清并冻结
开发中说「顺便加云同步」	直接开始加功能	识别 Requirement Change，等待明确决策
改一个按钮文案	可能过度规划	Tiny Task，最小修改 + 验证
想改数据库 Schema	顺手写 migration	Schema Gate：调查 → 提案 → 人类批准 → 执行
Bug 连续修 3 次失败	继续 Patch	Circuit Breaker → `REPLAN_REQUIRED`
新开会话继续项目	依赖旧聊天上下文	从 Repository + Git + PROGRESS 恢复
代码写完但没测试	「Done」	保持 `UNVERIFIED`
老板说「先发布」	可能把发布当验证完成	Shipping Authorization 与 Verification 分离

18. 这个 Skill 自己也做了测试

我不希望它只是：

「一篇看起来很完整的软件工程 Prompt。」

所以仓库里专门保留了 Skill 行为测试：

▼
text
复制代码
tests/
├── scenarios.md
├── rubric.md
├── validate_skill.sh
└── results/

当前 V0.1 README 中记录了：

4 类 control / candidate wording micro-tests；
20 个批准场景；
5 个独立审查回归场景。

测试重点不是某个函数返回值，而是 Agent 在压力下是否真的遵守工作流。

例如：

用户催促时会不会绕过 Requirement Gate？
Tiny Task 会不会被过度文档化？
Schema Change 会不会偷跑？
连续失败后是否会触发熔断？
没有 Fresh Evidence 时会不会假装完成？
当前版本是否只读取当前 Effective SPEC，而不是把所有历史版本塞进 Context？

19. 如何安装？

当前仓库已经可以作为 Codex Agent Skill 直接安装。

方式一：在 Codex 中安装

把下面这句话发送给 Codex：

▼
text
复制代码
请使用 $skill-installer 从 https://github.com/sz-xiaohuolong/vibe-workflow/tree/main/skills/vibe-workflow 安装这个 Skill

方式二：使用 Codex 内置安装脚本

▼
bash
复制代码
python3 "${CODEX_HOME:-$HOME/.codex}/skills/.system/skill-installer/scripts/install-skill-from-github.py" \
  --repo sz-xiaohuolong/vibe-workflow \
  --path skills/vibe-workflow

安装后，从下一轮会话开始使用：

▼
text
复制代码
$vibe-workflow 继续当前软件项目，并从仓库事实恢复正确状态。

对于一个需求还没有冻结的新项目，也可以直接从 $vibe-workflow 进入；它会根据 Requirement Gate 判断是否需要先调用 grill-me 或等价的需求澄清能力。

20. 如何使用？

安装完成、从下一轮会话开始后，Vibe Workflow 主要有三类用法。

1）新项目从零开始。 对一个需求还没有冻结的新项目，直接对 Codex 说：

▼
text
复制代码
$vibe-workflow 我想做一个录音软件

它会先检查 Requirement Gate：需求未冻结就暂停工程活动，先路由到 grill-me 或等价的需求澄清能力；需求冻结后再自动进入 SPEC、设计、Build、Verify、Review、Ship 的后续流程。

2）继续昨天的项目。 每天开始工作时说：

▼
text
复制代码
$vibe-workflow 继续当前软件项目，并从仓库事实恢复正确状态。

Agent 会根据 Git、代码、测试和 PROGRESS.md 恢复当前状态，而不是靠聊天记忆猜。

3）日常迭代与 Bug 修复。 新增功能就把需求说清楚，交给 Workflow 走一次 Release 流程；修 Bug 就直接描述现象，它会走「Reproduce → Root Cause → Regression Test → Fix → Verify」；想改 Schema 或发布，它会先触发对应的 Decision Gate，等你明确授权后再执行。

使用上记住三句话即可：

你确认做什么，实现交给 Agent；发布与破坏性操作必须你点头；没有验证证据，Agent 不能说 Done。

21. 哪些人可能适合用它？

如果你只是让 AI：

「帮我写一个正则表达式。」

那你大概率不需要它。

但如果你在做下面这些事情，它可能会比较有价值：

个人开发者

使用 Codex / Coding Agent 从 0 到 1 做真实项目，希望几周、几个月后仍然能继续维护。

Vibe Coding 重度用户

已经发现「生成代码很快，但控制代码熵和需求漂移越来越难」。

Agent 工程实践者

希望把 Requirement、Design、Plan、Build、Verification、Release 变成 Agent 可执行的生命周期。

多 Agent / 多 Skill 使用者

已经安装多个专业 Skill，但缺少一个统一的 Lifecycle Orchestrator 来判断什么时候应该调用谁。

长期维护项目

需要跨会话、跨 Release、跨 Bug 修复持续迭代，而不是只做一次性 Demo。

22. 我对 Vibe Coding 的一个判断

我现在越来越觉得：

Coding Agent 的能力越强，Workflow 反而越重要。

模型弱的时候，人需要告诉它每一步怎么写。

模型越来越强之后，真正重要的问题开始变成：

它有没有跑偏？
它有没有偷偷扩大范围？
它读取的是不是正确上下文？
它现在到底在 v0.2 还是 v0.3？
它为什么说完成？
这次修改有没有证据？
哪些事情应该自己决定？
哪些事情必须停下来问人？
新会话能不能无损继续昨天的工作？

换句话说：

AI 编码的瓶颈，正在从「Code Generation」逐渐转向「Engineering Control」。

Vibe Workflow 就是我对这个问题的一次尝试。

它不是为了让 Agent 一次生成更多代码。

而是为了让一个项目经历：

▼
text
复制代码
10 个 Task
→ 50 个 Task
→ 3 个 Release
→ 多次 Bug 修复
→ 多次新会话

之后，依然保持：

可理解、可恢复、可验证、可迭代。

23. 写在最后

这个项目目前还是 V0.1。

我更希望它未来变成一个真正经过真实项目不断压测和修正的工作流，而不是继续往 SKILL.md 里堆规则。

我给它保留了几条一直不会变的原则：