本文档描述 Hermes Agent（AI 编排者） 如何具体编排六阶段 Vibe Coding 全过程，包含入口判断、todo 追踪、每个阶段的精确工具调用序列、阶段间自动推进、反馈循环与异常处理。

为什么需要编排手册？

AI 编程正从”单轮对话生成代码”进化为多 Agent 协作的工程化流程。一份精确的执行手册让 AI Agent 在独立运行时保持一致的行为模式：

  • 阶段解耦：每阶段有明确输入/输出，互不干扰
  • 质量门禁：每个产出经过对抗性审阅
  • 上下文治理：防止长流程中记忆偏差与幻觉
  • 反馈循环：自动检测失败并修复，而非盲目继续

入口触发与初始化

触发条件

以下任一情况进入 Vibe Coding 模式：

1
2
3
4
1. 用户说"启动项目"、"开始开发"、"做这个项目"、"vibe coding"
2. 用户说"我们做 X 项目" — 明确要建一个完整项目
3. 用户发来一个文档/截图/链接说"帮我实现这个"
4. 用户说"继续上次的项目" — 触发 session_search 找回状态

初始化流程

  1. 检查工作区：搜索 workspace/plans/* 判断是否有已有同名项目规划
  2. 设置 todo 列表：标记 Stage 1 为 in_progress，其余为 pending
  3. 记录项目指针到 memory：保存项目路径和当前阶段

全局编排器核心逻辑

核心驱动机制是 todo 驱动的自动阶段推进——每个阶段完成后自动将下一阶段标记为 in_progress，同时更新项目状态文件。

元技能加载策略

场景 加载的 skill 调用时机
需求模糊 需求澄清 (Stage 1) 项目启动时
规划阶段 蓝图规划 (Stage 2) Stage 1 退出后
搭架子 项目初始化 (Stage 3) Stage 2 退出后
开发 模块开发 (Stage 4) 每模块开始前
审查 代码审查 (Stage 4b) 每模块完成后
红队 红队测试 (Stage 5) 全部模块合并后

双目录管理

1
2
3
workspace/plans/{project-name}/     ← 规划文档（三文档）
{PROJECT_DIR}/                       ← 项目代码目录
{PROJECT_DIR}/.hermes-status.md      ← 跨会话状态文件

关键规则：

  • AI 编排者读取 tasks.md 从 workspace/plans/，但 subagent 的 workdir 指向项目代码目录
  • subagent 不直接读文件，而是接收编排者传过来的完整上下文
  • 每个阶段完成后更新 .hermes-status.md

Stage 1：需求澄清 — 实现细节

流程

1
2
3
4
5
6
7
8
用户提想法
  │
  ├─ 想法清晰？→ 直接输出用户故事地图
  └─ 想法模糊？→ 按 4 层访谈协议逐步澄清
       Layer 1: "目标用户是谁？核心解决的问题是什么？"
       Layer 2: "预期对标的竞品/参考是什么？"
       Layer 3: "技术栈有倾向或约束吗？"
       Layer 4: "哪些功能你明确不需要（反需求）？"

精确工具调用序列

  1. 加载 kiro-spec-engine 的 4 层访谈协议
  2. 逐层提问，每次问一个维度（用户回答后进入下一层）
  3. 生成需求澄清报告并写入 workspace/plans/{project}/stage1-demand-clarification.md
  4. 确认退出条件后，todo 标记完成 → 自动进入 Stage 2

产出格式示例

1
2
3
4
5
6
7
8
9
10
11
12
13
## 用户故事地图

| ID | 优先级 | 用户故事 | 正常路径 | 替代路径 | 异常路径 |
|----|--------|---------|---------|---------|---------|
| US-01 | P0 | 作为用户，我想粘贴链接并下载无水印视频 | 粘贴→点击→下载 | — | 无效链接→报错 |

## 非功能需求
- 性能: 单次下载 < 5s
- 安全: 不存储用户上传的链接

## 反需求清单（已确认）
1. ❌ 不做用户登录/注册系统
2. ❌ 不做批量下载（v1 只做单条）

Stage 2：蓝图规划 — 实现细节

核心产出三文档

  1. requirements.md：按 P0/P1/P2 分级，每个需求有 AC（可验收标准）
  2. design.md：系统架构图 (Mermaid)、数据模型、API 契约 (TypeScript types)、错误处理策略、Architecture Constraints、Decision Log
  3. tasks.md：模块化拆分，每任务 < 200 行或 < 3 个文件，含测试用例

对抗性审阅

这是最关键的质量门禁。编排在输出设计后，对自身发起对抗性质疑：

1
2
3
4
5
6
7
8
9
const adversarialQuestions = [
  "核心 API 如果挂了，有降级方案吗？",
  "第三方依赖变更（如抖音改链接域名）怎么应对？",
  "边界数据（空、超大、特殊字符）有处理吗？",
  "并发场景下会不会竞态？",
  "这个设计如果用户量翻 10 倍会崩在哪儿？",
  "有没有隐藏的跨模块耦合？",
];
// 至少找到 3 个风险才视为审阅充分

Stage 3：项目初始化 — 实现细节

脚手架结构

1
2
3
4
5
6
7
8
{PROJECT_DIR}/
├── .ai/              # AI 辅助工具配置
├── docs/             # 文档
├── module-summaries/ # 模块归档
├── src/              # 源文件
├── tests/            # 测试文件
├── CLAUDE.md         # Architecture Constraints
└── .hermes-status.md # 项目宪章 + 进度追踪

输出产物

  • 项目目录结构
  • CLAUDE.md：从 design.md 回填的 Architecture Constraints、技术栈版本、测试命令、禁止 API
  • .hermes-status.md：项目宪章 + 当前进度
  • Git init + 首次 commit

Stage 4：模块开发 — 实现细节

整体编排循环

1
2
3
4
5
6
7
8
9
10
11
12
while tasks.md 中还有未完成的模块:
    1. 取出下一个模块（按优先级）
    2. 创建分支: git checkout -b ai/dev-{TASK_ID}
    3. 读取 design.md + tasks.md，构造成 subagent context
    4. delegate_task 传给 subagent 实现
    5. 验证输出（stat 文件存在、read_file 抽查）
    6. 运行单元测试
    7. 失败 → 调度修复 subagent → 重新测试
    8. 通过 → 生成 module-summaries/{TASK_ID}.md
    9. Code Review → commit → 下一模块

全部模块完成 → git checkout main → git merge → Stage 5

编排者与 Subagent 的分工

角色 编排者 Subagent（执行者）
分支管理 创建/切换/合并 不涉及
读取三文档 负责读取，转成 context 传过去 不读文件，只接收 context
编码实现 不写代码 delegate_task 执行
测试验证 跑测试命令，判断通过/失败 只实现，不验证
模块归档 写 module-summaries/ 不参与
Code Review 调度 review agent 不参与

Subagent Context 模板

1
2
3
4
5
6
7
8
9
10
11
12
delegate_task(
    goal="实现 {TASK_ID}: {模块名}",
    context=f'''
任务描述：{tasks.md 中的任务描述}
接口契约：{design.md 中的 API contract}
架构约束：1. {AC #1}  2. {AC #2}
TDD 要求: 先写测试再写实现，覆盖正常+异常路径
文件说明: src/ 源文件，tests/ 测试文件
''',
    toolsets=['terminal', 'file'],
    workdir={PROJECT_DIR}
)

输出验证

验证器检查：文件是否存在、内容是否过短、测试是否通过。任意一项不通过则触发修复循环。

Code Review 调用序列

1
2
3
4
5
1. git diff main...HEAD > diff 文件
2. delegate_task 给 review agent，7 维度审查
3. 评估结果：
   - 通过 → commit，进入下一模块
   - 阻塞 → 调度修复（最多 2 次）→ 重新审查

Stage 5：红队测试 — 实现细节

五阶段测试

阶段 测试内容 方法
Phase 1 异常输入攻击 空值、超长字符串、XSS payload
Phase 2 边界条件 空数组、单条数据、极限值
Phase 3 网络场景模拟 断网、超时、限速
Phase 4 行为测试 快速连续点击、防抖节流
Phase 5 汇总报告 写入 docs/redteam/redteam-report.md

高危修复循环

1
2
3
4
5
while has_high_risk and retry_count < 2:
    调度修复 → 回归测试
    retry_count++
if retry_count >= 2 and still_high_risk:
    升级用户决策：接受风险还是重构

Stage 6：交付与复盘 — 实现细节

交付步骤

  1. 汇总 module-summaries/ 全部模块归档 → docs/project-summary.md
  2. 汇总技术债 → docs/known-issues.md
  3. 提炼可复用的 Skill 模式
  4. 保存项目指针到 memory
  5. 标记全部 todo completed

异常和反馈循环

常见异常处理一览

场景 处理策略
用户中途改需求 回 Stage 1 更新用户故事 → 更新 design.md → 更新受影响模块
模块开发卡住 3 次 升级用户：「回滚设计」还是「换方案」
红队高危修 2 次仍不过 升级用户：「接受风险」还是「重构模块」
用户说”跳过阶段” 确认 → 记录到 .hermes-status.md → 强制执行跳过
Subagent 声称完成但文件不存在 重新调度 subagent，强调文件路径确认
测试幻觉（说通过了但没跑） 重新调度修复 + 要求输出终端日志

反馈循环实现

1
2
3
4
5
6
7
8
9
def feedback_loop(stage_func, max_retries=2):
    for i in range(max_retries):
        result = stage_func()
        if result.success:
            return result
        fix_result = delegate_task(goal=f"修复: {result.error}", ...)
        if not fix_result.success and i == max_retries - 1:
            clarify("修复失败，请决策", choices=["回滚", "换方案", "手动介入"])
    return result

上下文治理规则

何时重置上下文

  • 上下文 token > 50% 窗口上限
  • 连续 2 次编排者出现记忆偏差
  • 模块切换时（强制干净上下文）
  • 幻觉式修改（声称改了文件但 stat 发现没变）

重置后恢复流程

  1. 加载 Project Charter（从 .hermes-status.md 读取）
  2. 加载上一个模块归档
  3. 加载 design.md 相关章节
  4. 重新声明 Architecture Constraints

模块切换时强制执行

每开始一个新模块前：如果已连续开发 2+ 模块，先回顾已完成内容，再重新加载 CLAUDE.md 和 design.md 中的 Architecture Constraints。发现 subagent 输出与实际文件不一致时立即重新调度。

编排者的常驻心智模型

1
2
3
4
5
6
7
8
9
我是一个编排者，不是写代码的人。
我的工作 = 排任务 + 传上下文 + 验结果 + 推流程 + 管质量

每个阶段我思考:
  1. 当前阶段的核心 skill 是什么？
  2. 退出条件检查清单我过完了吗？
  3. 需要我亲自做，还是 delegate 给 subagent？
  4. 这个决策需要用户确认，还是我可以直接推进？
  5. 质量门禁有没有被跳过？

路径速查

文件 路径
需求澄清报告 workspace/plans/{project}/stage1-demand-clarification.md
需求规格 workspace/plans/{project}/requirements.md
设计文档 workspace/plans/{project}/design.md
任务拆分 workspace/plans/{project}/tasks.md
项目宪章 workspace/plans/{project}/.hermes-status.md
代码目录 {PROJECT_DIR}
AI 约束 {PROJECT_DIR}/CLAUDE.md
模块归档 {PROJECT_DIR}/module-summaries/{TASK_ID}.md
审查报告 {PROJECT_DIR}/docs/reviews/
红队报告 {PROJECT_DIR}/docs/redteam/redteam-report.md
项目总结 {PROJECT_DIR}/docs/project-summary.md

常见问题

Q: Vibe Coding 和传统 AI 编程有什么区别？
A: 传统 AI 编程主要是一次性对话生成代码，Vibe Coding 是多阶段、可编排的工程化流程。它强调阶段分解、质量门禁、反馈循环和上下文治理，让 AI 独立完成从需求到交付的完整闭环。

Q: 六阶段流程是否适用于所有项目？
A: 不一定。小型工具类项目可以简化为 3-4 阶段（跳过全面规划和红队测试），大型工程建议全流程执行。编排者的核心职责之一是根据项目规模动态剪裁流程。

Q: 如何处理 subagent 输出的不可靠性？
A: 三层防御：第一层是输出验证（stat + read_file 抽查），第二层是自动化测试，第三层是 Code Review。如果 subagent 声称完成但实际文件不存在，立即重新调度并强调文件路径。

Q: 上下文溢出后如何恢复工作？
A: 通过 .hermes-status.md（Project Charter）和 module-summaries/{PREV}.md（上一个模块归档）恢复。每次模块切换时强制加载历史归档，避免编排者遗忘上下文。

Q: 这套流程依赖特定的 AI 平台吗？
A: 核心模式（阶段分解 + delegate_task + todo 驱动推进 + 验证循环）是平台无关的。本文的实现基于 OpenClaw 的 skill/subagent 机制，但可将类似模式迁移到 Anthropic、LangChain 等任何支持 Agent 编排的平台。

相关文章