VibeEngineering/DESIGN.md

# VibeEngineering V2 设计文档

> **目标**：在 Claude Code CLI 上实现自动化开发系统，融合 Superpowers 专家方法论 + 跨 Compact 恢复机制，实现"人工把关设计，自动执行任务"的工作流程。
>
> **核心原则**：
> - 设计阶段需要人工确认（命令边界形成自然审查点），执行阶段全自动化
> - 执行阶段使用子代理驱动模式（Implementer → Spec Reviewer → Quality Reviewer）
> - 使用 Claude Code 原生 Task 系统替代自定义状态管理，metadata 记录执行细节
> - 跨 Compact 恢复：PreCompact Hook 保存上下文 → SessionStart Hook 引导恢复
> - 校验 Task 作为最后一个 Task，对比 design.md + metadata 检查降级

---

## 一、核心设计理念

### 1.1 命令驱动的两阶段分离

```
┌─────────────────────────────────────────────────────────────────────────┐
│                         Vibe Engineering V2                             │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│   ┌─────────────────────────────────────────────────────────────────┐   │
│   │  设计阶段                                                        │   │
│   │  ──────────────────────────                                      │   │
│   │                                                                  │   │
│   │  /vibe-brainstorming "需求"                                      │   │
│   │    └── 使用 brainstorming skill → 生成 design.md                │   │
│   │                                                                  │   │
│   │         ↓ 用户审核 design.md（命令边界 = 审查点）                 │   │
│   │                                                                  │   │
│   │  /vibe-plan                                                      │   │
│   │    └── 使用 writing-plans skill → 生成 plan.md                  │   │
│   │                                                                  │   │
│   │  特点：                                                          │   │
│   │  ├── 每个命令独立结束，形成自然的审查点                           │   │
│   │  └── 用户手动执行下一个命令                                       │   │
│   └─────────────────────────────────────────────────────────────────┘   │
│                                                                         │
│                         ↓ 用户审核 plan.md ↓                            │
│                         ↓ 执行 /vibe-execute ↓                          │
│                                                                         │
│   ┌─────────────────────────────────────────────────────────────────┐   │
│   │  执行阶段                                                        │   │
│   │  ──────────────────────────                                      │   │
│   │                                                                  │   │
│   │  /vibe-execute                                                   │   │
│   │    ├── 按转换规则从 plan.md 创建 Task 系统                       │   │
│   │    ├── 自动追加校验 Task                                         │   │
│   │    ├── 创建 session.yml                                         │   │
│   │    └── 协调者循环执行所有 Task                                   │   │
│   │                                                                  │   │
│   │  Task 执行：                                                     │   │
│   │    ├── 派发 Implementer 子代理（实现 + TDD + 提交 + 更新 metadata）│   │
│   │    ├── 派发 Spec Reviewer 子代理（规格符合性审查）               │   │
│   │    └── 派发 Quality Reviewer 子代理（代码质量审查）              │   │
│   │                                                                  │   │
│   │  跨 Compact 恢复：                                               │   │
│   │    ├── PreCompact Hook：保存当前任务上下文                       │   │
│   │    └── SessionStart Hook：引导恢复执行                           │   │
│   │                                                                  │   │
│   │  校验阶段（最后一个 Task）：                                      │   │
│   │    ├── 对比 design.md + Task metadata 检查降级                   │   │
│   │    ├── 运行完整测试套件                                          │   │
│   │    ├── 发现问题 → 创建修复 Task → 继续执行                       │   │
│   │    └── 全部通过 → 保存快照 → 标记完成                            │   │
│   └─────────────────────────────────────────────────────────────────┘   │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘
```

### 1.2 V1 到 V2 的关键变化

| 方面 | V1 | V2 |
|------|----|----|
| **状态管理** | 自定义状态文件 `vibe-state.local.md` | Claude Code 原生 Task 系统 |
| **执行细节** | 无持久化记录 | Task metadata 持久化记录 |
| **执行控制** | Stop Hook 拦截 + 灌 Prompt | Task 系统自动持久化 |
| **Compact 恢复** | 依赖状态文件 phase 字段 | PreCompact + SessionStart Hook 组合 |
| **完成验证** | verification-before-completion skill | 校验 Task（自动追加，作为最后一个 Task） |
| **降级检测** | 无 | 校验 Task 对比 metadata 检测降级 |

