productspec

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ProductSpec Agent Skill

Product Specs are the product contract for consequential software work.

When a repo uses Agent Run files, treat them as the receipt for one agent execution against a pinned Product Spec revision.

Before planning, coding, testing, or changing scope, look for relevant

.product-spec.md

files in the repository. Common locations include:

```
specs/
```
```
product-specs/
```
```
docs/product-specs/
```
paths named in the task, issue, pull request, or engineering spec

If a relevant Product Spec exists, read it before acting.

Product Spec是重要软件工作的产品契约。

当仓库使用Agent Run文件时，将其视为针对固定Product Spec版本执行一次Agent操作的凭证。

在规划、编码、测试或变更范围之前，请在仓库中查找相关的

.product-spec.md

文件。常见位置包括：

```
specs/
```
```
product-specs/
```
```
docs/product-specs/
```
任务、问题、拉取请求或工程规格中指定的路径

如果存在相关的Product Spec，请先阅读再开展工作。

How To Use A Product Spec

如何使用Product Spec

Read these sections in order:

```
Problem
```
: who is hurting and why the work matters.
```
Hypothesis
```
: the causal bet behind the product.
```
Product Summary
```
: what should exist when the work is done.
```
Scope
```
: what is in, out, and deliberately cut.
```
Acceptance Criteria
```
: the build contract, including AI evals when present.
```
Success Metrics
```
: post-launch outcome checks.
```
Related Artifacts
```
: issues, pull requests, eval runs, dashboards, designs, engineering specs, or other Product Specs the work depends on.

Acceptance Criteria are the build contract. Plans, tasks, code changes, tests, and pull request summaries should cite the relevant

AC-<number>

IDs.

AI evals are pre-launch gates inside Acceptance Criteria, not a separate

## AI Evals

section. Cite

EVAL-<number>

when implementing or changing model behavior.

Success Metrics are post-launch outcomes. Do not treat

SM-<number>

items as implementation tasks.

按以下顺序阅读这些章节：

```
Problem
```
（问题）：受影响的用户群体以及该工作的重要性原因。
```
Hypothesis
```
（假设）：产品背后的因果假设。
```
Product Summary
```
（产品概述）：工作完成后应实现的内容。
```
Scope
```
（范围）：包含、排除以及刻意删减的内容。
```
Acceptance Criteria
```
（验收标准）：构建契约，包含AI评估（若有）。
```
Success Metrics
```
（成功指标）：发布后的结果验证标准。
```
Related Artifacts
```
（相关工件）：工作依赖的问题、拉取请求、评估运行、仪表板、设计、工程规格或其他Product Spec。

验收标准是构建契约。计划、任务、代码变更、测试和拉取请求摘要应引用相关的

AC-<编号>

ID。

AI评估是验收标准中的发布前关卡，而非单独的

## AI Evals

章节。在实现或变更模型行为时，请引用

EVAL-<编号>

。

成功指标是发布后的结果。请勿将

SM-<编号>

项视为实现任务。

Planning Rules

规划规则

When creating an implementation plan:

List which Product Spec and
```
spec_revision
```
you are implementing.
If ProductSpec MCP is available, call
```
begin_spec_session
```
before planning and include the returned
```
spec_revision
```
and session id in your plan.
Map each task to the relevant Acceptance Criteria.
Name any Acceptance Criteria that are not covered by the plan.
Treat
```
scope.out
```
and
```
scope.cut
```
as explicit non-goals.
Use
```
applies_to
```
and
```
Related Artifacts
```
to find relevant code, issues, pull requests, designs, evals, and dashboards.
Resolve
```
product_spec
```
related artifacts before planning. A spec whose
```
depends_on
```
target is not built yet is blocked, not buildable, and the plan should say what it waits for.
For a folder of specs, run
```
productspec graph <dir> --json
```
(or the
```
get_spec_graph
```
MCP tool) to get the buildable set, the blocked set with what each spec waits for, and a dependency-respecting build order in one call, instead of re-reading every spec to derive it.
For a repo with Product Specs, Agent Runs, Decision Traces, and evidence links, run
```
productspec garden <repo> --json
```
before selecting work. Use it to find missing evidence, stale revision pins, run gaps, Decision Trace gaps, unscoped specs, contention, and waves.
If another agent may be working the same folder, read
```
contention
```
and
```
waves
```
from that same call. Two specs that touch one surface must not be built at the same time, even when both are buildable. Take work from the current wave, and treat a spec listed in
```
unscoped
```
as unknown scope rather than safe scope.
Treat
```
RESOLVE-IN-PLAN:
```
markers as unresolved technical bindings. Resolve each marker against the codebase with a source citation before coding.
Do not implement guessed table names, fields, endpoints, services, or file paths as if they were binding instructions.

创建实施计划时：

