escrever-prd

编写 PRD

创建和编辑功能 PRD。PRD 是一个产品思考单元：一组可以一起说明其决策的行为和业务规则。它是面向人的文档，是产品意图的真实来源。它全面描述功能的行为和业务规则；AI 会按需查阅其中的原因，并根据 SPEC（由 sdd-especificar 从 PRD 派生）进行实现。实现所需的技术背景来自 TRD（实施时一并加载）。必要时，参考字段用于关联 PRD 之间以及 PRD 与外部资源。

此 skill 既涵盖创建 PRD，也涵盖编辑尚未完成的现有 PRD——status: concluido 的 PRD 不可变，不应通过此 skill 编辑。

PRD 在流程中的作用

PRD 承担两个作用：

1. 功能规格——独立描述行为和业务规则的文档，用于实现功能
2. 状态控制——通过 status 字段和 depends_on 关系图，作为功能生命周期的真实来源

由此产生的原则：

• concluido 状态下不可变——状态达到 concluido 后，PRD 会冻结并成为历史记录。之后如需变更行为，应新建 PRD，而不是编辑已完成的 PRD
• 通过 depends_on 渐进式披露——显式声明 PRD 之间的依赖关系；只有当实现上下文需要时，Agent 才会读取依赖的 PRD
• 职责分离——PRD 涵盖行为和业务规则；TRD 和 ADR 涵盖技术限制、技术栈和架构决策。PRD 引用技术文档，但不指导、限定范围或跟踪技术实现——PRD 的形式由产品决定，而非由执行决定
• 稳定 ID——US 和 Milestone 会分配 ID（US01、Milestone 1……），分配后不得更改，因为后续文档（规划、任务）会通过这些 ID 进行引用

输入

用户提供想要构建内容的描述，其中可能包括：

• 问题或机会描述
• 解决方案构想
• 技术背景
• 已知限制

$ARGUMENTS — 如果提供，将其用作功能的初始描述。

执行流程

1. 识别模式

首先，识别请求属于创建还是编辑：

• 创建——用户描述新功能，或未引用任何现有 PRD
• 编辑——用户引用特定 PRD（按编号、名称或文件），或要求调整、完善现有内容

编辑模式下：

1. 在 ./docs/prds/ 中读取所引用的 PRD
2. 检查 status——如果为 concluido，则停止并告知用户：已完成的 PRD 不可变，行为变更应新建 PRD
3. 对于状态为 rascunho、pronto 或 em-progresso 的 PRD，继续编辑，并保留已分配的 prd_number、US ID 和 Milestone ID

2. 范围与阻塞性缺口分析

生成前，快速进行两项检查：

2a. 检测多个功能

判断标准不是是否彼此独立，而是是否能自成一体。PRD 涵盖一个功能的条件是：各部分都能自成一体，并为用户交付可观察到的成果。如果输入中的不同部分分别满足这一标准，那么它们就是不同的功能——即使彼此依赖。依赖关系很正常，应记录在 depends_on 中（一个串联的功能仍然是独立功能）；它不是阻止拆分的理由。

**合理性检查：**如果某个功能需要许多产品里程碑（实际上超过约 6 个），它很可能包含多个功能——请重新评估拆分方式。里程碑少并不意味着必须拆分：小型功能可以只有 1 或 2 个合理的里程碑。

如果检测到多个功能，在生成前提出具体的拆分方案：

Detectei 3 features no input. Sugiro criar:
  PRD-A: [nome da feature A]
  PRD-B: [nome da feature B]
  PRD-C: [nome da feature C]

Começamos pelo PRD-A?

等待确认或调整拆分方案。在内部记录待处理 PRD 列表。

2b. 阻塞性缺口

检查是否存在某些信息缺失，导致草稿无法使用——即无法合理推断的信息。真正的阻塞性缺口示例：无法确定功能所属的领域，也无法确定其所属的系统。

如果存在阻塞性缺口：提出一个封闭式问题（尽可能提供选项），不要进行访谈。其他任何缺口——均进行推断并在草稿中标注。

如果不存在：立即生成。

3. 生成带有假设的草稿

立即生成完整 PRD，不等待更多信息。未提供的内容应进行推断并内联标注。

假设格式：

- Token expirado → redirecionar para login *(premissa — confirme ou corrija)*

对于任何推断出的内容，都使用 *(假设 — 请确认或更正)*，包括规则、边缘情况、验收标准、负向范围和里程碑。用户审阅的是具体文本，而不是回答抽象问题。

生成：

1. 阅读 references/template-prd.md 中的模板
2. 填写所有章节，生成完整 PRD
3. 推断未提供的规则和边缘情况，并将每一项标记为假设
4. 将草稿交给用户进行针对性审阅 生成规则：