### 1.3 子代理驱动模式

```
执行阶段的每个业务 Task 执行流程：

Task N（业务任务）
  │
  ├── Task tool: Implementer (general-purpose)
  │         │
  │         ├── 阅读任务需求
  │         ├── 遵循 TDD（RED-GREEN-REFACTOR）
  │         ├── 实现功能
  │         ├── Git commit
  │         └── 更新 Task metadata（files_modified, errors_encountered, test_results, git_commit）
  │         │
  │         ▼
  ├── Task tool: Spec Reviewer (general-purpose)
  │         │
  │         ├── 独立阅读代码（不信任 Implementer 报告）
  │         ├── 逐条验证需求是否满足
  │         ├── 检查遗漏或多余功能
  │         │
  │         ▼ 问题? → Implementer 修复 → 重新审查
  │         │
  ├── Task tool: Quality Reviewer (general-purpose)
  │         │
  │         ├── 审查代码质量、架构、测试
  │         ├── 分类问题：关键/重要/次要
  │         │
  │         ▼ 问题? → Implementer 修复 → 重新审查
  │         │
  └── 主窗口：TaskUpdate status=completed

所有业务 Task completed
  │
  ▼
校验 Task 启动（最后一个 pending Task）
  │
  ├── 读取所有 Task JSON + metadata
  ├── 对比 design.md 逐条校验
  ├── 运行完整测试套件
  ├── 检查 metadata 中未解决问题
  │
  ▼ 发现问题? → 创建修复 Task → 执行 → 重新校验
  │
  ▼ 全部通过
  │
  ├── 保存 Task 快照
  └── 标记校验 Task completed → Task JSON 被系统删除
```

---

## 二、整体流程图

```mermaid
graph TB
    subgraph init ["初始化阶段 - vibe-execute"]
        A1["读取 plan.md"] --> A2["按转换规则创建业务 Task"]
        A2 --> A5["自动追加校验 Task"]
        A5 --> A4["创建 session.yml"]
    end

    subgraph exec ["执行阶段 - 协调者循环"]
        B0["获取下一个 pending Task"] --> B00{"是校验 Task?"}

        B00 -->|否| B1["派发 Implementer 子代理"]
        subgraph task ["业务 Task 执行"]
            B1 --> B2["Implementer: 实现/测试/提交"]
            B2 --> B3["Implementer: 更新 Task metadata"]
            B3 --> B4["派发 Spec Reviewer"]
            B4 --> B5{"规格符合?"}
            B5 -->|否| B6["Implementer: 修复规格差距"]
            B6 --> B4
            B5 -->|是| B7["派发 Code Quality Reviewer"]
            B7 --> B8{"质量通过?"}
            B8 -->|否| B9["Implementer: 修复质量问题"]
            B9 --> B7
            B8 -->|是| B10["TaskUpdate status=completed"]
        end
        B10 --> B0

        B00 -->|是| B20["校验 Task 开始"]
        subgraph verify ["校验 Task 执行"]
            B20 --> B21["读取所有 Task JSON + metadata"]
            B21 --> B22["对比 design.md 逐条校验"]
            B22 --> B23["运行完整测试套件"]
            B23 --> B24["检查 metadata 中未解决问题"]
            B24 --> B25{"全部通过?"}
            B25 -->|否| B26["创建修复 Task"]
            B26 --> B0
            B25 -->|是| B27["保存 Task 快照"]
            B27 --> B28["标记校验 Task completed"]
            B28 --> B29["Task JSON 被删除"]
        end
    end

    subgraph precompact ["PreCompact 阶段"]
        C1["PreCompact Hook 触发"] --> C2["读取 transcript.jsonl"]
        C2 --> C3["找到最后 TaskUpdate completed"]
        C3 --> C4["提取之后的内容"]
        C4 --> C5["写入 last_task_context.jsonl"]
        C5 --> C6["Compact 发生"]
    end

    subgraph recovery ["恢复阶段 - SessionStart"]
        D1["SessionStart Hook 触发"] --> D2["读取 design.md"]
        D2 --> D3["读取所有 Task JSON"]
        D3 --> D4["读取 last_task_context.jsonl"]
    end

    A4 --> B0
    B0 -.可能触发.-> C1
    C6 --> D1
    D4 --> B0
```

---

## 三、文件体系

