th-ralph-evo

name	th-ralph-evo
version	1.0.0
description	Ralph Evolution - 自动化闭环开发系统 整合 decision-record、bug-analyzer、prd-to-code、prd-evolution 和 ralpha 形成自驱动开发工作流：决策→调研→PRD→代码→测试→Bug分析→优化
triggers	["启动自动化开发","创建智能开发团队","启动ralph闭环","自动化开发流程","智能开发系统","闭环开发","ralph evo"]

Ralph Evolution - 自动化闭环开发系统

角色: 智能开发编排中枢 核心价值: 从需求到代码的自动化闭环，持续迭代优化 版本: v1.0 (Multi-Agent Orchestrator)

---

系统架构

┌─────────────────────────────────────────────────────────────────────────────┐
│                         Ralph Evolution 自动化闭环                           │
└─────────────────────────────────────────────────────────────────────────────┘

[输入层]                    [处理层]                    [输出层]
┌──────────┐              ┌──────────────┐           ┌────────────┐
│决策记录   │─────────────▶│ 中央编排器    │──────────▶│ PRD 文档   │
│decision  │              │Orchestrator  │           │tree.md     │
│-record   │              └──────┬───────┘           └────────────┘
└──────────┘                     │
    │                            ▼
    │                   ┌────────────────┐
    │                   │ th-deep-coder2 │
    │                   │   深度调研     │
    │                   └───────┬────────┘
    │                           │
    ▼                           ▼
┌────────────────────────────────────────────────────────────┐
│                      自动化执行引擎                          │
├────────────────────────────────────────────────────────────┤
│  ┌──────────────┐   ┌──────────────┐   ┌────────────────┐  │
│  │ prd-evolution│──▶│  prd-to-code │──▶│    ralpha      │  │
│  │  版本管理    │   │   多代理实现  │   │  worktree管理  │  │
│  └──────────────┘   └──────────────┘   └────────────────┘  │
│                                                   │         │
└───────────────────────────────────────────────────┼─────────┘
                                                    ▼
┌─────────────────────────────────────────────────────────────┐
│                      质量保障层                              │
├─────────────────────────────────────────────────────────────┤
│  ┌──────────────┐   ┌──────────────┐   ┌─────────────────┐  │
│  │   自动化测试  │──▶│ th-bug       │──▶│ 反馈至决策层     │  │
│  │              │   │ -analyzer    │   │ (闭环优化)      │  │
│  └──────────────┘   └──────────────┘   └─────────────────┘  │
└─────────────────────────────────────────────────────────────┘

---

核心概念

1. 决策驱动开发 (Decision-Driven Development)

用户输入 (零散需求/抱怨)
    │
    ▼
┌────────────────────┐
│  decision-record   │  ← 自动触发，无需等待用户完整描述
│  需求演进与追踪    │
└────────┬───────────┘
         │
         ▼
    ┌────────────┐
    │ 功能主题   │  ← AI主动归纳主题
    ├────────────┤
    │ 1级解读    │  ← 表面层方案
    │ 2级解读    │  ← 系统层方案
    │ N级解读    │  ← 深层剖析
    │ 本地意见   │  ← 代码库分析
    │ 外部意见   │  ← 多模型聚合
    │ 最终方案   │  ← 用户确认
    └─────┬──────┘
          │
          ▼
    ┌────────────┐
    │ PRD 生成   │  ← 自动转换为 PRD
    └────────────┘

2. 自动化触发机制

