/cc-ralph

description: CC-Best Ralph Loop 集成，长时间自主循环
argument-hint: "[task-description]"
allowed-tools: Read, Write, Edit, Glob, Grep, Bash, TodoWrite, Task, WebSearch, WebFetch, Skill, mcp__*

/cc-ralph - CC-Best Ralph Loop 集成

使用 cc-best 工作流启动 Ralph Loop 自主开发循环。

**同时支持插件用户和 Clone 用户。**

---

与官方 ralph-loop 的关系

┌─────────────────────────────────────────────────────────────┐
│  /cc-best:cc-ralph (cc-best 插件)                                    │
│  ├── 读取项目状态 (progress.md, CLAUDE.md)                   │
│  ├── 生成 cc-best 工作流 Prompt                              │
│  │   (角色切换、迭代步骤、完成标准)                           │
│  └── 调用 ↓                                                  │
├─────────────────────────────────────────────────────────────┤
│  /ralph-loop:ralph-loop (官方插件)                           │
│  ├── 提供循环机制 (Stop hook)                                │
│  ├── 管理迭代次数                                            │
│  └── 检测完成信号 (<promise>)                                │
└─────────────────────────────────────────────────────────────┘

**简单理解**：

• **ralph-loop**：官方插件，提供"循环"能力（让 Claude 持续工作直到完成）
• **cc-ralph**：cc-best 的包装命令，提供"工作流"（告诉 Claude 按什么流程工作）

**为什么需要 cc-ralph？** 直接用 `/ralph-loop:ralph-loop "任务描述"` 时，需要手动编写完整的 prompt。 而 `/cc-best:cc-ralph` 自动：

1. 读取项目当前状态 2. 注入 cc-best 的角色工作流（PM→Lead→Designer→Dev→QA） 3. 添加完成标准和卡住处理逻辑

---

前置条件

需要安装 `ralph-loop` 官方插件：

/plugin install ralph-loop@claude-plugins-official

> ⚠️ **Windows 用户注意**： > > ralph-loop 插件的 setup 脚本是 bash 脚本，在 Windows 原生环境可能报错： > > ``` > Error: Bash command failed for pattern "...setup-ralph-loop.sh" > ``` > > **解决方案**： > > 1. **推荐**：使用 WSL (Windows Subsystem for Linux) > 2. **替代**：使用 Git Bash 运行 Claude Code > 3. **替代**：直接使用 `/cc-best:iterate`（单会话版本，无需 ralph-loop） > > ralph-loop 插件还依赖 `jq` 工具，需提前安装。

---

使用方式

基本用法

# 自动读取 progress.md，继续当前任务
/cc-best:cc-ralph

# 指定任务描述
/cc-best:cc-ralph "实现用户登录功能"

# 指定最大迭代次数
/cc-best:cc-ralph "完成 Phase 2" --max-iterations 20

选择模式

# 完整功能开发（默认）
/cc-best:cc-ralph --mode full-feature "实现用户认证"

# Phase 迭代（按 progress.md 推进）
/cc-best:cc-ralph --mode iterate

# Bug 修复
/cc-best:cc-ralph --mode bug-fix "修复登录超时问题"

# 代码重构
/cc-best:cc-ralph --mode refactor "重构认证模块"

# 修复测试
/cc-best:cc-ralph --mode fix-tests

# 文档生成
/cc-best:cc-ralph --mode doc-gen "生成 API 文档"

复制模板到本地（可选）

# 将模板复制到 .claude/ralph-prompts/（方便自定义）
/cc-best:cc-ralph --setup

---

执行流程

1. 检查环境

• 验证 ralph-loop 插件是否已安装
• 未安装则提示安装命令并退出

2. 归档历史记录（重要）

启动前先运行归档脚本，防止 progress.md 过大：

node scripts/node/archive-progress.js memory-bank

归档策略（滚动窗口）：

• **最近完成**: 保留 5 项，其余移到 progress-archive.md
• **最近决策**: 保留 5 条
• **最近检查点**: 保留 5 个

3. 检测用户类型

如果存在 .claude/ralph-prompts/ 目录：
  → Clone 用户，使用本地模板
否则：
  → 插件用户，使用内嵌工作流

4. 读取项目上下文

• `memory-bank/progress.md` - 当前进度和待办任务
• `CLAUDE.md` - 核心约束和原则