```
项目根目录/
├── docs/plans/
│   ├── {timestamp}-design.md        # 需求和架构（设计阶段产出）
│   └── {timestamp}-plan.md          # 实现计划（设计阶段产出）
│
├── .vibe/
│   ├── session.yml                  # 会话元信息（task_list_id, design_doc）
│   ├── last_task_context.jsonl      # 当前任务执行过程（PreCompact 生成）
│   └── task-snapshot.md             # Task 快照（校验通过后保存）
│
├── .claude/
│   ├── commands/
│   │   ├── vibe-brainstorming.md    # 设计阶段第一步：需求探索
│   │   ├── vibe-plan.md             # 设计阶段第二步：创建计划
│   │   └── vibe-execute.md          # 执行阶段：创建 Task + 协调执行
│   ├── hooks/
│   │   ├── session-start.sh         # 恢复提示词
│   │   ├── pre-compact.sh           # 调用提取脚本
│   │   └── extract-last-context.js  # transcript → last_task_context.jsonl
│   ├── skills/
│   │   ├── brainstorming/           # 需求探索方法论
│   │   ├── writing-plans/           # 计划编写方法论
│   │   ├── test-driven-development/ # TDD 方法论
│   │   └── subagent-driven-development/ # 子代理驱动执行方法论
│   ├── settings.local.json          # Hook 配置
│   └── CLAUDE.md                    # 项目级提示词（含 metadata 读取说明）
│
└── ~/.claude/tasks/{TaskListId}/    # Claude Code 原生 Task 系统
    ├── 1.json                       # Task + metadata（动态）
    ├── 2.json
    └── ...                          # ⚠️ 所有任务完成后被系统删除
```

### 文件职责

| 文件 | 内容 | 生命周期 |
|------|------|---------|
| **design.md** | 需求分析、架构设计、技术选型 | 永久 |
| **plan.md** | 任务分解、TDD 步骤 | 永久 |
| **Task JSON** | 任务信息 + metadata（执行细节） | 执行期间，完成后删除 |
| **last_task_context.jsonl** | 当前任务执行过程 | 每次 PreCompact 覆盖 |
| **task-snapshot.md** | Task JSON 快照 | 永久 |
| **session.yml** | task_list_id, design_doc | 执行期间 |

---

## 四、命令设计

### 4.1 /vibe-brainstorming - 需求探索

**文件**：`.claude/commands/vibe-brainstorming.md`

````markdown
---
name: vibe-brainstorming
description: 需求探索和设计文档生成
arguments:
  - name: requirement
    description: 用户需求描述
    required: true
---

# /vibe-brainstorming

使用 brainstorming skill 探索需求，生成设计文档。

## 执行步骤

1. 调用 brainstorming skill，传入用户需求
2. 探索需求，澄清问题
3. 分析 2-3 种技术方案
4. 生成设计文档：`docs/plans/YYYY-MM-DD-<feature>-design.md`

## 输出

完成后提示用户：
```
设计文档已生成：docs/plans/YYYY-MM-DD-<feature>-design.md

请审核设计文档，确认后执行：/vibe-plan
```
````

### 4.2 /vibe-plan - 创建实现计划

**文件**：`.claude/commands/vibe-plan.md`

````markdown
---
name: vibe-plan
description: 从设计文档创建实现计划
---

# /vibe-plan

使用 writing-plans skill 分解任务，生成实现计划。

## 执行步骤

1. 读取最新的设计文档 `docs/plans/*-design.md`
2. 调用 writing-plans skill
3. 分解任务，定义 TDD 步骤
4. 生成实现计划：`docs/plans/YYYY-MM-DD-<feature>-plan.md`

## 输出

完成后提示用户：
```
实现计划已生成：docs/plans/YYYY-MM-DD-<feature>-plan.md

请审核实现计划，确认后执行：/vibe-execute
```
````

### 4.3 /vibe-execute - 执行阶段

**文件**：`.claude/commands/vibe-execute.md`

这是最关键的命令，包含完整的转换规则和执行逻辑。

````markdown
---
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 执行

调用 test-driven-development skill，然后派发子代理：

**派发 Implementer 子代理**（使用第五章提示词模板）：
- 实现功能
- 遵循 TDD
- 提交代码
- **更新 Task metadata**（关键！）

