VibeEngineering/.claude/commands/vibe-execute.md

---
name: vibe-execute
description: 从 plan.md 创建 Task 系统并执行
---

# /vibe-execute

从 plan.md 创建 Claude Code Task 系统，协调子代理执行所有任务。

## Phase 1: 初始化 - 创建 Task 系统

### 1.1 读取 plan.md

读取最新的实现计划：`docs/plans/*-plan.md`

### 1.2 按转换规则创建业务 Task

遍历 plan.md 中的所有 Task（按 Task 编号识别，如 Task 0.1, Task 1.1 等），为每个 Task 调用 TaskCreate：

```
TaskCreate(
    subject="{Task 标题}",
    description="{Task 完整文本，原样保留}",
    activeForm="{简短的进行时描述}",
    metadata={"plan_task_id": "{Task 编号}"}
)
```

**示例**：

plan.md 中：
```markdown
## Task 1.1: 创建配置模块基础结构

**目标**: 使用Pydantic创建统一配置管理模块

**文件**:
- 创建: src/config/__init__.py
- 创建: src/config/settings.py

**验收标准**:
- 配置模块可导入
- get_config()返回AppConfig实例
```

转换为：
```
TaskCreate(
    subject="创建配置模块基础结构",
    description="## Task 1.1: 创建配置模块基础结构\n\n**目标**: 使用Pydantic创建统一配置管理模块\n\n**文件**:\n- 创建: src/config/__init__.py\n- 创建: src/config/settings.py\n\n**验收标准**:\n- 配置模块可导入\n- get_config()返回AppConfig实例",
    activeForm="创建配置模块",
    metadata={"plan_task_id": "1.1"}
)
```

### 1.3 自动追加校验 Task

所有业务 Task 创建完成后，自动追加校验 Task：

```
TaskCreate(
    subject="[校验] 全局需求验证",
    description="""## 全局校验 Task

**目标**: 验证所有业务 Task 忠实实现了 design.md 的全部需求，无降级、无遗漏。

**固定流程**:

### Step 0: 读取 session.yml 获取文件路径
- 读取 .vibe/session.yml
- 获取 design_doc 和 plan_doc 路径

### Step 1: 读取所有 Task JSON + metadata
- 调用 TaskList 获取所有任务
- 逐个 TaskGet 读取完整信息（含 metadata）
- 重点检查每个已完成 Task 的 metadata：
  - errors_encountered：是否含"暂时跳过"、"简化实现"、"workaround"
  - test_results：测试数量是否符合 description 中的预期
  - files_modified：是否缺少 description 中指定的文件
  - commit_message：是否含"partial"、"skip"、"TODO"

### Step 2: 对比 design.md 逐条校验
- 读取 session.yml 中 design_doc 指定的设计文档
- 逐条对照：需求 → 对应 Task description → 对应 metadata 实际执行
- 生成校验报告：
  - ✅ 需求 X：已实现（Task N, commit abc123）
  - ❌ 需求 Y：未实现 / 实现不完整
  - ⚠️ 需求 Z：降级实现（metadata 显示 workaround）

### Step 3: 运行完整测试套件
- 执行项目的完整测试命令（不能只看 metadata 里的历史结果）
- 确认所有测试通过

### Step 4: 检查未解决问题
- 扫描所有 Task metadata 的 errors_encountered
- 确认没有"暂时跳过"、"后续处理"的遗留问题

### Step 5: 处理校验结果

**全部通过：**
1. 读取所有 Task JSON（Glob + Read），生成 task-snapshot.md 保存到 .vibe/task-snapshot.md
2. 标记本 Task completed

**发现问题：**
1. 输出详细校验报告
2. 为每个问题创建修复 Task（TaskCreate，description 包含具体问题）
3. 等待修复 Task 完成后重新执行 Step 1-4
""",
    activeForm="全局需求验证",
    metadata={"verification_task": True}
)
```

### 1.4 创建 session.yml

```yaml
# .vibe/session.yml
task_list_id: "{TaskListId}"
design_doc: "docs/plans/{timestamp}-design.md"
plan_doc: "docs/plans/{timestamp}-plan.md"
created_at: "{当前时间}"
```

## Phase 2: 执行循环

获取下一个 pending Task，判断类型：

### 2.1 业务 Task 执行

调用 `subagent-driven-development` skill，派发子代理：

