ralph-tui-prd

Ralph TUI PRD 生成器

创建针对通过 ralph-tui 执行 AI Agent 任务进行优化的详细产品需求文档。

---

任务说明

1. 接收用户的功能描述
2. 提出 3-5 个必要的澄清问题（提供字母选项）——每次只问一组
3. 始终询问质量门禁（必须通过哪些命令）
4. 每次收到回答后，视需要提出后续问题（自适应探索）
5. 收集到足够的上下文后，生成结构化 PRD
6. 将 PRD 包在 [PRD]...[/PRD] 标记中输出，以便 TUI 解析

**重要：**不要开始实现。只创建 PRD。

---

步骤 1：澄清问题（迭代进行）

每次只问一组问题。每个回答都应为下一组问题提供参考。重点关注：

• **问题/目标：**这能解决什么问题？
• **核心功能：**关键操作有哪些？
• **范围/边界：**哪些事情不应包含在内？
• **成功标准：**如何判断任务已完成？
• **集成：**它如何与现有功能配合？
• **质量门禁：**每个故事必须通过哪些命令？（必需）

问题格式如下：

1. What is the primary goal of this feature?
   A. Improve user onboarding experience
   B. Increase user retention
   C. Reduce support burden
   D. Other: [please specify]

2. Who is the target user?
   A. New users only
   B. Existing users only
   C. All users
   D. Admin users only

这样用户就可以用“1A, 2C”快速回答。

如果你在交互会话中使用 Claude Code，可以改用 AskUserQuestion 工具提出这些问题——问题和选项相同，仍然每次只问一组。如果此技能由 ralph-tui create-prd 驱动，Agent 会以非交互方式运行，没有人能回答工具调用，因此请按上述方式用纯文本提供带字母标记的选项。

质量门禁问题（必需）

始终询问质量门禁——它们因项目而异：

What quality commands must pass for each user story?
   A. pnpm typecheck && pnpm lint
   B. npm run typecheck && npm run lint
   C. bun run typecheck && bun run lint
   D. Other: [specify your commands]

For UI stories, should we include browser verification?
   A. Yes, use dev-browser skill to verify visually
   B. No, automated tests are sufficient

自适应提问

每次收到回答后，判断是否需要：

• 提出后续问题（如果回答揭示了复杂性）
• 询问新的方面（如果当前方面已明确）
• 生成 PRD（如果上下文已充足）

通常需要进行 2-4 轮提问。

---

步骤 2：PRD 结构

PRD 应包含以下部分：

1. 简介/概述

简要描述该功能及其所解决的问题。

2. 目标

具体、可衡量的目标（项目符号列表）。

3. 质量门禁

**重要：**列出每个用户故事都必须通过的命令。

## Quality Gates

These commands must pass for every user story:
- `pnpm typecheck` - Type checking
- `pnpm lint` - Linting

For UI stories, also include:
- Verify in browser using dev-browser skill

转换工具（ralph-tui-create-json、ralph-tui-create-beads）会提取此部分，并将其附加到每个故事的验收标准中。

4. 用户故事

每个故事都需要：

• **标题：**简短的描述性名称
• 描述：“作为一名[用户]，我希望[功能]，以便[收益]”
• **验收标准：**可验证的检查清单，用于界定“完成”的含义

每个故事都应足够小，以便在一次专注的 AI Agent 会话中完成。

格式：

### US-001: [Title]
**Description:** As a [user], I want [feature] so that [benefit].

**Acceptance Criteria:**
- [ ] Specific verifiable criterion
- [ ] Another criterion

**注意：**不要在单个故事的验收标准中包含质量门禁命令——这些命令只在“质量门禁”部分定义，并会在转换过程中自动应用。

重要：

• 验收标准必须可验证，不能含糊
• “运行正常”是不合适的
• “删除前显示确认对话框”是合适的
• 每个故事都应可独立完成

5. 功能需求

以编号列表列出具体功能：

• “FR-1：系统必须允许用户……”
• “FR-2：当用户点击 X 时，系统必须……”

表述必须明确、无歧义。

6. 非目标（范围之外）

说明此功能不会包含哪些内容。这对控制范围至关重要。

7. 技术考量（可选）

• 已知限制或依赖项
• 与现有系统的集成点
• 性能要求

8. 成功指标

如何衡量成功？

9. 待解决问题

仍待解答的问题或需要澄清的方面。

---

面向 AI Agent 编写

PRD 将通过 ralph-tui 交由 AI 编码 Agent 执行。因此：

• 表述要明确、无歧义
• 用户故事应足够小（可在一次会话中完成）
• 验收标准应尽可能可由机器验证
• 如果知道具体文件路径，请写明
• 引用项目中现有的代码模式