**派发 Spec Reviewer 子代理**（使用第六章提示词模板）：
- 规格符合性审查
- 问题 → Implementer 修复 → 重新审查

**派发 Code Quality Reviewer 子代理**（使用第七章提示词模板）：
- 代码质量审查
- 问题 → Implementer 修复 → 重新审查

**标记完成**：
```
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" | 部分实现 |
````

---

## 五、Implementer 子代理提示词

派发 Implementer 子代理时使用此模板：

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

### metadata 完整示例

```json
{
  "id": "5",
  "subject": "迁移ES配置",
  "status": "completed",
  "metadata": {
    "plan_task_id": "2.3",
    "started_at": "2026-01-26 14:00",
    "completed_at": "2026-01-26 14:30",
    "files_modified": [
      "src/elasticsearch/config.py",
      "src/elasticsearch/client.py"
    ],
    "git_commit": "abc123f",
    "commit_message": "refactor(es): migrate to unified config",
    "errors_encountered": [
      "Pydantic版本冲突 - 已通过升级到2.0解决"
    ],
    "test_results": "5/5 passed"
  }
}
```

---

## 六、Spec Reviewer 子代理提示词

规格符合性审查通过后才派发 Code Quality Reviewer。

````markdown
Task tool (general-purpose):
  description: "审查 Task N 的规格符合性"
  prompt: |
    你正在审查一个实现是否符合其规格。

    ## 被请求的内容

    {Task JSON 的完整 description 内容}

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

    {Implementer 子代理的返回报告}

    ## 关键：不要信任报告

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

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

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

    ## 检查项

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

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

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

    ## 输出格式

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

---

## 七、Code Quality Reviewer 子代理提示词

只在规格符合性审查通过后派发。

````markdown
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 句话]
````

---

## 八、跨 Compact 恢复机制

### 8.1 核心机制

```
恢复上下文 = design.md（架构）
           + Task JSON + metadata（任务与执行细节）
           + last_task_context.jsonl（当前任务上下文）
```

### 8.2 PreCompact Hook

当上下文即将满时，PreCompact Hook 自动触发，从 transcript.jsonl 提取当前任务上下文。

**Shell 入口**：`.claude/hooks/pre-compact.sh`

```bash
#!/usr/bin/env bash

INPUT=$(cat)
TRANSCRIPT_PATH=$(echo "$INPUT" | jq -r '.transcript_path')

# 等待 transcript.jsonl 完全写入
sleep 1

node .claude/hooks/extract-last-context.js "$TRANSCRIPT_PATH" > .vibe/last_task_context.jsonl
```

**提取脚本**：`.claude/hooks/extract-last-context.js`

```javascript
const fs = require('fs');

function extractSinceLastTaskComplete(transcriptPath) {
  const content = fs.readFileSync(transcriptPath, 'utf-8');
  const lines = content.split('\n').filter(Boolean);

  // 倒序找最后一次 TaskUpdate status=completed
  let cutoffIndex = 0;
  for (let i = lines.length - 1; i >= 0; i--) {
    try {
      const entry = JSON.parse(lines[i]);
      if (entry.tool_name === 'TaskUpdate' &&
          entry.tool_input?.status === 'completed') {
        cutoffIndex = i + 1;
        break;
      }
    } catch (e) {
      continue;
    }
  }

  const relevantLines = lines.slice(cutoffIndex);
  const simplified = simplifyEntries(relevantLines);
  return simplified.map(e => JSON.stringify(e)).join('\n');
}

function simplifyEntries(lines) {
  return lines.map(line => {
    try {
      const entry = JSON.parse(line);

      // Claude 输出：全部保留
      if (entry.role === 'assistant') {
        return { type: 'assistant', content: entry.content };
      }

      // 用户输入：全部保留
      if (entry.role === 'user') {
        return { type: 'user', content: entry.content };
      }

      // Task tool 返回（子代理结果）：全部保留
      if (entry.type === 'tool_result' && entry.agentId) {
        return {
          type: 'task_result',
          agentId: entry.agentId,
          content: entry.content
        };
      }

      // 工具调用
      if (entry.tool_name) {
        const input = entry.tool_input || {};

        // Task tool（派发子代理）：prompt 全部保留
        if (entry.tool_name === 'Task') {
          return {
            type: 'tool',
            name: 'Task',
            subagent_type: input.subagent_type,
            description: input.description,
            prompt: input.prompt
          };
        }

        // 其他工具：只保留关键参数
        const simplified = { type: 'tool', name: entry.tool_name };
        if (input.file_path) simplified.file = input.file_path;
        if (input.command) simplified.command = input.command;
        if (input.pattern) simplified.pattern = input.pattern;
        if (input.path) simplified.path = input.path;
        if (input.taskId) simplified.taskId = input.taskId;
        if (input.status) simplified.status = input.status;

        if (entry.tool_result?.exit_code !== undefined) {
          simplified.exit_code = entry.tool_result.exit_code;
        }
        return simplified;
      }

      return null;
    } catch (e) {
      return null;
    }
  }).filter(Boolean);
}