5. 生成 Prompt

根据 `--mode` 参数选择对应的工作流：

| Mode | 描述 | 完成信号 | | -------------- | ----------------------------------- | ------------------- | | `full-feature` | 完整功能开发（需求→设计→开发→测试） | `FEATURE_COMPLETE` | | `iterate` | Phase 迭代，按 progress.md 推进 | `PHASE_COMPLETE` | | `bug-fix` | 定位并修复 Bug | `BUG_FIXED` | | `refactor` | 改善代码质量 | `REFACTOR_COMPLETE` | | `fix-tests` | 让测试通过 | `TESTS_PASSING` | | `doc-gen` | 生成/更新文档 | `DOCS_COMPLETE` |

6. 启动 Ralph Loop

调用 `/ralph-loop:ralph-loop` 命令，传入生成的 prompt。

---

核心工作流（内嵌）

当没有本地模板时，使用以下内嵌工作流：

角色选择规则

| 当前状态 | 选择角色 | 动作 | | -------------------- | ----------- | ------------------------------------ | | 无需求文档 | `/cc-best:pm` | 需求分析，创建 REQ-XXX | | REQ 有待澄清项 | `/cc-best:clarify` | 需求澄清 | | 有需求无设计 | `/cc-best:lead` | 技术设计，创建 DES-XXX | | 有设计，前端任务 | `/cc-best:designer` | UI 设计指导 | | 有任务待开发 | `/cc-best:dev` | 编码实现 | | 有代码待验证 | `/cc-best:verify` | 综合验证（构建+类型+Lint+测试+安全） | | 验证通过，待功能验收 | `/cc-best:qa` | 功能验收 | | QA 发现 Bug | `/cc-best:dev` | 修复后重新 `/cc-best:verify` |

每次迭代步骤

1. **读取上下文** - progress.md + CLAUDE.md 2. **确定角色和任务** - 根据状态选择角色 3. **执行任务** - 按角色职责执行 4. **验证结果** - `/cc-best:test` + `/cc-best:build` 5. **提交和更新** - `/cc-best:commit` + 更新 progress.md 6. **检查归档** - 如果 progress.md 超过限制，自动归档 7. **继续下一任务** - 不等待用户

关键规则（来自 CLAUDE.md）

1. **P1 接口处理** - 调用前必须查阅文档，**禁止猜测** 2. **P3 业务理解** - 必须来源于明确需求，**禁止假设** 3. **A1 上下文推断** - 基于项目上下文推断，**不中断询问用户** 4. **A2 决策记录** - 记录依据和置信度

卡住时的处理

如果连续 3 次迭代没有进展：

1. 在 progress.md 记录阻塞原因 2. 列出已尝试的方案 3. 输出 `<promise>BLOCKED</promise>` 等待人工介入

---

--setup 功能

当使用 `--setup` 参数时：

1. **检查目标目录**

• 如果 `.claude/ralph-prompts/` 已存在，询问是否覆盖

2. **创建模板文件**

• Clone 用户：提示模板已存在
• 插件用户：创建以下文件
• `iterate-phase.md` - Phase 迭代
• `full-feature.md` - 完整功能开发
• `bug-fix.md` - Bug 修复
• `refactor.md` - 代码重构
• `fix-tests.md` - 修复测试
• `doc-gen.md` - 文档生成
• `README` - 使用说明

3. **输出结果**

   ✅ Ralph Loop 模板配置完成

   已创建模板：
   - .claude/ralph-prompts/iterate-phase.md   (Phase 迭代)
   - .claude/ralph-prompts/full-feature.md    (完整功能开发)
   - .claude/ralph-prompts/bug-fix.md         (Bug 修复)
   - .claude/ralph-prompts/refactor.md        (代码重构)
   - .claude/ralph-prompts/fix-tests.md       (修复测试)
   - .claude/ralph-prompts/doc-gen.md         (文档生成)

   现在可以编辑这些模板，然后使用 /cc-best:cc-ralph 启动循环

---

与 /cc-best:iterate 的区别

| 功能 | /cc-best:iterate | /cc-best:cc-ralph | | -------- | --------------- | ------------------ | | 会话边界 | 单会话内 | 跨会话自动重启 | | 进度保存 | progress.md | progress.md + 插件 | | 适用场景 | 短期任务（<2h） | 长期项目（小时级） | | 中断恢复 | 手动