Ralph 实战指南

# 检查依赖
claude --version   # Claude Code CLI
jq --version       # JSON 处理
git --version      # Git

Install this skill for me: https://github.com/snarktank/ralph

# 添加并安装插件
/plugin marketplace add snarktank/ralph
/plugin install ralph-skills@ralph-marketplace

# 先克隆仓库
git clone https://github.com/snarktank/ralph.git /tmp/ralph

# Claude Code 用户
cp -r /tmp/ralph/skills/prd ~/.claude/skills/
cp -r /tmp/ralph/skills/ralph ~/.claude/skills/

# Amp 用户
cp -r /tmp/ralph/skills/prd ~/.config/amp/skills/
cp -r /tmp/ralph/skills/ralph ~/.config/amp/skills/

# 克隆 Ralph 仓库
git clone https://github.com/snarktank/ralph.git /tmp/ralph

# 复制核心文件到项目
mkdir -p scripts/ralph
cp /tmp/ralph/ralph.sh scripts/ralph/
cp /tmp/ralph/CLAUDE.md scripts/ralph/   # Claude Code 用户
# 或
cp /tmp/ralph/prompt.md scripts/ralph/   # Amp 用户

# 赋予执行权限
chmod +x scripts/ralph/ralph.sh

your-project/
├── scripts/ralph/
│   ├── ralph.sh        # 核心循环脚本
│   └── CLAUDE.md       # Claude Code 的 Prompt 模板
├── tasks/              # PRD 文件目录（执行时自动创建）
│   └── prd.json        # 你的任务定义
└── ...

# 基本用法
./scripts/ralph/ralph.sh [max_iterations]        # 默认：Amp
./scripts/ralph/ralph.sh --tool claude [iterations]  # 使用 Claude Code

# 简单项目
./scripts/ralph/ralph.sh --tool claude 10

# 复杂项目
./scripts/ralph/ralph.sh --tool claude 50

{
  "projectName": "Blog i18n Translation",
  "branchName": "ralph/i18n-translation",
  "userStories": [
    {
      "id": "US-001",
      "title": "Translate homepage metadata",
      "description": "Create content/docs/meta.en.json with English translations for all navigation items",
      "acceptanceCriteria": [
        "meta.en.json file exists with valid JSON format",
        "All navigation titles are translated to English",
        "pnpm types:check passes"
      ],
      "priority": 1,
      "passes": false,
      "dependsOn": [],
      "notes": "Reference the existing meta.json structure"
    },
    {
      "id": "US-002",
      "title": "Translate blog post hello-world",
      "description": "Create content/blog/hello-world.en.mdx, translated from Chinese to English",
      "acceptanceCriteria": [
        "hello-world.en.mdx file exists",
        "All QuoteCard components have defaultLang='en'",
        "Internal links use /en/ prefix",
        "Code blocks remain untranslated",
        "pnpm types:check passes"
      ],
      "priority": 2,
      "passes": false,
      "dependsOn": ["US-001"],
      "notes": "Preserve MDX component props format"
    }
  ]
}

=== Iteration 1 (US-001) ===
- Discovered: typecheck command is `pnpm types:check`, not `pnpm typecheck`
- Discovered: meta.en.json needs to mirror exact structure of meta.json
- Pattern: fumadocs i18n uses `.en.` suffix convention

=== Iteration 2 (US-002) ===
- Discovered: QuoteCard requires both `quote` and `quoteZh` props
- Gotcha: internal links must use /en/ prefix for English pages
- Pattern: code blocks should never be translated

# AGENTS.md

## Codebase Conventions
- Use fumadocs for documentation framework
- MDX files use custom components: QuoteCard, BlogImage, GlossaryCard
- i18n files use `.en.mdx` suffix

## Gotchas
- Always run `pnpm types:check` after modifying MDX files
- QuoteCard: set `defaultLang='en'` in English translations

# 在 Claude Code 或 Amp 中
/prd I want to add i18n support to the blog, translating all Chinese content to English

/ralph    # 转换 PRD 为 prd.json

