c484cafb45
- 两阶段分离：设计阶段人工确认，执行阶段全自动化 - 子代理驱动：Implementer → Spec Reviewer → Quality Reviewer - 原生 Task 系统：使用 Claude Code Task 替代自定义状态管理 - 跨 Compact 恢复：PreCompact + SessionStart Hook（内联命令实现） Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
38 KiB
38 KiB
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 被系统删除
二、整体流程图
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
---
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
---
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
这是最关键的命令，包含完整的转换规则和执行逻辑。
---
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 子代理时使用此模板：
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 完整示例
{
"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。
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 句话]
八、跨 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
#!/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
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
#!/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 的用途：
## 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
{
"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 格式
# .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
# 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）
十三、完整执行示例
# ========== 设计阶段 ==========
> /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 系统替代） |
核心改进：
- 利用原生 Task 系统：不再维护自定义状态文件，直接使用 Claude Code 的 Task JSON
- metadata 记录执行细节：每个 Task 的执行过程持久化，支持恢复和校验
- 自动追加校验 Task：不再依赖 skill 提示，而是作为实际 Task 执行
- 降级检测：通过 metadata 中的关键字检测"暂时跳过"、"简化实现"等降级行为
- 跨 Compact 完整恢复：PreCompact 保存上下文，SessionStart 引导恢复