Prd

核心用法

PRD技能是一套面向AI编码代理的产品需求文档生成框架，核心目标是将复杂功能拆解为可在单个上下文窗口内完成的独立用户故事，实现无人值守的自动化开发循环。

工作流程：
1. 创建Markdown格式PRD文档（tasks/prd-[feature].md）
2. 转换为机器可读的prd.json格式
3. 运行代理循环：while :; do cat PROMPT.md | claude-code; done

prd.json结构包含：项目名称、分支名、描述、以及用户故事数组。每个故事必须包含唯一ID、标题、用户故事描述（As a... I want... so that...）、可验证的验收标准、执行优先级、完成状态和运行备注。

显著优点

极致的任务原子化：强制每个故事在单一上下文窗口完成，避免代理"失忆"导致的重复工作或错误累积。

严格的依赖排序：要求按"数据库模式→后端逻辑→UI组件"的顺序排列，防止因前置依赖未完成而导致的阻塞。

可验证的验收标准：明确禁止模糊描述（如"Works correctly"），强制使用可自动检查的断言（如"Typecheck passes"、"Add status column with default 'pending'"）。

无缝的无人值守执行：通过prd.json的状态标记和progress.txt的追加日志，实现跨会话的持续执行和知识传递。

多代理兼容：支持Claude Code、OpenCode等主流AI编码工具，提供对应的命令模板。

潜在缺点与局限性

前置知识门槛：要求使用者熟悉用户故事格式、验收标准编写规范，以及Git工作流（包括worktree策略）。

过度拆分风险：强制原子化可能导致故事数量膨胀，增加文档维护成本，且难以把握"合适"的粒度边界。

技术栈假设：示例 heavily偏向全栈Web开发（数据库迁移、TypeScript类型检查），对其他领域（如移动端原生开发、嵌入式、数据科学）的适配性未明确说明。

质量检查盲区：虽然强调"Typecheck passes"，但未涵盖运行时测试、集成测试、性能基准等更全面的验证维度。

安全风险未评估：--dangerously-skip-permissions标志提示存在权限绕过的安全隐患，但文档未深入讨论。

适合人群

• AI原生开发者：希望最大化利用Claude Code等工具的自主能力，减少人工干预
• 快速原型团队：需要高频迭代、快速验证产品假设的初创团队
• 标准化流程追求者：苦于需求文档与代码实现脱节，希望建立可执行的需求规范
• 多项目并行管理者：通过progress.txt和状态标记同时追踪多个功能的开发进度

常规风险

无限循环风险：while :; do循环若无正确终止条件（所有story的passes: true），可能消耗大量API token。必须确保PRD完整性检查清单被执行。

状态同步失效：若代理异常退出或手动干预，prd.json的passes标记可能与实际代码状态不一致，需人工校验。

权限与代码安全：--dangerously-skip-permissions模式跳过所有确认提示，可能导致意外删除、错误推送或敏感信息泄露。建议在隔离的worktree或容器中运行。

核心用法

prd 是一款面向 AI 编码 Agent 的 PRD（Product Requirements Document）管理 Skill，核心目标是将复杂功能拆解为可在单上下文窗口内完成的独立用户故事，驱动自主化开发循环。

典型工作流：
1. 创建 PRD：以 Markdown 格式编写 tasks/prd-[feature-name].md，包含用户故事、验收标准和优先级
2. 转换格式：通过 AI Agent 将 Markdown 转换为结构化的 prd.json（标准含 project、branchName、userStories 等字段）
3. 执行循环：运行无人值守的 Agentic Loop（如 while :; do cat PROMPT.md | claude-code; done），Agent 自动读取 prd.json → 选择最高优先级未完成任务 → 实现功能 → 运行质量检查 → 标记完成 → 追加进度到 progress.txt

用户故事设计原则：

• 单一上下文原则：每个故事必须能在一次 Agent 会话中完成（如"添加数据库列+迁移"而非"构建整个仪表盘"）
• 依赖顺序：按 Schema → Backend → UI 排序，前置任务不依赖后置任务
• 可验证标准：每条验收准则必须可客观验证（如"Typecheck passes"而非"Works correctly"）

---

显著优点

1. 降低认知负担
将复杂功能拆解为原子化任务，开发者只需审核 PRD 结构，无需逐行监督代码实现，特别适合大规模功能拆分。

2. 标准化 Agent 协作
统一的 prd.json 格式使 Claude Code、OpenCode 等不同 Agent 工具都能理解任务状态，实现工具无关的协作协议。

3. 支持人机协作
提供 Git Worktree 策略实现隔离开发环境，允许人工介入审核后再推进后续任务，平衡自动化与可控性。

4. 进度可追溯
progress.txt 的追加式记录和 Codebase Patterns 机制，使跨会话的上下文积累成为可能，避免"每轮从零开始"的上下文丢失问题。

5. 社区背书
基于 Geoffrey Huntley 提出的 Ralph Wiggum pattern，该模式已在 AI 编程社区获得验证，文档成熟度较高。

---

潜在缺点与局限性

1. 仅适用于特定技术栈
示例重度依赖 Git 工作流、TypeScript/Node.js 生态（typecheck、lint 等质量检查），非 TS/JS 项目需大量自定义验收标准。

2. 上下文窗口限制的现实约束
"单上下文完成"的理想假设在实际中常遇挑战：遗留代码理解、跨文件重构、第三方库异常处理等场景往往超出上下文容量。

3. 缺乏动态调整机制
prd.json 一旦生成，执行过程中难以根据实现发现自动拆分或合并故事，遇到阻塞时容易陷入"硬编码计划"困境。

4. 质量检查过于简化
默认仅建议 typecheck/lint/test，未涵盖集成测试、E2E 测试、性能基准等，可能产生"单元测试全绿但功能不可用"的假阳性。

5. 安全风险示例争议
文档中包含 --dangerously-skip-permissions 的示例代码，虽标注为文档用途，但仍存在被误用于生产环境的风险。

---

适合人群

• 独立开发者/技术创始人：需快速推进 MVP 功能，愿意用自动化换取速度
• AI 编程工具重度用户：已熟练使用 Claude Code、OpenCode 等工具，寻求标准化工作流
• 全栈 TS/JS 开发者：技术栈与示例高度契合，可直接套用模板
• 探索 Agentic Workflow 的团队：希望实验"AI 自主开发"但需要结构化控制机制

不适合：

• 强合规要求的金融/医疗行业（需完整审计链）
• 大型团队协作项目（缺乏角色分工和冲突解决机制）
• 非 Git 工作流或强类型语言项目

---

常规风险

执行风险： Agent 可能误解验收标准，产生"形式达标但实质错误"的实现（如添加了字段但未正确关联业务逻辑）。建议保留关键节点的人工审核。

数据安全风险： prd.json 和 progress.txt 可能包含业务敏感信息（数据库结构、API 端点），需确保这些文件不被意外提交到公开仓库。

无限循环风险： 示例中的 while :; do ... done 循环若无正确停止条件，可能在遇到不可解问题时持续消耗 Token/成本。务必确保 Agent Prompt 中包含 <promise>COMPLETE</promise> 等明确停止信号。

分支污染风险： ralph/ 前缀的自动分支策略若与团队现有命名规范冲突，可能导致分支管理混乱。

权限提升误用： --dangerously-skip-permissions 等标志若被用于生产 CI/CD，可能绕过安全审查机制，需在团队内建立明确的使用规范。