// ❌ 太大：一次迭代完不成
{
  "id": "US-001",
  "title": "Build complete user authentication system",
  "description": "Implement registration, login, forgot password, OAuth, permission management..."
}

// ❌ 太小：没有独立价值
{
  "id": "US-001",
  "title": "Create email field on User table",
  "description": "Add email field to User model"
}

// ✅ 刚好：一次迭代能完成，有独立价值
{
  "id": "US-001",
  "title": "Implement email/password login",
  "description": "Create login API and login page with email/password authentication",
  "acceptanceCriteria": [
    "POST /api/auth/login accepts email + password",
    "Returns JWT token",
    "Login page form submits successfully",
    "All tests pass"
  ]
}

// ❌ 模糊的标准
"acceptanceCriteria": [
  "Code quality is good",
  "Performance is decent",
  "User experience is smooth"
]

// ✅ 可验证的标准
"acceptanceCriteria": [
  "pnpm types:check passes",
  "pnpm test passes",
  "API response time < 200ms",
  "File src/auth/login.ts exists and exports loginHandler function"
]

{
  "userStories": [
    {
      "id": "US-001",
      "title": "Create database schema",
      "dependsOn": []
    },
    {
      "id": "US-002",
      "title": "Implement user registration API",
      "dependsOn": ["US-001"]
    },
    {
      "id": "US-003",
      "title": "Implement login page",
      "dependsOn": ["US-002"]
    }
  ]
}

{
  "notes": "Project uses fumadocs framework, i18n files follow .en.mdx suffix naming. Reference content/docs/notes/speckit/concept.en.mdx for translation style."
}

# 使用 Claude Code，默认 10 次迭代
./scripts/ralph/ralph.sh --tool claude

# 指定迭代次数
./scripts/ralph/ralph.sh --tool claude 30

# 使用 Amp（默认）
./scripts/ralph/ralph.sh 20

=== Ralph Loop - Iteration 1 ===
Branch: ralph/i18n-translation
Selected story: US-001 - Translate homepage metadata
Spawning fresh Claude instance...

[Claude Code executing...]

Quality check: pnpm types:check ... PASSED
Committing: feat: [US-001] - Translate homepage metadata
Updating prd.json: US-001 passes: true
Appending to progress.txt

=== Ralph Loop - Iteration 2 ===
Selected story: US-002 - Translate blog post hello-world
Spawning fresh Claude instance...

All stories completed!
<promise>COMPLETE</promise>

# 查看每个 story 的完成状态
cat tasks/prd.json | jq '.userStories[] | {id, title, passes}'

# 查看经验日志
cat progress.txt

# 查看最近的 git 提交
git log --oneline -10

# 实时跟踪 Ralph 输出
tail -f progress.txt

## Quality Commands

After implementing each story, run these checks IN ORDER:

1. `pnpm types:check` — TypeScript type checking
2. `pnpm test` — Unit tests
3. `pnpm build` — Full build verification

If any check fails:
- DO NOT commit
- Fix the issue
- Re-run all checks
- Only commit when all checks pass

## Project-Specific Commands
- Typecheck: `pnpm types:check` (not `tsc` or `pnpm typecheck`)
- Test: `pnpm vitest run`
- Build: `pnpm build`
- Lint: `pnpm lint`

## Code Conventions
- Use TypeScript strict mode
- Prefer named exports over default exports
- Use fumadocs components for MDX content
- Follow existing file naming patterns (kebab-case)

## Known Gotchas
- MDX files: always import components at the top
- i18n: English files use `.en.mdx` suffix
- Links: English pages must use `/en/` prefix
- QuoteCard: set `defaultLang` to match the file language

## When Stuck
If you cannot complete a story after 3 attempts within the same iteration:
1. Document what's blocking in progress.txt
2. Move to the next story if possible
3. Do NOT modify files unrelated to the current story

scripts/ralph/
├── prd.json          # 16 个 user story，带验收标准
└── progress.txt      # 经验日志，每个 story 完成后更新

安装 → 编写 PRD → 配置质量门禁 → 运行循环 → 检查结果