name: prd-converter description: “将PRDs转换为prd.json格式，供Aha Loop自主执行使用。在转换现有PRD为JSON格式时使用。触发于：转换prd，创建prd.json，aha-loop格式。”

Aha Loop PRD转换器

将现有PRDs转换为Aha Loop用于自主执行的prd.json格式。

工作内容

取一个PRD（markdown文件或文本）并将其转换为脚本/aha-loop目录中的prd.json。

输出格式（v2）

{
  "version": 2,
  "prdId": "[PRD-XXX from roadmap or PRD filename]",
  "project": "[Project Name]",
  "branchName": "aha-loop/[feature-name-kebab-case]",
  "description": "[Feature description from PRD title/intro]",
  "changeLog": [],
  "userStories": [
    {
      "id": "US-001",
      "title": "[Story title]",
      "description": "As a [user], I want [feature] so that [benefit]",
      "acceptanceCriteria": [
        "Criterion 1",
        "Criterion 2",
        "Typecheck passes"
      ],
      "priority": 1,
      "passes": false,
      "researchTopics": [
        "Question about technology or best practice",
        "Question about existing patterns"
      ],
      "researchCompleted": false,
      "learnings": "",
      "implementationNotes": "",
      "notes": ""
    }
  ]
}

新v2字段解释

字段	目的
`version`	模式版本（始终为2）
`prdId`	PRD标识符（例如，PRD-001），用于提交消息前缀
`changeLog`	执行期间计划修改的数组
`researchTopics`	在实现故事之前要调查的问题
`researchCompleted`	此故事的研究阶段是否完成
`learnings`	实施期间获得的知识（由Aha Loop填充）
`implementationNotes`	研究阶段的实施指导

故事大小：首要规则

每个故事必须在一个Aha Loop迭代（一个上下文窗口）内完成。

Aha Loop每个迭代启动一个新的AI实例，没有先前工作的记忆。如果故事太大，LLM在完成之前会用尽上下文并产生损坏的代码。

适当大小的故事：

添加数据库列和迁移
将UI组件添加到现有页面
用新逻辑更新服务器操作
向列表添加过滤器下拉菜单

太大（拆分这些）：

“构建整个仪表板” - 拆分为：模式、查询、UI组件、过滤器
“添加身份验证” - 拆分为：模式、中间件、登录UI、会话处理
“重构API” - 拆分为每个端点或模式一个故事

经验法则： 如果您无法用2-3句话描述更改，则太大。

故事排序：依赖优先

故事按优先级顺序执行。较早的故事不能依赖于较晚的故事。

正确顺序：

模式/数据库更改（迁移）
服务器操作/后端逻辑
使用后端的UI组件
聚合数据的仪表板/摘要视图

错误顺序：

UI组件（依赖于尚不存在的模式）
模式更改

接受标准：必须可验证

每个标准必须是执行引擎可以检查的东西，而不是模糊的。

好标准（可验证）：

“向任务表添加status列，默认’pending’”
“过滤器下拉菜单选项：全部、活跃、已完成”
“点击删除显示确认对话框”
“类型检查通过”
“测试通过”

坏标准（模糊）：

“工作正确”
“用户可以轻松做X”
“良好用户体验”
“处理边缘情况”

始终作为最终标准包括：

"类型检查通过"

对于有可测试逻辑的故事，也包括：

"测试通过"

对于更改UI的故事，也包括：

"使用开发浏览器技能在浏览器中验证"

前端故事在视觉验证之前不完整。Aha Loop将使用开发浏览器技能导航到页面，与UI交互，并确认更改工作。

转换规则

版本：始终设置"version": 2
prdId：从路线图PRD ID设置（例如，PRD-001）或从PRD文件名派生
每个用户故事成为一个JSON条目
ID：顺序（US-001, US-002等）
优先级：基于依赖顺序，然后文档顺序
所有故事：passes: false, researchCompleted: false, 空notes, learnings, implementationNotes
branchName：从功能名称派生，kebab-case，前缀aha-loop/
始终添加：每个故事的接受标准中包括"类型检查通过"
researchTopics：从PRD的研究主题部分提取，或生成如果故事涉及：
- 不熟悉的第三方库
- 多个实施方法
- 性能敏感代码
- 复杂集成
changeLog：初始化为空数组[]

拆分大型PRD

如果一个PRD有大型功能，拆分它们：

原始：

“添加用户通知系统”

拆分为：

US-001：向数据库添加通知表
US-002：创建发送通知的通知服务
US-003：向头部添加通知铃图标
US-004：创建通知下拉面板
US-005：添加标记为已读功能
US-006：添加通知偏好设置页面

每个是一个可以独立完成和验证的集中更改。

示例

输入PRD：