const transcriptPath = process.argv[2];
if (transcriptPath) {
  console.log(extractSinceLastTaskComplete(transcriptPath));
}
```

**提取精简规则**：

| 类型 | 保留内容 |
|------|---------|
| Claude 输出 | ✅ 全部 content |
| 用户输入 | ✅ 全部 content |
| Task tool（派发） | ✅ prompt, subagent_type, description |
| Task tool（返回） | ✅ content, agentId |
| Read / Edit / Write | file_path |
| Bash | command, exit_code |
| Glob / Grep | pattern, path |
| TaskUpdate | taskId, status |

### 8.3 SessionStart Hook

Compact 后会话恢复时，SessionStart Hook 自动触发，引导 Claude 恢复执行上下文。

**文件**：`.claude/hooks/session-start.sh`

````bash
#!/usr/bin/env bash

# 只有存在 last_task_context.jsonl 才触发恢复提示
# 说明之前发生过 PreCompact，需要恢复上下文
if [[ ! -f ".vibe/last_task_context.jsonl" ]]; then
    exit 0
fi

if [[ ! -f ".vibe/session.yml" ]]; then
    exit 0
fi

# 使用 grep + sed 替代 yq，兼容性更好
TASK_LIST_ID=$(grep 'task_list_id:' .vibe/session.yml | sed 's/task_list_id: *//' | tr -d '"' | tr -d "'")
TASK_DIR="$HOME/.claude/tasks/$TASK_LIST_ID"

cat << 'PROMPT'
## 【系统提示：检测到跨 Compact 恢复 - VibeEngineering V2 执行阶段】

你正在从 Compact 后恢复执行上下文。请严格按以下顺序读取信息：

### Step 1: 读取执行流程定义
```
Read .claude/commands/vibe-execute.md
```
了解 Phase 2 执行循环的完整流程。

### Step 2: 读取 subagent-driven-development skill
```
Read .claude/skills/subagent-driven-development/SKILL.md
```
了解子代理派发模板（Implementer、Spec Reviewer、Code Quality Reviewer）。

### Step 3: 读取设计文档
```
Read .vibe/session.yml
```
获取 design_doc 路径，然后读取设计文档了解需求。

### Step 4: 读取所有 Task JSON
PROMPT

echo '```'
echo "Glob pattern='*.json' path='$TASK_DIR'"
echo "然后 Read 每个返回的 JSON 文件"
echo '```'

cat << 'PROMPT'
从 Task JSON 了解：
- 所有任务列表（subject）和详细信息（description）
- 任务状态（status: pending / in_progress / completed）
- **已完成任务的 metadata**：files_modified, errors_encountered, git_commit, test_results

### Step 5: 读取上一窗口执行上下文
```
Read .vibe/last_task_context.jsonl
```
从 last_task_context.jsonl 了解：
- 当前任务执行到哪一步
- Claude 的思考过程和决策
- 用户的纠正指令（如有）
- 子代理派发的任务和返回结果

### 恢复后行为

1. 找到第一个 status 为 pending 或 in_progress 的 Task
2. 如果有 in_progress 的 Task，结合 last_task_context.jsonl 从中断点继续
3. 如果上一个 Task 已 completed，从下一个 pending Task 开始
4. **按照 vibe-execute.md Phase 2 和 subagent-driven-development skill 执行**：
   - 业务 Task：派发 Implementer → Spec Reviewer → Code Quality Reviewer → 标记完成
   - 校验 Task：执行 Step 0-5 固定流程
5. 所有 Task 完成后，校验 Task 保存快照并标记完成
PROMPT
````

---