列出你要实施的Product Spec及其
```
spec_revision
```
（规格版本）。
如果ProductSpec MCP可用，请在规划前调用
```
begin_spec_session
```
，并在计划中包含返回的
```
spec_revision
```
和会话ID。
将每个任务映射到对应的验收标准。
列出计划未覆盖的验收标准。
将
```
scope.out
```
和
```
scope.cut
```
视为明确的非目标。
使用
```
applies_to
```
和
```
Related Artifacts
```
查找相关代码、问题、拉取请求、设计、评估和仪表板。
在规划前解决与
```
product_spec
```
相关的工件。若某个规格的
```
depends_on
```
目标尚未构建，则该规格处于阻塞状态，无法构建，计划中应说明其等待的内容。
对于规格文件夹，运行
```
productspec graph <dir> --json
```
（或
```
get_spec_graph
```
MCP工具），一次性获取可构建集合、阻塞集合（以及每个规格等待的内容）和遵循依赖关系的构建顺序，无需重新阅读每个规格来推导。
对于包含Product Spec、Agent Run、决策跟踪和证据链接的仓库，在选择工作前运行
```
productspec garden <repo> --json
```
。用它查找缺失的证据、过时的版本固定、运行缺口、决策跟踪缺口、未界定范围的规格、冲突和工作波次。
如果其他Agent可能在同一文件夹工作，请从同一调用中查看
```
contention
```
（冲突）和
```
waves
```
（波次）。即使两个规格都可构建，涉及同一界面的两个规格也不能同时构建。选择当前波次的工作，并将
```
unscoped
```
中列出的规格视为范围未知而非安全范围。
将
```
RESOLVE-IN-PLAN:
```
标记视为未解决的技术绑定。在编码前，通过引用源代码解决每个标记。
请勿将猜测的表名、字段、端点、服务或文件路径当作绑定指令来实现。

Change Rules

变更规则

Do not silently change product intent.

If implementation pressure conflicts with the Product Spec, state the conflict and propose one of:

update the Product Spec
update the implementation
accept a tradeoff and record a Decision Trace
reopen the work

If behavior changes after implementation, propose a Product Spec revision or a Decision Trace entry instead of treating code drift as intent.

请勿擅自变更产品意图。

如果实施压力与Product Spec冲突，请说明冲突并提出以下方案之一：

更新Product Spec
更新实现方案
接受权衡并记录决策跟踪
重新开启工作

如果实施后行为发生变更，请提议修订Product Spec或添加决策跟踪条目，而非将代码漂移视为意图。

Output Rules

输出规则

When reporting progress or opening a pull request:

If ProductSpec MCP is available, call
```
check_spec_session
```
first. If the Product Spec changed, re-read it and re-plan before claiming done.
If ProductSpec MCP is available, call
```
get_evidence_checklist
```
and attach or name evidence for covered
```
AC-
```
and
```
EVAL-
```
IDs.
If the repo uses Agent Run files, call
```
draft_agent_run
```
or run
```
productspec init-run <spec> <agent-run>
```
to create a receipt, then fill in checked
```
AC-
```
,
```
EVAL-
```
, and
```
SM-
```
IDs, evidence links, drift state, and completion claim. Validate it with
```
productspec validate-run
```
.
Before claiming completion, run
```
productspec reconcile <spec> --against <agent-run>
```
when a local CLI is available. Fix missing checked items, failed items, stale spec revisions, passed items without evidence, or drift without Decision Trace before saying the work is done.
cite the Product Spec path and
```
spec_revision
```
cite the Acceptance Criteria covered
cite AI evals added or changed
name scope items intentionally deferred
link related issues, pull requests, eval runs, or dashboards when available

报告进度或发起拉取请求时：

如果ProductSpec MCP可用，请先调用
```
check_spec_session
```
。若Product Spec已变更，请重新阅读并重新规划，再声明工作完成。
如果ProductSpec MCP可用，请调用
```
get_evidence_checklist
```
，并附上或注明已覆盖的
```
AC-
```
和
```
EVAL-
```
ID的证据。
如果仓库使用Agent Run文件，请调用
```
draft_agent_run
```
或运行
```
productspec init-run <spec> <agent-run>
```
创建凭证，然后填写已勾选的
```
AC-
```
、
```
EVAL-
```
和
```
SM-
```
ID、证据链接、漂移状态和完成声明。使用
```
productspec validate-run
```
验证凭证。
如果本地CLI可用，在声明完成前运行
```
productspec reconcile <spec> --against <agent-run>
```
。在声明工作完成前，修复缺失的勾选项、失败项、过时的规格版本、无证据的通过项或无决策跟踪的漂移。
引用Product Spec路径和
```
spec_revision
```
引用已覆盖的验收标准
引用新增或变更的AI评估
列出有意延迟的范围项
如有可用，链接相关问题、拉取请求、评估运行或仪表板