productspec-authoring

编写 ProductSpec 文件

ProductSpec 是一种 Markdown 格式，用于记录编写工单、工程计划和代码之前的产品决策。每项功能对应一个文件，用来承载已确定的意图。

本技能介绍如何编写该文件。阅读已完成的规格并据此构建产品是另一项工作，由 productspec 技能负责。本技能在文件通过验证时结束。

始终适用

• 文件扩展名为 .product-spec.md：YAML frontmatter 位于 --- 标记之间，后接 ## Section 标题。
• 六个必需部分必须按顺序排列：problem、hypothesis、product_summary、scope、acceptance_criteria、success_metrics。
• 标题匹配时不区分大小写和分隔符。## Acceptance Criteria 与 ## acceptance_criteria 是同一个部分。惯例是使用标题式大小写。
• Frontmatter 必须包含 spec_format_version: "0.1"、title、artifact_type（hypothesis | prd | openspec_proposal）、author、created_at、updated_at。可选字段：spec_revision、linked_github_repo、applies_to、custom_sections、tool_metadata。
• acceptance_criteria 和 success_metrics 都必须包含一个必需的围栏代码块。仅有散文内容无法通过验证。结构化范围、AI 评估和相关产物均为可选。
• 结构化条目必须带有持久 ID：AC-<number>、SM-<number>、EVAL-<number>。其他文档会引用这些 ID。
• AI 评估必须放在 ## Acceptance Criteria 中，不得单独设为一个部分。相关产物必须放在 ## Related Artifacts 中。
• 使用以下命令验证任何文件：npm exec --yes --package @productspec/parser -- productspec validate <file>（--yes 会跳过 npm 的交互式安装提示，该提示会导致 CI 和非交互式 Agent 卡住）。
• 完整的规范性定义见 ProductSpec 仓库中的 SPEC.md：https://github.com/gokulrajaram/ProductSpec/blob/main/SPEC.md。当本技能与 SPEC.md 不一致时，以 SPEC.md 为准。

选择任务，阅读一份参考文档

任务	阅读
从头编写新的规格	references/authoring.md
验证文件并修复错误	references/validating.md
转换现有 PRD 或功能文档	references/converting.md
记录偏差、修订和结果	references/decision-trace.md

只阅读任务所需的参考文档。

基本规则

• 永远不要重新编号持久 ID。AC-2 今天和明天都代表同一条验收标准，因为工单、工程规格或其他 Agent 可能会引用它。新增 ID 时，从末尾接续。
• 成功指标必须包含目标和时间窗口，且必须提供代码块。如果数值取决于仅在上线后才会有的基线，请写入 target: tbd、target_status: provisional 和具名的 target_owner。切勿为了通过验证而编造数值。
• 保留作者在各部分中的 Markdown 内容。表格、列表和链接都应保留。不要将其压平成纯文本。
• Scope 条目应写成完整句子或祈使句。避免使用 search 或 storage 之类过于简略的标签。
• 只有在产品意图发生实质变化时才递增 spec_revision；拼写或格式修改不递增。