productspec-authoring

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Authoring ProductSpec Files

编写ProductSpec文件

ProductSpec is a Markdown format for the product decision that comes before tickets, engineering plans, and code. One file per feature holds the committed intent.

This skill covers producing that file. Reading a finished spec and building against it is a different job, and the

productspec

skill covers it. This skill ends when the file validates.

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

本技能负责生成该文件。读取已完成的规范并基于其进行开发是另一项工作，由

productspec

技能负责。本技能的流程在文件验证通过后结束。

Always true

通用规则

Files use the extension
```
.product-spec.md
```
: YAML frontmatter between
```
---
```
markers, then
```
## Section
```
headings.

Six sections are mandatory, in order:

problem

hypothesis

product_summary

scope

acceptance_criteria

success_metrics

Headings match case- and separator-insensitively.
```
## Acceptance Criteria
```
and
```
## acceptance_criteria
```
are the same section. Title case is the convention.

Frontmatter requires

spec_format_version: "0.1"

title

artifact_type

(

hypothesis

prd

openspec_proposal

author

created_at

updated_at

. Optional:

spec_revision

linked_github_repo

applies_to

custom_sections

tool_metadata

```
acceptance_criteria
```
and
```
success_metrics
```
each carry a required fenced block. Prose alone fails validation. Structured scope, AI evals, and related artifacts are optional.
Structured items carry durable ids:
```
AC-<number>
```
,
```
SM-<number>
```
,
```
EVAL-<number>
```
. Other documents cite them.
AI evals live inside
```
## Acceptance Criteria
```
, never in a section of their own. Related artifacts live inside
```
## Related Artifacts
```
.
Validate any file with:
```
npm exec --yes --package @productspec/parser -- productspec validate <file>
```
(
```
--yes
```
suppresses npm's interactive install prompt, which hangs CI and non-interactive agents).
The full normative definition is SPEC.md in the ProductSpec repository: https://github.com/gokulrajaram/ProductSpec/blob/main/SPEC.md. When this skill and SPEC.md disagree, SPEC.md wins.

文件使用
```
.product-spec.md
```
扩展名：在
```
---
```
标记之间是YAML前置元数据，之后是
```
## Section
```
格式的标题。
必须包含六个固定顺序的章节：
```
problem
```
（问题）、
```
hypothesis
```
（假设）、
```
product_summary
```
（产品概述）、
```
scope
```
（范围）、
```
acceptance_criteria
```
（验收标准）、
```
success_metrics
```
（成功指标）。
标题的匹配不区分大小写和分隔符。
```
## Acceptance Criteria
```
和
```
## acceptance_criteria
```
视为同一章节。惯例是使用标题大小写格式。
前置元数据必须包含
```
spec_format_version: "0.1"
```
、
```
title
```
（标题）、
```
artifact_type
```
（工件类型，可选值：
```
hypothesis
```
|
```
prd
```
|
```
openspec_proposal
```
）、
```
author
```
（作者）、
```
created_at
```
（创建时间）、
```
updated_at
```
（更新时间）。可选字段：
```
spec_revision
```
（规范版本）、
```
linked_github_repo
```
（关联GitHub仓库）、
```
applies_to
```
（适用范围）、
```
custom_sections
```
（自定义章节）、
```
tool_metadata
```
（工具元数据）。
```
acceptance_criteria
```
和
```
success_metrics
```
章节各自必须包含一个代码块（fenced block）。仅使用普通文本会验证失败。结构化范围、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为准。

Pick the task, read one reference

选择任务，阅读对应参考文档

Task	Read
Write a new spec from scratch	references/authoring.md
Validate files and fix errors	references/validating.md
Convert an existing PRD or feature doc	references/converting.md
Record drift, revisions, and outcomes	references/decision-trace.md

Read only the reference the task needs.

任务	参考文档
从零开始编写新规范	references/authoring.md
验证文件并修复错误	references/validating.md
转换现有PRD或功能文档	references/converting.md
记录偏差、版本和结果	references/decision-trace.md

仅阅读当前任务所需的参考文档。

Ground rules

基本原则

Never renumber a durable id.
```
AC-2
```
means the same criterion tomorrow as it does today, because a ticket, an engineering spec, or another agent may cite it. Add new ids at the end.
A success metric needs a target and a window, and the block is required. When the number depends on a baseline that only exists after launch, write
```
target: tbd
```
with
```
target_status: provisional
```
and a named
```
target_owner
```
. Never invent a number to clear the validator.
Preserve the author's Markdown inside sections. Tables, lists, and links survive the format. Do not flatten them.
Write Scope items as complete sentences or imperative statements. Avoid terse tags like
```
search
```
or
```
storage
```
.
```
spec_revision
```
increments only when product intent materially changes, never for typo or formatting edits.

切勿重新编号持久ID。
```
AC-2
```
在未来指代的验收标准应与现在一致，因为工单、工程规范或其他Agent可能会引用它。新增ID需添加在末尾。
成功指标需要包含目标值和时间窗口，且代码块为必填项。如果目标值依赖于上线后的基准数据，请填写
```
target: tbd
```
并标注
```
target_status: provisional
```
（临时）以及指定
```
target_owner
```
（目标负责人）。切勿为了通过验证而编造数值。
保留章节内作者编写的Markdown格式。表格、列表和链接应保留原样，不得扁平化处理。
范围条目需写成完整句子或祈使句。避免使用
```
search
```
（搜索）或
```
storage
```
（存储）这类简洁标签。
仅当产品意图发生实质性变化时才递增
```
spec_revision
```
，拼写错误或格式修改无需更新版本号。