**派发 Implementer 子代理**：
```
Task tool (general-purpose):
  description: "实现 Task N: {Task标题}"
  prompt: |
    你正在实现一个具体的开发任务。

    ## 任务信息

    {Task JSON 的完整 description 内容}

    ## Task metadata 更新规范（必须遵守）

    在执行过程中，你必须持续通过 TaskUpdate 更新 metadata，记录执行细节。
    这些 metadata 将被后续的校验 Task 读取，用于检查是否有降级实现。

    **1. 开始任务时：**
    TaskUpdate taskId={id} metadata={"started_at": "{当前时间}"}

    **2. 每次修改文件后：**
    TaskUpdate taskId={id} metadata={"files_modified": ["file1.py", "file2.py"]}

    **3. 遇到错误时（必须记录，包含解决方案）：**
    TaskUpdate taskId={id} metadata={"errors_encountered": ["错误描述 - 解决方案"]}
    ⚠️ 如果你无法解决某个问题而选择跳过或简化，必须如实记录：
    "无法实现XX功能 - 暂时跳过" 或 "XX过于复杂 - 简化为YY"

    **4. 运行测试后：**
    TaskUpdate taskId={id} metadata={"test_results": "5/5 passed"}

    **5. 提交代码后：**
    TaskUpdate taskId={id} metadata={"git_commit": "{commit hash}", "commit_message": "{提交信息}"}

    **6. 任务完成时（由主窗口标记，不是你）：**
    主窗口会调用 TaskUpdate status=completed，你只需要更新 metadata。

    ## 执行要求

    - 遵循 TDD：先写测试，再实现
    - 每个有意义的变更都要提交
    - 自审：完成后检查自己的实现是否完整
    - 如实记录：不要隐瞒错误或跳过的内容
```

**派发 Spec Reviewer 子代理**：
```
Task tool (general-purpose):
  description: "审查 Task N 的规格符合性"
  prompt: |
    你正在审查一个实现是否符合其规格。

    ## 被请求的内容

    {Task JSON 的完整 description 内容}

    ## 实现者声称构建的内容

    {Implementer 子代理的返回报告}

    ## 关键：不要信任报告

    实现者的报告可能不完整、不准确或过于乐观。你必须独立验证。

    **要：**
    - 阅读实际代码
    - 逐行比较实现和需求
    - 检查声称实现但实际没有的部分
    - 寻找没提到的额外功能

    **不要：**
    - 相信实现者的说法
    - 信任完整性声明
    - 接受对需求的重新解释

    ## 检查项

    **遗漏的需求：**
    - 所有被请求的内容都实现了吗？
    - 有跳过或遗漏的需求吗？

    **多余的工作：**
    - 构建了没有被请求的东西吗？
    - 过度设计或添加了不必要的功能吗？

    **误解：**
    - 对需求的解释与预期不同吗？
    - 解决了错误的问题吗？

    ## 输出格式

    - ✅ 符合规格（如果代码检查后一切匹配）
    - ❌ 发现问题：[具体列出遗漏或多余的内容，带 file:line 引用]
```

**派发 Code Quality Reviewer 子代理**（规格符合性审查通过后）：
```
Task tool (general-purpose):
  description: "审查 Task N 的代码质量"
  prompt: |
    你正在审查代码更改的生产就绪性。

    ## 实现内容

    {Implementer 报告的描述}

    ## 需求/计划

    {Task JSON 的完整 description 内容}

    ## 要审查的 Git 范围

    **Base:** {任务前的提交}
    **Head:** {当前提交}

    ```bash
    git diff --stat {BASE_SHA}..{HEAD_SHA}
    git diff {BASE_SHA}..{HEAD_SHA}
    ```

    ## 审查清单

    **代码质量：** 关注点分离、错误处理、类型安全、DRY、边界情况
    **架构：** 设计决策、可扩展性、性能、安全
    **测试：** 测试真实逻辑（非mock）、边界覆盖、集成测试、全部通过
    **生产就绪：** 向后兼容、文档、无明显bug

    ## 输出格式

    ### 优点
    [什么做得好？要具体。]

    ### 问题

    #### 关键（必须修复）
    [Bug、安全问题、数据丢失风险]

    #### 重要（应该修复）
    [架构问题、测试缺口]

    #### 次要（可以改进）
    [代码风格、优化机会]

    **对于每个问题：** File:line 引用 + 什么问题 + 为什么重要 + 如何修复

    ### 评估
    **可以合并？** [是/否/修复后可以]
    **理由：** [1-2 句话]
```

**标记完成**：
```
TaskUpdate taskId={id} status=completed
```

### 2.2 校验 Task 执行

按照校验 Task 的 description 中的固定流程执行（Step 0-5）。

## 降级检测信号表

| metadata 字段 | 降级信号 | 说明 |
|---------------|---------|------|
| `errors_encountered` | 含"暂时跳过"、"简化"、"workaround" | 遇到困难绕过了 |
| `test_results` | 测试数量 < description 中的预期 | 测试覆盖不足 |
| `files_modified` | 缺少 description 中指定的文件 | 有文件未修改 |
| `commit_message` | 含"partial"、"skip"、"TODO" | 部分实现 |