One-command setup for Ralph loop + OpenSpec workflows across Cursor, OpenCode, and Claude Code.
npm install ralphy-spec规范驱动的 AI 开发 + 迭代执行。 结合 OpenSpec 和 Ralph 循环,实现可预测的 AI 辅助编码。
官网: https://ralphy-spec.org
文档: https://ralphy-spec.org/zh/docs/
更新日志: https://ralphy-spec.org/zh/changelog/ · GitHub
``bash`
npx ralphy-spec init
CLI 基础用法:
`bash`
ralphy-spec run --dry-run
ralphy-spec run
ralphy-spec status
ralphy-spec budget --json
然后使用你的 AI 工具对应的命令:
| 命令 | 功能 |
|------|------|
| /ralphy-plan | 从需求创建规范 |/ralphy-implement
| | 迭代循环构建 |/ralphy-validate
| | 验证验收标准 |/ralphy-archive
| | 完成并归档 |
| 命令 | 功能 |
|------|------|
| /ralphy-plan | 从需求创建规范 |/ralphy-implement
| | 迭代循环构建 |/ralphy-validate
| | 验证验收标准 |/ralphy-archive
| | 完成并归档 |
使用自然语言配合 AGENTS.md:
- "Follow AGENTS.md to plan [功能]""Follow AGENTS.md to implement [变更]"
- "Follow AGENTS.md to validate"
- "Follow AGENTS.md to archive [变更]"
-
配合 Ralph 循环运行器:
`bash`
npm install -g @th0rgal/ralph-wiggum
ralph "Follow AGENTS.md to implement add-api. Output
`bash1. 规划:从你的想法创建规范
You: /ralphy-plan 添加 JWT 用户认证
创建的文件
`
.cursor/prompts/ # 或 .claude/commands/
├── ralphy-plan.md
├── ralphy-implement.md
├── ralphy-validate.md
└── ralphy-archive.mdAGENTS.md # OpenCode 使用
openspec/
├── specs/ # 真实来源
├── changes/ # 进行中的工作
├── archive/ # 已完成
└── project.md # 上下文
ralphy-spec/ # 本地状态 + 可读产物(IDE 友好)
├── state.db # SQLite 运行/任务日志
├── STATUS.md # 实时状态(
ralphy-spec status 优先读取)
├── TASKS.md # 任务看板
├── BUDGET.md # 花费/预算
├── runs/ # 不可变运行日志(runs/)
├── logs/ # 后端原始输出(尽力写入)
├── worktrees/ # Git worktree(启用 worktree 模式时)
└── tasks/ # 单任务产物(CONTEXT / REPAIR / NOTES)
└── /
├── CONTEXT.md
├── REPAIR.md
└── NOTES.md
`> 注意:如果检测到旧的
.ralphy/,会自动迁移到 ralphy-spec/ 并提示。工作原理
Ralph Wiggum 循环: AI 重复接收相同提示直到任务完成。每次迭代,它都能看到文件中的之前工作并自我纠正。
OpenSpec: 先有规范后有代码。结构化的规范和验收标准确保 AI 知道要构建什么。
为什么结合使用:
| 问题 | 解决方案 |
|------|----------|
| 聊天中的模糊需求 | 规范锁定意图 |
| AI 中途停止 | 循环重试直到完成 |
| 无法验证 | 测试验证输出 |
| 工具特定设置 | 一条命令搞定所有 |
安装选项
`bash
npx(推荐)
npx ralphy-spec init全局安装
npm install -g ralphy-spec
ralphy-spec init指定工具
ralphy-spec init --tools cursor,claude-code,opencode
``基于以下项目:
- Ralph 方法论 by Geoffrey Huntley
- opencode-ralph-wiggum by @Th0rgal
- OpenSpec by Fission-AI
BSD-3-Clause