Ralph 实践指南

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

帮我安装这个 skill：https://github.com/snarktank/ralph

# 基本用法
./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": "博客 i18n 翻译",
  "branchName": "ralph/i18n-translation",
  "userStories": [
    {
      "id": "US-001",
      "title": "翻译首页元数据",
      "description": "创建 content/docs/meta.en.json，包含所有导航项的英文翻译",
      "acceptanceCriteria": [
        "meta.en.json 文件存在且 JSON 格式正确",
        "所有导航标题都已翻译为英文",
        "pnpm types:check 通过"
      ],
      "priority": 1,
      "passes": false,
      "dependsOn": [],
      "notes": "参考现有 meta.json 的结构"
    },
    {
      "id": "US-002",
      "title": "翻译博客文章 hello-world",
      "description": "创建 content/blog/hello-world.en.mdx，从中文翻译为英文",
      "acceptanceCriteria": [
        "hello-world.en.mdx 文件存在",
        "所有 QuoteCard 组件设置 defaultLang='en'",
        "内部链接使用 /en/ 前缀",
        "代码块保持不翻译",
        "pnpm types:check 通过"
      ],
      "priority": 2,
      "passes": false,
      "dependsOn": ["US-001"],
      "notes": "注意保留 MDX 组件的 props 格式"
    }
  ]
}

=== 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 我想为博客系统添加 i18n 支持，需要将所有中文内容翻译成英文

/ralph    # 将 PRD 转换为 prd.json

// ❌ 太大：一次迭代完不成
{
  "id": "US-001",
  "title": "构建完整的用户认证系统",
  "description": "实现注册、登录、忘记密码、OAuth、权限管理..."
}

// ❌ 太小：没有独立价值
{
  "id": "US-001",
  "title": "创建 User 表的 email 字段",
  "description": "在 User 模型中添加 email 字段"
}

// ✅ 合适：一次能完成，有独立价值
{
  "id": "US-001",
  "title": "实现邮箱密码登录",
  "description": "创建登录 API 和登录页面，支持邮箱密码验证",
  "acceptanceCriteria": [
    "POST /api/auth/login 接受 email + password",
    "返回 JWT token",
    "登录页面表单可提交",
    "所有测试通过"
  ]
}

// ❌ 模糊的标准
"acceptanceCriteria": [
  "代码质量好",
  "性能不错",
  "用户体验流畅"
]

// ✅ 可验证的标准
"acceptanceCriteria": [
  "pnpm types:check 通过",
  "pnpm test 通过",
  "API 响应时间 < 200ms",
  "文件 src/auth/login.ts 存在且导出 loginHandler 函数"
]

{
  "userStories": [
    {
      "id": "US-001",
      "title": "创建数据库 schema",
      "dependsOn": []
    },
    {
      "id": "US-002",
      "title": "实现用户注册 API",
      "dependsOn": ["US-001"]
    },
    {
      "id": "US-003",
      "title": "实现登录页面",
      "dependsOn": ["US-002"]
    }
  ]
}

{
  "notes": "项目使用 fumadocs 框架，i18n 文件命名规则是 .en.mdx 后缀。参考 content/docs/notes/speckit/concept.en.mdx 的翻译风格。"
}

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

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

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

Starting Ralph - Tool: claude - Max iterations: 35

===============================================================
  Ralph Iteration 1 of 35 (claude)
===============================================================
## US-001 Complete

**Summary of what was done:**
1. Created meta.en.json with all navigation items translated
2. Ran pnpm types:check — PASSED
3. Committed: feat: [US-001] - Translate homepage metadata

There are still **15 user stories with `passes: false`** remaining.
The next story is **US-002: 翻译博客文章 hello-world**.
Iteration 1 complete. Continuing...

===============================================================
  Ralph Iteration 2 of 35 (claude)
===============================================================

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

# 查看各 story 的完成状态（带图标，更直观）
cat tasks/prd.json | python3 -c "
import json,sys
for s in json.load(sys.stdin)['userStories']:
    print(f'{\"✅\" if s[\"passes\"] else \"⬜\"} {s[\"id\"]}: {s[\"title\"]}')"

# 或者用 jq 查看
cat tasks/prd.json | jq '.userStories[] | {id, title, passes}'

# 查看经验日志
cat progress.txt

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

# 实时查看 Ralph 的输出
tail -f progress.txt

# 完成后，查看相比主分支的全部改动
git diff main...ralph/your-branch-name --stat

# 中断后恢复，只需重新运行同样的命令
./scripts/ralph/ralph.sh --tool claude 35

## 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

## 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 → 配置质量门禁 → 执行循环 → 检查成果