## 九、项目级 CLAUDE.md

在项目根目录的 `.claude/CLAUDE.md` 中添加以下内容，让 Claude 了解 metadata 的用途：

````markdown
## VibeEngineering V2 项目说明

### Task 执行规范

大部分 Task 应当遵照 `subagent-driven-development` skill 的流程执行（协调者循环）：
1. 派发 Implementer 子代理实现功能
2. 派发 Spec Reviewer 子代理审查规格符合性
3. 派发 Code Quality Reviewer 子代理审查代码质量
4. 主窗口标记 Task completed

**过于简单的 Task**（如单文件小改动）主代理可以自行完成，无需派发子代理，但**同样需要更新 metadata**。

### Task metadata 规范

无论主代理自己实现还是派发子代理，都必须更新 Task metadata：

- `started_at`: 任务开始时间
- `completed_at`: 任务完成时间
- `files_modified`: 修改的文件列表
- `git_commit`: 提交的 commit hash
- `commit_message`: 提交信息
- `errors_encountered`: 遇到的错误及解决方案（必须如实记录）
- `test_results`: 测试结果

**用途**：
1. 跨 Compact 恢复时，读取 metadata 了解已完成任务的执行细节
2. 校验 Task 读取所有 metadata，检测是否有降级实现
3. 生成 Task 快照时，保存完整的执行历史

**按需读取**：恢复后可按需读取各 Task 的 metadata，无需全部加载到上下文。
````

---

## 十、Hook 配置

**文件**：`.claude/settings.local.json`

```json
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/session-start.sh"
          }
        ]
      }
    ],
    "PreCompact": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/pre-compact.sh"
          }
        ]
      }
    ]
  }
}
```

---

## 十一、session.yml 格式

```yaml
# .vibe/session.yml
task_list_id: "386113df-47f7-4e1d-9db2-d572e3081bf9"
design_doc: "docs/plans/20260126-design.md"
plan_doc: "docs/plans/20260126-plan.md"
created_at: "2026-01-26 10:00"
```

---

## 十二、Task 快照格式

**文件**：`.vibe/task-snapshot.md`

```markdown
# Task 快照 - 2026-01-26 18:00

**Task List ID**: 386113df-47f7-4e1d-9db2-d572e3081bf9
**总任务数**: 22
**完成任务数**: 22

---

### Task 1: 代码备份与分支创建 [completed]

**描述**: 创建重构分支，确保代码安全

**元数据**:
- 完成时间：2026-01-26 10:00
- Git commit：abc123f
- 修改文件：无
- 测试结果：无

---

### Task 2: 创建配置模块基础结构 [completed]

**描述**: 使用Pydantic创建统一配置管理模块

**元数据**:
- 完成时间：2026-01-26 11:00
- Git commit：def456g
- 修改文件：src/config/settings.py, src/config/__init__.py
- 测试结果：5/5 passed
- 错误：Pydantic版本冲突（已通过升级解决）

---

...（所有 Task）
```

---

## 十三、完整执行示例