• 使用清晰、客观的语言，避免不必要的行话
• 填写所有章节——将推断内容标记为前提；只有用户明确留空的内容才使用「待定」
• PRD 应在行为和业务规则方面自包含，而非技术背景。技术栈、架构和规范以实施时一并加载的 TRD 为准；相关时，「背景」章节只需提供指向 TRD 的引用，不要重复技术栈
• 每项功能都必须是带有连续 ID 的用户故事（US）（US01、US02……）
• 每个 US 必须包含：采用「作为[角色]，我希望[操作]，以便[收益]」格式编写的用户故事、Rules（业务规则和预期行为）以及 Edge cases（异常情况及预期行为）
• 每个 US 至少包含一条 Rule 和一个 Edge case；如果未提供，则推断最可能的情况并标记为前提
• Edge cases 遵循以下格式：「[异常情况] → [预期行为]」
• 验收标准（§5a）涵盖该功能特有的功能性和非功能性标准——只有在有业务理由时，才纳入响应时间、可用性和容量（记录阈值及其原因）。项目级全局 NFR（整体 p95、正常运行时间、加密）归入 TRD，不归入 PRD。成功指标（基线→目标）归入 §5b
• 不接受「应当运行良好」或「性能良好」等模糊标准——应改写为客观可验证的标准；如果数据不足，则标记为前提
• 里程碑是产品节点：由一组连贯的功能组成，为用户带来实际价值——它应当是可以宣布的成果，而不是执行过程中的一个阶段。每个里程碑须明确涵盖哪些 US（按 ID 列出）、说明为何它是一个里程碑（进行自我评估：如果理由牵强，它很可能是伪装成里程碑的任务，或是硬塞在一起的两个里程碑），并提供验收清单（从 §5a 中筛选该里程碑所涵盖 US 的标准，由验收人于实施后逐项勾选）。里程碑没有最低数量；上限约为 6 个是 §2a 的合理性信号。不要在里程碑中详细说明技术任务或执行顺序——拆分方式（切片、任务、顺序）由 sdd-especificar 负责
• 仅当规则分支无法通过文字清楚说明时，才纳入业务流程（§4，即旅程/流程图，其中决策点体现规则）。PRD 不包含技术拓扑（组件/服务、数据模型）——这些内容归入 TRD、ADR，或者在属于难以撤销的局部决策时，归入切片的 PLAN
• 「不在范围内」章节为必填项——如果未提供，则推断明显排除的项目并标记为前提
• 「决策记录」记录产品决策和重要的业务前提。架构/技术决策不应纳入其中——应作为 ADR 处理
• 如果输入包含持久性架构决策（数据库选择、身份验证策略、架构模式、基础库），不要将其纳入产品决策：应指出这属于 ADR，并建议通过 escrever-trd 的 Decision 模式记录到 docs/adrs/。PRD 可在 §8 引用该 ADR
• 「参考资料」章节列出背景中提及的文档、问题、相关 PRD、API、设计或外部资源链接
• frontmatter 中的 references 字段必须以列表格式包含与「参考资料」章节相同的链接
• US ID（US01、US02……）和里程碑 ID（Milestone 1、2……）保持稳定——分配后不得更改，因为后续产物（规划、任务）会引用这些 ID
• 创建模式下，保存时的初始 status 始终为 rascunho。编辑模式下，保留 PRD 当前的 status——pronto、em-progresso 和 concluido 之间的转换由后续规划和执行技能完成

4. 依赖关系映射

在将 PRD 提交最终审核之前：

1. 列出 ./docs/prds/ 中现有的文件（或用户指定路径下的文件）
2. 对每个现有 PRD，评估当前功能是否依赖其中已定义的内容——依赖是指此功能的实现预设了另一个 PRD 中描述的行为、实体、接口或规则
3. 在 frontmatter 中填写 depends_on 字段，列出已识别依赖项的 prd_number（例如：depends_on: ["001", "003"]）
4. 在“决策记录”中记录判定每项依赖所采用的标准，避免今后重新推导判断过程

规则：

• 依赖必须真实且具体——不要列出所有“相关”或“属于同一领域”的 PRD
• 如果没有依赖，保留 depends_on: []
• 按需加载依赖的 PRD（渐进式披露）——不要将其内容纳入当前 PRD

5. 针对性完善

根据用户的要求修订草稿——修正前提、调整范围、完善规则。重复此过程，直至获得批准。

如果审核导致功能范围发生变化，保存前重新评估 depends_on——功能职责的增减可能导致依赖项增加或减少。

6. 保存文件

创建模式下，保存新的 PRD：

1. 确定下一个编号：列出 ./docs/prds/ 中现有的文件，找出已使用的最大编号（格式为 NNN）。下一个 PRD 使用紧接其后的序号。如果不存在任何 PRD，则从 001 开始。
2. 命名文件：NNN-[nome-em-kebab-case].md（例如：003-autenticacao-oauth.md）
3. 默认位置：./docs/prds/
4. 如果用户指定了其他路径，则使用指定路径
5. 如果目录不存在，则创建该目录
6. 在 frontmatter 中填写 prd_number 字段，使用分配的编号（例如：003）

编辑模式下，覆盖原文件，同时保留 prd_number、文件名、当前 status 以及已分配的 US 和 Milestone ID。新增 US 使用下一个可用的连续 ID。

7. 多 PRD 连续处理

保存后，检查步骤 2a 中是否提出了拆分，且仍有待处理的 PRD。

如果有：

PRD-A salvo. Continua com PRD-B: [nome da feature B]?

确认后，开始处理下一个 PRD——利用前一个 PRD 中的决策作为上下文，以便做出更准确的推断（相同技术栈、相同系统、相同检测到的模式）。

重复此过程，直至拆分中的所有 PRD 均已保存，或用户中止。