ralphy-spec

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

规范驱动的 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 工具对应的命令：

$3

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

$3

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

$3

使用自然语言配合 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 TASK_COMPLETE when done." --max-iterations 20
`

工作流示例

`bash


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/.md）
├── 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