VibeEngineering/README.md

# 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` 脚本：

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

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

```json
{
  "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 会话

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

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

### PreCompact Hook

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

**逻辑**：
```bash
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 路径：

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

例如，如果 Git 安装在 `C:\Program Files\Git`：
```batch
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：
   ```batch
   cd your-project
   claude
   ```

4. 开始设计阶段：
   ```
   /vibe-brainstorming "你的需求描述"
   ```

5. 审核 design.md 后，创建计划：
   ```
   /vibe-plan
   ```

6. 审核 plan.md 后，开始执行：
   ```
   /vibe-execute
   ```

## 参考

- [DESIGN.md](./DESIGN.md) - 完整设计文档
- [Claude Code 官方文档](https://docs.anthropic.com/en/docs/claude-code)