Smart Ralph
把功能需求变成结构化规格，再逐任务自动执行——为 Claude Code 与 Codex 打造的规格驱动开发插件。
文档明确了最小化外部影响（原型的终端记录不可变、不授权 push/PR/issue 写操作）、分阶段审批检查点（quick 模式除外）、审批路径转移控制，以及 .ralph-state. 完成后删除、/cancel 清理回滚。扣分点：这些多为 README 声明，本次证据未见 Stop hook 与权限脚本的实际实现；敏感数据处理（如索引中记录 MCP/URL、凭据风险）未提及；发布者身份未经核验。
版本同步测试、锁生命周期测试、Windows/POSIX 进程控制测试显示内部一致性好，StateError、terminationUnverified、controlError 等失败信息设计具体。扣分点：失败信息质量主要经测试间接印证，文档层面故障恢复指引引用的 TROUBLESHOOTING.md 内容未提供；依赖可用性仅见 CI 安装 bats/jq/ripgrep。
面向 Claude Code 与 Codex 双平台，含 triage/prototype/index 多场景，Windows 原生与模拟测试均覆盖，环境适配强。扣分点：能力边界与触发精度主要靠命令表与流程图描述，边界条件（如非 git 项目、超大仓库索引）未见明确说明。
README 结构清晰，安装指引分平台且含本地开发与迁移说明，MIT LICENSE 文件齐全，CI 强制 semver 递增与版本同步，发布说明提到升级路径。扣分点：已知局限需查 TROUBLESHOOTING.md（内容未提供）；specum/speckit 双插件与 v2→v3 迁移对命名稳定性略增负担；CONTRIBUTING.md 内容未提供，维护承诺只能按引用计。
产物是留在项目内的 specs/ 结构化文件，可人工审阅编辑，任务级进度记录与恢复，输出可用性高。扣分点：相对原生 Claude Code 规划能力的边际价值未量化；loop 自动执行与每任务新上下文可能提高 token 成本，成本收益未讨论。
README 声明的锁、发布不可覆盖、删除源后凭收据发布等行为均有对应单元测试佐证，跨源一致性突出。扣分点：部分关键声明（Stop hook 行为、quick 模式转移策略）无实现文件可核对；事实与推断在文档中偶有混合，但总体区分尚可。
- Trust 判断主要基于 README 声明；安装前请自行审阅 Stop hook 脚本与插件源码，确认其权限行为与文档一致。
- --quick 模式会跳过阶段间审批，仅在可接受自动连续执行的受控环境中使用。
- 索引功能会记录外部 URL、MCP 服务器与已安装技能，注意其中可能含敏感环境信息，避免提交到公开仓库。
- 原型执行涉及进程启动与终止（含 taskkill/killpg），请在隔离或沙箱环境验证后再用于生产项目。
- TROUBLESHOOTING.md 与 CONTRIBUTING.md 内容未在本次证据中，故障恢复与贡献流程需自行核实。
这个 Agent 能做什么，适合哪些场景？
Smart Ralph（tzachbon/smart-ralph）是一个 MIT 许可的 Claude Code 插件，同时支持 OpenAI Codex，将 Ralph Wiggum 循环与结构化规格工作流结合。它先把功能请求转化为 research、requirements、design、tasks 四类规格文件，然后由专门的子代理（如 research-analyst、product-manager、architect-reviewer、task-planner、spec-executor）逐任务执行，每个任务都在全新上下文中开始。规格文件保留在项目的 specs/ 目录中，用户可以在每个阶段之间审查或修改；进度记录在 .progress.md，会话中断后可通过 /ralph-specum:start 恢复。大型目标可先用 /ralph-specum:triage 拆分成依赖感知的多个规格（epic）。此外还提供 ralph-speckit 备选插件以支持 GitHub Spec-Kit 方法论，以及 /ralph-specum:index 代码库索引功能，为研究代理生成可检索的组件规格。
用户调用 /ralph-specum:start [name] "goal"（Claude Code）或 $ralph-specum-start（Codex）后，Smart Ralph 依次执行：research-analyst 分析代码库并搜索网络；product-manager 撰写用户故事与验收标准；architect-reviewer 定义架构与权衡；task-planner 按 POC 优先拆分任务；spec-executor 逐任务实现，每个任务以全新上下文开始并依次经历 POC 验证、重构、测试、质量门（lint、类型、CI 检查）四个阶段。可用 /ralph-specum:triage 把大目标拆为 epic 计划；/ralph-specum:prototype 在安全阶段边界用临时 worktree 测试单个设计问题；/ralph-specum:index 扫描现有项目并在 specs/.index/ 下生成组件规格摘要。可选 --quick 跳过阶段间审批直接生成并执行；--tasks-size fine|coarse 控制任务粒度；[P] 标记低冲突并行任务，[VERIFY]/VE 任务表示显式验证。状态存储于 .ralph-state. 与 .progress.md，规范产物写入 specs/<feature>/ 下的 research.md、requirements.md、design.md、tasks.md。
- 在已有代码库上开发新功能的开发者：先运行 /ralph-specum:index 建立可检索索引，再让研究代理复用现有代码上下文生成规格
- 目标横跨多个功能或系统的用户：用 /ralph-specum:triage 拆分成依赖感知的 epic 计划，逐个规格推进
- 希望在自动执行前逐阶段把关的团队：使用默认模式，在 research、requirements、design 等阶段之间审批后再继续
- 想快速拿到结果的个人开发者：使用 --quick 一次性生成全部规格并连续执行
- 遵循 GitHub Spec-Kit 治理流程的团队：改用 ralph-speckit 插件，获得项目宪法与需求到任务的可追溯性
- 对某个设计问题不确定的开发者：在阶段边界运行 /ralph-specum:prototype，用一次性原型验证后再进入设计
这个 Agent 有哪些优点和局限？
- 规格文件（research/requirements/design/tasks）持久保留在项目中，可审查、可编辑、可恢复，执行透明
- 每个阶段由专职子代理负责，任务按 POC 验证→重构→测试→质量门的顺序推进，且有 lint/类型/CI 质量门
- triage 可把大目标拆成依赖感知的 epic 计划，index 可为已有代码库生成可检索组件规格，研究时复用
- 同时支持 Claude Code 与 Codex 两个平台，v3.0.0 起执行循环内置在插件 Stop 钩子中，无需再装独立的 Ralph Loop 插件
- 深度绑定 Claude Code 与 OpenAI Codex 两个宿主运行时，未提供其他模型或环境的适配路径
- Codex 需要审查并信任捆绑的 Stop 钩子才能自动执行任务，否则必须每任务手动运行 $ralph-specum-implement
- 从 v2.x 升级需注意 v3.0.0 将执行移入插件 Stop 钩子，可能需要卸载旧的 Ralph Loop 插件
- 默认模式下阶段间需人工审批，完整流程比单步执行耗时；--quick 模式则跳过原型询问，由插件自行做设计决策
- 仓库未提供性能、成功率等量化评估证据，采用前需自行试用验证
如何安装或部署这个 Agent？
Claude Code：在 Claude Code 中运行 /plugin marketplace add tzachbon/smart-ralph，然后 /plugin install ralph-specum@smart-ralph，安装后重启 Claude Code。Codex：运行 codex plugin marketplace add tzachbon/smart-ralph --sparse .agents/plugins --sparse plugins/ralph-specum-codex，再运行 codex plugin add ralph-specum@smart-ralph，之后开一个新的 Codex 任务，运行 /hooks 审查捆绑的 Stop 钩子并选择信任以启用自动任务执行。本地开发可克隆仓库后运行 claude --plugin-dir ./plugins/ralph-specum。
如何使用这个 Agent？
Claude Code 中执行 /ralph-specum:start user-auth "Add JWT authentication" 启动首个规格；加 --quick 可跳过阶段间审批；不带参数运行 /ralph-specum:start 可恢复当前活跃规格。Codex 中使用 $ralph-specum-start user-auth "Add JWT authentication"，或 $ralph-specum 让插件自行决定下一步；$ralph-specum-triage 用于跨多个功能的大目标。其他常用命令：/ralph-specum:research、/ralph-specum:requirements、/ralph-specum:design、/ralph-specum:tasks、/ralph-specum:implement（逐任务执行）、/ralph-specum:status（查看进度）、/ralph-specum:cancel（取消执行并清除循环状态）。Codex 在未信任 Stop 钩子前需每任务手动运行一次 $ralph-specum-implement。
这个 Agent 与同类方案有什么区别？
仓库本身提供两种工作流：ralph-specum（规格存于 specs/，适合快速迭代）与 ralph-speckit（遵循 GitHub Spec-Kit，存于 .specify/specs/，带项目宪法与需求到任务的可追溯性，适合团队治理与审计）。此外 Smart Ralph v3.0.0 内置执行循环后，取代了此前需要单独安装的 Ralph Loop 插件。