---

输出格式

重要： 请用标记包裹最终 PRD，以便 TUI 解析：

[PRD]
# PRD: Feature Name

## Overview
...

## Quality Gates
...

## User Stories
...
[/PRD]

文件命名： TUI 会将文件保存到 ./tasks/prd-[feature-name].md

---

对话流程示例

用户： 为 TUI 添加深色模式，并创建一份 PRD

助手： 我来帮你创建一份关于深色模式的 PRD。先问几个问题：

1. 主要目标是什么？ A. 减轻长时间使用时的眼睛疲劳 B. 与系统主题偏好一致 C. 提供视觉自定义选项 D. 其他

2. 设置是否应该持久保存？ A. 是，保存到配置文件 B. 否，仅在当前会话生效 C. 跟随系统偏好

用户： 1A，2A

助手： 好的。再问几个问题：

3. 哪些组件需要支持深色模式？ A. 所有 TUI 组件 B. 仅主执行视图 C. 主视图和设置 D. 其他

4. 每个故事都必须通过哪些质量检查命令？ A. pnpm typecheck && pnpm lint B. npm run typecheck && npm run lint C. bun run typecheck D. 其他：[请指定]

5. 对于 UI 故事，是否需要进行浏览器验证？ A. 是，使用 dev-browser skill B. 否，自动化测试已足够

用户： 3A，4A，5A

助手： 很好，生成 PRD 所需的信息已经足够。

[PRD]

PRD：Ralph TUI 深色模式

概述

为 ralph-tui 添加深色模式支持，减轻长时间编排会话时的眼睛疲劳。此功能将应用于所有 TUI 组件，并将用户偏好保存到配置文件中。

目标

• 在低光照环境中提供舒适的观看体验
• 跨会话保存主题偏好
• 为所有 TUI 组件应用统一的样式

质量门槛

每个用户故事都必须通过以下命令：

• pnpm typecheck - 类型检查
• pnpm lint - 代码检查

对于 UI 故事，还需：

• 使用 dev-browser skill 在浏览器中验证

用户故事

US-001：添加主题配置

描述： 作为用户，我希望设置偏好的主题（浅色/深色），使其能在不同会话间保持不变。

验收标准：

• 在 .ralph-tui.yaml schema 中添加 theme 字段
• 支持以下值："light"、"dark"、"system"
• 默认值设为 "light"，以保持向后兼容

US-002：创建深色主题调色板

描述： 作为用户，我希望深色主题采用柔和的对比度，减少眼睛疲劳。

验收标准：

• 定义以灰色调为主的深色调色板（而非纯黑色）
• 确保对比度足够（WCAG AA）
• 颜色适用于所有 UI 状态（选中、悬停、禁用）

US-003：将主题应用于 TUI 组件

描述： 作为用户，我希望所有 TUI 组件都遵循我的主题偏好。

验收标准：

• 标题组件使用主题颜色
• 任务列表使用主题颜色
• 详情面板使用主题颜色
• 进度条使用主题颜色
• 对话框使用主题颜色

US-004：在设置中添加主题切换功能

描述： 作为用户，我希望能在 TUI 设置中切换主题。

验收标准：

• 设置视图中显示主题选项
• 更改立即生效，无需重启
• 更改保存到配置文件

功能需求

• FR-1：必须能从 .ralph-tui.yaml 中读取主题设置
• FR-2：TUI 启动时必须应用主题
• FR-3：在设置中更改主题后，必须立即生效
• FR-4：所有文本在两种主题下都必须清晰易读

非目标

• 自动检测系统主题（未来增强项）
• 浅色/深色之外的自定义配色方案
• 按组件单独覆盖主题

技术考量

• 如果可用，请使用现有的 OpenTUI 主题功能
• 考虑为 React 组件创建 ThemeContext
• 尽量减少主题变更时的重新渲染

成功指标

• 所有组件都能在深色模式下正确渲染
• 不存在无障碍对比度问题
• 主题可跨会话保留

待解决的问题

• 是否应在 v2 中自动检测系统主题偏好？ [/PRD]

---

检查清单

输出 PRD 前：

• 已通过带字母编号的选项提出澄清问题
• 已询问质量门禁（必需）
• 必要时已提出后续问题
• 已包含包含项目专属命令的质量门禁部分
• 用户故事规模较小，可独立完成
• 用户故事未包含质量门禁命令（这些命令应放在质量门禁部分）
• 功能需求已编号且表述明确
• 非目标部分明确界定了范围
• PRD 已用 [PRD]...[/PRD] 标记包裹