```bash
# ========== 设计阶段 ==========
> /vibe-brainstorming "实现代码质量改进"
# → 使用 brainstorming skill
# → 生成 docs/plans/20260126-design.md
# → Claude 停止，用户审核

# 用户审核 design.md

> /vibe-plan
# → 使用 writing-plans skill
# → 生成 docs/plans/20260126-plan.md
# → Claude 停止，用户审核

# 用户审核 plan.md

# ========== 初始化阶段 ==========
> /vibe-execute

# vibe-execute 执行 Phase 1:
# 1. 读取 plan.md
# 2. 按转换规则为每个 Task 调用 TaskCreate
# 3. 自动追加：TaskCreate("[校验] 全局需求验证", ...)
# 4. 创建 .vibe/session.yml

# ========== 执行循环 ==========
# 协调者获取 Task 1（pending）

# → 派发 Implementer 子代理
#   - Implementer 实现功能
#   - Implementer 更新 metadata：
#     TaskUpdate taskId=1 metadata={
#       "files_modified": ["src/backup.sh"],
#       "git_commit": "abc123",
#       "test_results": "N/A"
#     }

# → 派发 Spec Reviewer 子代理
#   - ✅ 符合规格

# → 派发 Code Quality Reviewer 子代理
#   - ✅ 通过

# → 主窗口：TaskUpdate taskId=1 status=completed

# 继续 Task 2, 3, ... N

# ========== PreCompact 触发（如果发生）==========
# 上下文满 → PreCompact Hook 触发
# → 提取 transcript.jsonl 中最后 TaskUpdate completed 之后的内容
# → 写入 .vibe/last_task_context.jsonl
# → Compact 发生

# ========== Compact 后恢复 ==========
# SessionStart Hook 触发
# → Claude 按顺序读取：design.md → Task JSON → last_task_context.jsonl
# → 找到 in_progress 或下一个 pending Task
# → 继续执行循环

# ========== 校验阶段 ==========
# 所有业务 Task completed → 校验 Task 是下一个 pending
# 协调者获取校验 Task

# → 校验 Task 执行固定流程：
#   Step 1: 读取所有 Task JSON + metadata
#   - Task 3 metadata: errors_encountered 包含"Pydantic版本冲突 - 已升级" → ✅ 已解决
#   - Task 15 metadata: errors_encountered 包含"暂时跳过第三种检索模式" → ❌ 降级！

#   Step 2: 对比 design.md
#   - design.md 要求"支持3种检索模式"
#   - Task 15 只实现了2种 → ❌ 需求未满足

#   Step 3: 运行完整测试套件
#   pytest → 45/45 passed → ✅

#   Step 4: 发现降级问题
#   → 创建修复 Task: "实现第三种检索模式"
#   → Implementer 执行修复
#   → 重新校验 → ✅ 全部通过

#   Step 5: 校验通过
#   → 保存 Task 快照（此时所有 JSON 仍存在）
#   → 标记校验 Task completed → Task JSON 被系统删除
#   → task-snapshot.md 作为永久历史记录保留
```

---

## 十四、实现清单

| 优先级 | 文件 | 说明 |
|--------|------|------|
| P0 | `.claude/commands/vibe-execute.md` | 第四章的完整命令（含转换规则 + 校验 Task） |
| P0 | `.claude/hooks/session-start.sh` | 第八章的恢复提示词 |
| P0 | `.claude/hooks/pre-compact.sh` | 第八章的 shell 入口 |
| P0 | `.claude/hooks/extract-last-context.js` | 第八章的提取脚本 |
| P0 | `.claude/settings.local.json` | 第十章的 Hook 配置 |
| P1 | `.claude/commands/vibe-brainstorming.md` | 第四章的命令 |
| P1 | `.claude/commands/vibe-plan.md` | 第四章的命令 |
| P1 | `.claude/CLAUDE.md` | 第九章的项目级提示词 |
| P2 | `.claude/skills/brainstorming/SKILL.md` | 继承 V1 |
| P2 | `.claude/skills/writing-plans/SKILL.md` | 继承 V1 |
| P2 | `.claude/skills/test-driven-development/SKILL.md` | 继承 V1 |
| P2 | `.claude/skills/subagent-driven-development/SKILL.md` | 子代理驱动执行 |

---

## 十五、与 V1 的对比总结

| 方面 | V1 | V2 |
|------|----|----|
| **状态管理** | 自定义 `vibe-state.local.md` | Claude Code 原生 Task 系统 |
| **执行细节记录** | 无 | Task metadata 持久化 |
| **执行控制** | Stop Hook 拦截 + 灌 Prompt | Task 系统自动持久化 |
| **Compact 恢复** | 依赖 phase 字段 | PreCompact + SessionStart Hook |
| **完成验证** | verification-before-completion skill | 校验 Task（自动追加，作为最后一个 Task） |
| **降级检测** | 无 | 校验 Task 对比 design.md + metadata |
| **快照机制** | 无 | 校验通过后保存 task-snapshot.md |
| **Ralph Wiggum** | 使用 | 移除（Task 系统替代） |

**核心改进**：
1. **利用原生 Task 系统**：不再维护自定义状态文件，直接使用 Claude Code 的 Task JSON
2. **metadata 记录执行细节**：每个 Task 的执行过程持久化，支持恢复和校验
3. **自动追加校验 Task**：不再依赖 skill 提示，而是作为实际 Task 执行
4. **降级检测**：通过 metadata 中的关键字检测"暂时跳过"、"简化实现"等降级行为
5. **跨 Compact 完整恢复**：PreCompact 保存上下文，SessionStart 引导恢复