VibeEngineering V2

在 Claude Code CLI 上实现自动化开发系统，融合 Superpowers 专家方法论 + 跨 Compact 恢复机制，实现"人工把关设计，自动执行任务"的工作流程。

核心特性

• 两阶段分离：设计阶段需人工确认，执行阶段全自动化
• 子代理驱动：Implementer → Spec Reviewer → Quality Reviewer 三阶段审查
• 原生 Task 系统：使用 Claude Code 原生 Task 替代自定义状态管理
• 跨 Compact 恢复：PreCompact 保存上下文 → SessionStart 引导恢复
• 降级检测：校验 Task 对比 design.md + metadata 检测实现降级

工作流程

设计阶段（需人工确认）：
/vibe-brainstorming "需求描述" → design.md
    ↓ 用户审核
/vibe-plan → plan.md
    ↓ 用户审核

执行阶段（全自动化）：
/vibe-execute → 创建 Task 系统 → 协调者循环执行

文件结构

项目根目录/
├── README.md                     # 本文件
├── DESIGN.md                     # 详细设计文档
│
├── docs/plans/
│   ├── {timestamp}-design.md     # 需求和架构（设计阶段产出）
│   └── {timestamp}-plan.md       # 实现计划（设计阶段产出）
│
├── .vibe/
│   ├── session.yml               # 会话元信息
│   ├── session-start-prompt.txt  # SessionStart 恢复提示词
│   ├── last_task_context.jsonl   # 当前任务执行上下文（PreCompact 生成）
│   └── task-snapshot.md          # Task 快照（校验通过后保存）
│
├── .claude/
│   ├── commands/
│   │   ├── vibe-brainstorming.md # 需求探索命令
│   │   ├── vibe-plan.md          # 创建计划命令
│   │   └── vibe-execute.md       # 执行命令
│   ├── hooks/
│   │   └── extract-last-context.js  # 上下文提取脚本
│   ├── skills/
│   │   ├── brainstorming/        # 需求探索方法论
│   │   ├── writing-plans/        # 计划编写方法论
│   │   ├── test-driven-development/  # TDD 方法论
│   │   └── subagent-driven-development/  # 子代理驱动执行
│   ├── settings.local.json       # Hook 配置（内联命令）
│   └── CLAUDE.md                 # 项目级提示词

Hook 实现说明

设计 vs 实现

原设计文档中 Hook 配置为调用外部 .sh 脚本：

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

由于 Windows 环境下 Claude Code 执行外部 .sh 脚本存在兼容性问题，当前实现改为内联命令方式：

{
  "hooks": {
    "SessionStart": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "test -f .vibe/last_task_context.jsonl && cat .vibe/session-start-prompt.txt || exit 0"
      }]
    }],
    "PreCompact": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "mkdir -p .vibe && read input && echo \"$input\" | jq -r '.transcript_path' > .vibe/debug-transcript-path.txt && sleep 1 && node .claude/hooks/extract-last-context.js $(cat .vibe/debug-transcript-path.txt) > .vibe/last_task_context.jsonl 2> .vibe/debug-error.txt; exit 0"
      }]
    }]
  }
}

内联命令 vs 外部脚本

方面	外部脚本	内联命令
可读性	好（独立文件）	差（一行挤在 JSON）
维护性	易修改	复杂命令难改
Windows 兼容	❌ 有问题	✅ 正常工作
功能	完整	完整

结论：功能完全一致，内联命令只是把脚本逻辑写成一行。

Hook 工作原理

┌─────────────────────────────────────────────────────────┐
│                    Claude Code                          │
│                                                         │
│   Hook 事件触发                                          │
│        │                                                │
│        ▼                                                │
│   ┌─────────────────────────────────────────────┐      │
│   │  Shell 环境 (Git Bash)                       │      │
│   │                                              │      │
│   │  stdin  ← Claude Code 传入的 JSON 数据       │      │
│   │  stdout → 输出注入到 Claude 上下文           │      │
│   │                                              │      │
│   └─────────────────────────────────────────────┘      │
│        │                                                │
│        ▼                                                │
│   Claude 收到 stdout 输出                                │
└─────────────────────────────────────────────────────────┘

SessionStart Hook

触发时机：每次打开 Claude Code 会话

逻辑：

test -f .vibe/last_task_context.jsonl  # 检查是否存在恢复上下文
  && cat .vibe/session-start-prompt.txt  # 存在则输出恢复提示词
  || exit 0                              # 不存在则静默退出

作用：只有在 Compact 后（存在 last_task_context.jsonl）才注入恢复提示词，引导 Claude 读取必要文件恢复执行。

PreCompact Hook

触发时机：上下文即将满，执行 /compact 之前

逻辑：

mkdir -p .vibe                           # 确保目录存在
&& read input                            # 从 stdin 读取 Claude Code 传入的 JSON
&& echo "$input" | jq -r '.transcript_path'  # 提取 transcript 文件路径
&& sleep 1                               # 等待 transcript 写入完成
&& node extract-last-context.js ...      # 调用 Node 脚本提取上下文

作用：从 transcript.jsonl 提取最后一次 TaskUpdate completed 之后的内容，保存到 last_task_context.jsonl，供恢复时使用。

环境要求

依赖

• Node.js（用于运行 extract-last-context.js）
• jq（用于解析 JSON）
• Git Bash（Windows 用户）

Windows 用户注意

Claude Code 在 Windows 上默认使用 cmd.exe 执行 Hook 命令，无法识别 bash 语法。需要设置环境变量指定 Git Bash 路径：

set CLAUDE_CODE_GIT_BASH_PATH=<你的Git安装路径>\bin\bash.exe

例如，如果 Git 安装在 C:\Program Files\Git：

set CLAUDE_CODE_GIT_BASH_PATH=C:\Program Files\Git\bin\bash.exe

建议将此变量添加到系统环境变量中永久生效。

跨 Compact 恢复机制

执行中...
    │
    ▼ 上下文即将满
┌─────────────────────────────────┐
│  PreCompact Hook 触发            │
│  提取 transcript → last_task_context.jsonl
└─────────────────────────────────┘
    │
    ▼ Compact 发生（上下文被压缩）
┌─────────────────────────────────┐
│  SessionStart Hook 触发          │
│  检测到 last_task_context.jsonl  │
│  输出恢复提示词给 Claude         │
└─────────────────────────────────┘
    │
    ▼
Claude 按提示读取：
  1. vibe-execute.md（执行流程）
  2. subagent-driven-development skill（子代理模板）
  3. session.yml → design.md（需求）
  4. TaskList（任务状态）
  5. last_task_context.jsonl（中断点上下文）
    │
    ▼
从中断点继续执行

快速开始

1. 克隆项目到本地

2. Windows 用户设置环境变量（参见上方"环境要求"）

3. 进入项目目录，启动 Claude Code：

   cd your-project
   claude
   

4. 开始设计阶段：

   /vibe-brainstorming "你的需求描述"
   

5. 审核 design.md 后，创建计划：

   /vibe-plan
   

6. 审核 plan.md 后，开始执行：

   /vibe-execute
   

参考

• DESIGN.md - 完整设计文档
• Claude Code 官方文档