# 任务状态功能

添加用不同状态标记任务的能力。

## 要求
- 在任务列表中切换待处理/进行中/完成
- 按状态过滤列表
- 在每个任务上显示状态徽章
- 在数据库中持久化状态

输出prd.json（v2）：

{
  "version": 2,
  "prdId": "PRD-001",
  "project": "TaskApp",
  "branchName": "aha-loop/task-status",
  "description": "任务状态功能 - 用状态指示器跟踪任务进度",
  "changeLog": [],
  "userStories": [
    {
      "id": "US-001",
      "title": "向任务表添加状态字段",
      "description": "作为开发者，我需要在数据库中存储任务状态。",
      "acceptanceCriteria": [
        "添加状态列：'pending' | 'in_progress' | 'done'（默认'pending'）",
        "成功生成并运行迁移",
        "类型检查通过"
      ],
      "priority": 1,
      "passes": false,
      "researchTopics": [
        "此数据库中枚举列的最佳实践",
        "迁移回滚策略"
      ],
      "researchCompleted": false,
      "learnings": "",
      "implementationNotes": "",
      "notes": ""
    },
    {
      "id": "US-002",
      "title": "在任务卡上显示状态徽章",
      "description": "作为用户，我想一眼看到任务状态。",
      "acceptanceCriteria": [
        "每个任务卡显示彩色状态徽章",
        "徽章颜色：灰色=待处理，蓝色=进行中，绿色=完成",
        "类型检查通过",
        "使用开发浏览器技能在浏览器中验证"
      ],
      "priority": 2,
      "passes": false,
      "researchTopics": [
        "代码库中现有的徽章组件",
        "状态指示器的可访问颜色方案"
      ],
      "researchCompleted": false,
      "learnings": "",
      "implementationNotes": "",
      "notes": ""
    },
    {
      "id": "US-003",
      "title": "向任务列表行添加状态切换",
      "description": "作为用户，我想直接从列表更改任务状态。",
      "acceptanceCriteria": [
        "每行有状态下拉菜单或切换",
        "更改状态立即保存",
        "UI更新无需页面刷新",
        "类型检查通过",
        "使用开发浏览器技能在浏览器中验证"
      ],
      "priority": 3,
      "passes": false,
      "researchTopics": [],
      "researchCompleted": false,
      "learnings": "",
      "implementationNotes": "",
      "notes": ""
    },
    {
      "id": "US-004",
      "title": "按状态过滤任务",
      "description": "作为用户，我想过滤列表以仅查看特定状态。",
      "acceptanceCriteria": [
        "过滤器下拉菜单：全部 | 待处理 | 进行中 | 完成",
        "过滤器在URL参数中持久化",
        "类型检查通过",
        "使用开发浏览器技能在浏览器中验证"
      ],
      "priority": 4,
      "passes": false,
      "researchTopics": [
        "此代码库中URL状态管理模式"
      ],
      "researchCompleted": false,
      "learnings": "",
      "implementationNotes": "",
      "notes": ""
    }
  ]
}

归档先前运行

在编写新prd.json之前，检查是否存在来自不同功能的现有一个：

如果存在，读取当前prd.json
检查branchName是否与新功能的分支名称不同
如果不同且progress.txt有超出标题的内容：
- 创建归档文件夹：archive/YYYY-MM-DD-feature-name/
- 将当前prd.json和progress.txt复制到归档
- 用新标题重置progress.txt

aha-loop.sh脚本在运行时自动处理此操作，但如果您在运行之间手动更新prd.json，请先归档。

保存前检查清单

在写入prd.json之前，验证：

[ ] 版本设置为2
[ ] prdId设置（从路线图或PRD文件名，例如，PRD-001）
[ ] 先前运行已归档（如果prd.json存在且branchName不同，请先归档）
[ ] 每个故事在一个迭代内可完成（足够小）
[ ] 故事按依赖顺序排序（从模式到后端到UI）
[ ] 每个故事有"类型检查通过"作为标准
[ ] UI故事有"使用开发浏览器技能在浏览器中验证"作为标准
[ ] 接受标准可验证（不模糊）
[ ] 没有故事依赖于较晚的故事
[ ] 复杂故事有相关researchTopics
[ ] 所有故事初始researchCompleted: false
[ ] changeLog初始化为空数组

研究主题指南

何时添加研究主题：

故事使用不熟悉的库 → “如何使用[库]进行[任务]”
可能有多种方法 → “比较[方法A]与[方法B]”
性能重要 → “[方法]的性能影响”
现有模式未知 → “代码库中[功能]的现有模式”

何时跳过研究主题：

简单CRUD操作
从现有类似代码复制粘贴
项目中已使用的良好理解模式
故事直接基于先前故事的学习