ralphy-spec

English | 简体中文 | 한국어 | 日本語

规范驱动的 AI 开发 + 迭代执行。 结合 OpenSpec 和 Ralph 循环，实现可预测的 AI 辅助编码。

官网： https://ralphy-spec.org 文档： https://ralphy-spec.org/zh/docs/ 更新日志： https://ralphy-spec.org/zh/changelog/ · GitHub

快速开始

npx ralphy-spec init

CLI 基础用法：

ralphy-spec run --dry-run
ralphy-spec run
ralphy-spec status
ralphy-spec budget --json

然后使用你的 AI 工具对应的命令：

Cursor

| 命令 | 功能 | |------|------| | /ralphy-plan | 从需求创建规范 | | /ralphy-implement | 迭代循环构建 | | /ralphy-validate | 验证验收标准 | | /ralphy-archive | 完成并归档 |

Claude Code

| 命令 | 功能 | |------|------| | /ralphy-plan | 从需求创建规范 | | /ralphy-implement | 迭代循环构建 | | /ralphy-validate | 验证验收标准 | | /ralphy-archive | 完成并归档 |

OpenCode

使用自然语言配合 AGENTS.md：

• "Follow AGENTS.md to plan [功能]"
• "Follow AGENTS.md to implement [变更]"
• "Follow AGENTS.md to validate"
• "Follow AGENTS.md to archive [变更]"

配合 Ralph 循环运行器：

npm install -g @th0rgal/ralph-wiggum
ralph "Follow AGENTS.md to implement add-api. Output <promise>TASK_COMPLETE</promise> when done." --max-iterations 20

工作流示例

# 1. 规划：从你的想法创建规范
You: /ralphy-plan 添加 JWT 用户认证

# 2. 实现：AI 迭代构建
You: /ralphy-implement add-user-auth

# 3. 验证：确保测试通过
You: /ralphy-validate

# 4. 归档：完成变更
You: /ralphy-archive add-user-auth

创建的文件

.cursor/prompts/          # 或 .claude/commands/
├── ralphy-plan.md
├── ralphy-implement.md
├── ralphy-validate.md
└── ralphy-archive.md

AGENTS.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/<runId>.md`）
├── logs/                 # 后端原始输出（尽力写入）
├── worktrees/            # Git worktree（启用 worktree 模式时）
└── tasks/                # 单任务产物（CONTEXT / REPAIR / NOTES）
    └── <taskId>/
        ├── CONTEXT.md
        ├── REPAIR.md
        └── NOTES.md

注意：如果检测到旧的 .ralphy/，会自动迁移到 ralphy-spec/ 并提示。

工作原理

Ralph Wiggum 循环： AI 重复接收相同提示直到任务完成。每次迭代，它都能看到文件中的之前工作并自我纠正。

OpenSpec： 先有规范后有代码。结构化的规范和验收标准确保 AI 知道要构建什么。

为什么结合使用：

| 问题 | 解决方案 | |------|----------| | 聊天中的模糊需求 | 规范锁定意图 | | AI 中途停止 | 循环重试直到完成 | | 无法验证 | 测试验证输出 | | 工具特定设置 | 一条命令搞定所有 |

安装选项

# 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