触发条件:
  decision_record:
    - 文件变更监听: ~/src/docs/decisions/*.md
    - 状态变化: 草稿 → 已确认
    - 自动动作: 启动 deep-coder2 调研

  prd_evolution:
    - PRD 状态: 已确认 → 待实现
    - 自动动作: 创建 prd-to-code 团队

  ralpha:
    - PRD 就绪信号
    - 自动动作: 创建 worktree 并行开发

  bug_analyzer:
    - 测试失败信号
    - 代码覆盖率低于阈值
    - 自动动作: 分析影响并修复

3. 闭环反馈

        ┌────────────────────────────┐
        │         用户确认            │
        └────────────┬───────────────┘
                     │
    ┌────────────────┼────────────────┐
    │                ▼                │
    │       ┌──────────────┐          │
    │       │   PRD 实现   │          │
    │       └──────┬───────┘          │
    │              │                  │
    │              ▼                  │
    │       ┌──────────────┐          │
    │       │ 自动化测试   │          │
    │       └──────┬───────┘          │
    │              │                  │
    ▼              ▼                  ▼
┌────────────────────────────────────────┐
│            质量评估节点                 │
├────────────────────────────────────────┤
│  测试通过? → 覆盖率>90%? → 安全扫描?    │
│       │           │           │       │
│       ▼           ▼           ▼       │
│    [是]        [是]        [通过]      │
│       │           │           │       │
│       └───────────┴───────────┘       │
│                   │                   │
│                   ▼                   │
│           ┌──────────────┐           │
│           │  完成闭环    │           │
│           └──────────────┘           │
│                                      │
│   任一检查失败:                      │
│       │                              │
│       ▼                              │
│   ┌──────────────┐                   │
│   │ bug-analyzer │ ← 自动分析影响    │
│   │   分析修复   │   生成修复方案    │
│   └──────┬───────┘                   │
│          │                           │
│          ▼                           │
│   更新 PRD / 创建热修复 worktree      │
│          │                           │
│          └───────────────────────────┘
│                     │
│                     ▼
│            回到开发阶段
└────────────────────────────────────────┘

---

工作流程

Phase 1: 启动自动化开发

用户输入:

启动自动化开发 - 用户认证模块

系统自动执行:

1. 检查决策记录
   ├── 读取 ~/src/docs/decisions/INDEX.md
   ├── 查找相关决策记录
   └── 若无，询问是否创建

2. 检查 PRD 状态
   ├── 读取 prd-evolution tree.md
   ├── 确认是否有待实现 PRD
   └── 若无，从 decision-record 生成

3. 启动深度调研 (可选)
   ├── 触发 th-deep-coder2
   ├── 收集技术方案
   └── 整合到 PRD

4. 创建实现团队
   ├── 使用 orchestrator 创建团队
   ├── 根据 PRD 技术栈选择代理类型
   └── 分配 worktree

5. 启动可视化面板
   └── 打开 dashboard 显示实时状态

Phase 2: 并行开发执行

┌─────────────────────────────────────────────────────────────┐
│                      多代理并行执行                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │ Worktree 1  │  │ Worktree 2  │  │ Worktree N  │         │
│  │ 数据层      │  │ 逻辑层      │  │ UI 层       │         │
│  │             │  │             │  │             │         │
│  │ data-agent  │  │ logic-agent │  │ ui-agent    │         │
│  │ (并行)      │  │ (等待data)  │  │ (并行)      │         │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘         │
│         │                │                │                │
│         └────────────────┼────────────────┘                │
│                          │                                 │
│                          ▼                                 │
│                   ┌─────────────┐                          │
│                   │ test-agent  │                          │
│                   │ (TDD 驱动)  │                          │
│                   └──────┬──────┘                          │
│                          │                                 │
│                          ▼                                 │
│  ┌────────────────────────────────────────────┐           │
│  │ 质量检查: security-reviewer + code-reviewer │           │
│  └────────────────────────────────────────────┘           │
│                          │                                 │
│                          ▼                                 │
│                   ┌─────────────┐                          │
│                   │ 自动化测试   │                          │
│                   └──────┬──────┘                          │
│                          │                                 │
└──────────────────────────┼─────────────────────────────────┘
                           │
              ┌────────────┴────────────┐
              ▼                         ▼
        [测试通过]                  [测试失败]
              │                         │
              ▼                         ▼
        ┌──────────┐              ┌──────────────┐
        │ 合并代码 │              │ bug-analyzer │
        │ 标记完成 │              │ 分析并修复   │
        └──────────┘              └──────────────┘
                                           │
                                           ▼
                                    更新 PRD / 重试

Phase 3: Bug 分析与闭环

测试失败触发:

1. bug-analyzer 分析
   ├── 读取测试失败日志
   ├── 使用 GitNexus 分析影响范围
   ├── 定位根因
   └── 生成修复方案

2. 决策分支
   ├── 若影响小: 直接修复
   ├── 若影响大: 创建 decision-record 讨论
   └── 若需架构调整: 更新 PRD-evolution

3. 自动修复执行
   ├── 创建 hotfix worktree
   ├── 实施修复
   ├── 回归测试
   └── 合并或废弃

4. 学习记录
   ├── 记录 bug 模式到知识库
   ├── 更新测试用例
   └── 反馈到 decision-record

---

可视化面板

Dashboard 组件

┌──────────────────────────────────────────────────────────────────────┐
│                    Ralph Evolution 实时监控面板                       │
├──────────────────────────────────────────────────────────────────────┤
│                                                                       │
│  [决策状态]                    [PRD 版本树]              [团队状态]   │
│  ┌────────────┐              ┌──────────────┐          ┌──────────┐  │
│  │ 活跃决策   │              │ prd-v1.0     │          │ 运行中   │  │
│  │   5个      │              │ ├──feature-A│🔵        │   3/5    │  │
│  │ 待确认     │              │ ├──feature-B│🔵        │          │  │
│  │   2个      │              │ └──feature-C│🟡        │ 空闲     │  │
│  └────────────┘              └──────────────┘          │   2/5    │  │
│                                                          └──────────┘  │
│  [当前 Worktrees]              [测试状态]                [Bug 分析]   │
│  ┌────────────────┐          ┌──────────────┐          ┌──────────┐  │
│  │ auth-layer     │          │ 单元测试     │          │ 待分析   │  │
│  │   ├── data     │✅        │   98% ✅     │          │   0      │  │
│  │   ├── logic    │🏃        │              │          │          │  │
│  │   └── ui       │✅        │ 集成测试     │          │ 已修复   │  │
│  │                │          │   85% ⚠️     │          │   3      │  │
│  │ payment-layer  │          │              │          │          │  │
│  │   ├── data     │✅        │ E2E 测试     │          │ 复现中   │  │
│  │   └── logic    │✅        │   12/15 ✅   │          │   1      │  │
│  └────────────────┘          └──────────────┘          └──────────┘  │
│                                                                       │
│  [影响分析]                                                           │
│  ┌──────────────────────────────────────────────────────────────┐   │
│  │ 最近变更: auth-layer/data/models/user.ts                     │   │
│  │ 影响范围: d=1 (3个文件) | d=2 (8个文件) | 风险: MEDIUM        │   │
│  └──────────────────────────────────────────────────────────────┘   │
│                                                                       │
│  [系统日志]                                                           │
│  2026-03-23 14:30:15  [INFO]  Worktree 'auth-layer' 测试通过         │
│  2026-03-23 14:28:02  [WARN]  payment-layer 集成测试覆盖率低于90%    │
│  2026-03-23 14:25:44  [INFO]  decision-record '性能优化' 已确认      │
│                                                                       │
└──────────────────────────────────────────────────────────────────────┘

交互命令

命令	说明
ralph-evo dashboard	启动实时监控面板
ralph-evo status	查看当前状态摘要
ralph-evo pause	暂停自动化流程
ralph-evo resume	恢复自动化流程
ralph-evo reset	重置状态（保留历史）

---

文件结构

~/.claude/skills/th-ralph-evo/
├── SKILL.md                      # 本文件
├── scripts/
│   ├── orchestrator.mjs          # 中央编排器 (核心)
│   ├── dashboard.mjs             # 可视化面板
│   ├── decision-monitor.mjs      # 决策文件监控
│   ├── prd-sync.mjs              # PRD 状态同步
│   └── bug-analyzer-bridge.mjs   # Bug分析桥接
├── templates/
│   └── workflow-config.yaml      # 工作流配置模板
└── docs/
    └── architecture.md           # 架构详细设计

---

集成说明

与现有技能的关系

decision-record (需求输入)
        │
        ▼ 自动触发
th-deep-coder2 (深度调研)
        │
        ▼ 数据流入
prd-evolution (版本管理)
        │
        ▼ 状态变更触发
prd-to-code (多代理实现)
        │
        ▼ 工作分配
ralpha (worktree管理)
        │
        ▼ 质量反馈
th-bug-analyzer (Bug分析)
        │
        └───────┐
                ▼
        反馈至决策层 (闭环)

配置示例

# workflow-config.yaml
workflow:
  name: "用户认证模块开发"
  triggers:
    decision_record:
      path: "~/src/docs/decisions/user-auth.md"
      auto_investigate: true

  prd:
    id: "prd-user-auth-v1"
    auto_create: true
    evolution:
      enable_version_tree: true

  team:
    type: "multi-agent"
    workers:
      - name: "data-agent"
        layer: "data"
        model: "typescript-reviewer"
      - name: "logic-agent"
        layer: "logic"
        model: "typescript-reviewer"
      - name: "ui-agent"
        layer: "ui"
        model: "typescript-reviewer"
      - name: "test-agent"
        layer: "test"
        model: "tdd-guide"

  quality_gates:
    test_coverage: 90
    security_scan: true
    code_review: true

  feedback:
    auto_bug_analyze: true
    create_decision_on_failure: true

---

快速开始

1. 启动一个完整的自动化开发流程

# 启动 Ralph Evolution
ralph-evo start --project user-auth --from-decision

# 或从现有 PRD 开始
ralph-evo start --project user-auth --from-prd prd-user-auth-v1

2. 在 Claude Code 中使用

用户: 启动自动化开发 - 实现用户认证系统

AI:
1. 读取 decision-record 中关于用户认证的决策
2. 检查 PRD 状态
3. 启动深度调研 (询问用户是否进行)
4. 创建多代理团队
5. 打开可视化面板
6. 开始并行开发

---

注意事项

1. 自动 vs 手动: 系统支持全自动化和半自动化模式，关键节点会询问用户确认
2. 资源管理: 自动清理已完成的 worktree，监控磁盘使用
3. 错误处理: 遇到关键错误时暂停，生成决策记录供用户审阅
4. 学习积累: Bug 分析结果自动记录到知识库，避免重复问题

---

最后更新：2026-03-23 | 版本：v1.0 (自动化闭环系统)