ECC product-capability 技能实战：把 PRD 变成可实现的能力契约（PRD-to-SRS 通道）

本文基于 ECC（The agent harness performance optimization system）仓库中的 product-capability 技能文档，讲清楚这条 ECC 原生的"PRD-to-SRS 通道"：它如何在编码开始前把模糊的产品意图翻译为显式约束、接口契约与未决问题清单，并产出一份可跨 Claude Code、Codex、Cursor、OpenCode 等 harness 复用的能力计划工件。读完后，你能掌握该技能的完整工作流、输出格式与配套模板，并知道它在 ECC 规划流水线中如何与 /plan-prd、/plan、tdd-workflow 等上下游环节衔接。

一、技能定位：解决"开始前必须成立什么"，而非"要建什么"

技能文档的第一句话就划定了边界（.agents/skills/product-capability/SKILL.md）：

This skill turns product intent into explicit engineering constraints. Use it when the gap is not "what should we build?" but "what exactly must be true before implementation starts?"

也就是说，它的适用前提不是"需求还不清楚"，而是"需求已经清楚，但隐含的架构、数据、生命周期、策略约束还没有被写下来"。文档给出的五类典型使用场景（SKILL.md）：

• 已有 PRD、roadmap 条目、讨论或创始人笔记，但实现约束仍然是隐式的；
• 功能横跨多个服务、仓库或团队，需要在编码前先有一份"能力契约"（capability contract）；
• 产品意图清晰，但架构、数据、生命周期或策略含义仍然模糊；
• 高级工程师在 review 中反复重申同样的隐藏假设（说明这些假设没有被固化）；
• 需要一份可复用的工件，能在不同 harness 和会话之间存活。

从仓库结构看，这个技能在仓库中有两份内容一致的存放位置：面向用户安装的 skills/product-capability/SKILL.md 与面向 Agent 接口的 .agents/skills/product-capability/SKILL.md。后者附带一份接口元数据 .agents/skills/product-capability/agents/openai.yaml，其中 policy.allow_implicit_invocation: true 表示该技能允许被隐式调用（即 Agent 在判断任务匹配时可直接启用，而无需显式点名）。该技能同时被打包进安装清单 manifests/install-modules.json 与 package.json，属于随 ECC 安装面分发的标准技能。

仓库的 WORKING-CONTEXT.md 记录了它的来历：2026-04-05 添加了 skills/product-capability 与 docs/examples/product-capability-template.md，作为 issue #1185 的"canonical PRD-to-SRS lane"，即介于"模糊产品意图"与"实现"之间的能力契约环节；同一条目还说明它刻意放在 business-content 中，"rather than spawning a parallel planning subsystem"（不另起一套并行规划子系统）。docs/skill-adaptation-policy.md 也强调在技能命名上优先使用 product-capability 这类 ECC 原生名称，而非含糊的导入式规划标签。

与 product-lens 的分工

ECC 中还有一个上游技能 product-lens，两者职责被明确切分（skills/product-lens/SKILL.md）：

• product-lens 负责产品诊断——验证 "why"、输出 go/no-go 建议；
• product-capability 负责实现就绪的能力计划——即 SRS 风格的约束与契约。

product-lens 的文档明确写着：当用户需要一份持久的 PRD-to-SRS 或能力契约工件时，"hand off to product-capability"；若诊断结果是"yes, build this"，下一站是 product-capability，"not more founder-theater"。因此典型的产品决策链路是：

product-lens（诊断 why，go/no-go）
        │  go
        ▼
product-capability（输出能力契约 + HANDOFF）
        │
        ├── tdd-workflow / plan（实现）
        ├── project-flow-ops（流程协调）
        └── verification-loop（验证闭环）

二、规范工件（Canonical Artifact）：能力契约写在哪里

技能文档的"Canonical Artifact"一节（SKILL.md）给出了一条明确的落盘规则，这是该技能与"一次性会话规划"的本质区别：

1. 仓库已有持久产品上下文文件时——如 PRODUCT.md、docs/product/ 目录或 program-spec 目录——直接在该处更新，不另起新文件；
2. 尚不存在能力清单时——用仓库自带的模板 docs/examples/product-capability-template.md 新建。

文档同时声明了设计目标："The goal is not to create another planning stack. The goal is to make hidden capability constraints durable and reusable."（目标不是再造一套规划体系，而是让隐藏的能力约束变得持久、可复用。）

模板文件 product-capability-template.md 的完整结构如下，每一节在技能输出中都有对应物：

模板章节	要求填写的内容
Capability	能力名称、来源（PRD / issue / discussion / roadmap / founder note）、主要 actor、发布后的结果（Outcome after ship）、成功信号（Success signal）
Product Intent	用一小段话描述用户可见的承诺
Constraints	实现开始前必须成立的规则：业务规则、范围边界、不变式（invariants）、灰度/回滚约束、迁移约束、向后兼容约束、计费/鉴权/合规约束
Actors and Surfaces	各 actor；UI / API / 自动化 / 报表与仪表盘四类触点表面
States and Transitions	用显式状态与允许的迁移描述生命周期，模板给了两个示例：draft -> active -> paused -> completed 与 pending -> approved -> provisioned -> revoked
Interface Contract	输入、输出、必需副作用、失败状态、重试/恢复、幂等预期
Data Implications	事实来源（source of truth）、新增实体或字段、所有权边界、保留期/删除预期
Security and Policy	信任边界、权限要求、滥用路径、策略/治理要求
Non-Goals	该能力明确不负责的内容
Open Questions	阻塞实现的未决决策
Handoff	三问：Ready for implementation? Needs architecture review? Needs product clarification? 以及 Next ECC lane（project-flow-ops / tdd-workflow / verification-loop / other）

三、五条不可妥协的规则（Non-Negotiable Rules）

技能文档用一节专门列出五条硬性规则（SKILL.md），它们定义了这份能力契约的"事实边界"，值得逐条理解：

1. Do not invent product truth —— 不编造产品事实，未决问题必须显式标记（落进 OPEN QUESTIONS 而不是被悄悄假设掉）；
2. Separate user-visible promises from implementation details —— 把"对用户可见的承诺"和"实现细节"分开写，防止两者在后续迭代中互相污染；
3. Call out what is fixed policy, what is architecture preference, and what is still open —— 明确区分"固定策略 / 架构偏好 / 尚未开放"三档约束强度，让读者知道哪些可以动、哪些不能动；
4. If the request conflicts with existing repo constraints, say so clearly —— 当需求与仓库既有约束冲突时直说，而不是"抹平"过去；
5. Prefer one reusable capability artifact over scattered ad hoc notes —— 优先维护一份可复用的能力工件，而不是散落各处的临时笔记。

第 3 条尤其关键：它对应工作流第 2 步中区分"fixed policy / architecture preference / open"的要求，也解释了为什么模板的 Constraints 一节要求逐条列出规则而不是笼统一句话——约束的"强度分级"决定了下游实现与 review 的自由度。

四、输入清单：只读必要的内容

技能的 Inputs 一节（SKILL.md）要求"Read only what is needed"，即按需读取、不做全库扫描。四类输入：

1. Product intent（产品意图）：issue、discussion、PRD、roadmap 笔记、创始人消息；
2. Current architecture（当前架构）：相关仓库文档、契约、schema、路由、既有工作流；
3. Existing capability context（既有能力上下文）：PRODUCT.md、设计文档、RFC、迁移笔记、运营模型文档；
4. Delivery constraints（交付约束）：鉴权、计费、合规、灰度发布、向后兼容、性能、review 策略。

注意第 2、4 类：它们要求技能在产出契约前就核对"仓库里已经有什么约束"，这正是规则 4（冲突必须直说）能落地的前提——如果没读现有契约与交付约束，冲突根本无从发现。

五、核心工作流：四步把意图变成执行交接

步骤 1：重述能力（Restate the capability）

把整个诉求压缩成一个精确陈述，必须回答三件事：

• 用户或操作者是谁；
• 本次发布后存在什么新能力；
• 因为它的存在，什么结果发生了变化。

文档附了一句警示："If this statement is weak, the implementation will drift."（这个陈述若含糊，实现就会漂移。）这一步产出的就是输出格式中的 CAPABILITY 段。

步骤 2：解析能力约束（Resolve capability constraints）

提取实现开始前必须成立的约束，清单共八项（SKILL.md）：

• 业务规则（business rules）
• 范围边界（scope boundaries）
• 不变式（invariants）
• 信任边界（trust boundaries）
• 数据所有权（data ownership）
• 生命周期迁移（lifecycle transitions）
• 灰度 / 迁移要求（rollout / migration requirements）
• 失败与恢复预期（failure and recovery expectations）

文档特别指出："These are the things that often live only in senior-engineer memory."（这些东西往往只活在高级工程师的脑子里。）这一步对应模板中的 Constraints、States and Transitions、Interface Contract 三节。

步骤 3：定义面向实现的契约（Define the implementation-facing contract）

产出一份 SRS 风格的能力计划，九项内容缺一不可：

1. 能力摘要（capability summary）
2. 显式的非目标（explicit non-goals）
3. actor 与触点表面（actors and surfaces）
4. 必需的状态与迁移（required states and transitions）
5. 接口 / 输入 / 输出（interfaces / inputs / outputs）
6. 数据模型影响（data model implications）
7. 安全 / 计费 / 策略约束（security / billing / policy constraints）
8. 可观测性与操作者要求（observability and operator requirements）
9. 阻塞实现的未决问题（open questions blocking implementation）

步骤 4：翻译成执行交接（Translate into execution）

以精确的交接结论收尾，只有三种合法状态：

• ready for direct implementation（可直接实现）
• needs architecture review first（需先做架构评审）
• needs product clarification first（需先做产品澄清）

若适用，再指向下一个 ECC 原生"lane"（SKILL.md），文档列出的候选：

• project-flow-ops —— 跨 GitHub/Linear 的执行流协调（见 skills/project-flow-ops/SKILL.md）
• workspace-surface-audit —— 工作区表面审计
• api-connector-builder —— API 连接器构建
• dashboard-builder —— 仪表盘构建
• tdd-workflow —— 测试先行实现
• verification-loop —— 验证闭环（见 skills/verification-loop/SKILL.md，其四阶段为 build → type check → lint → test suite，是 HANDOFF 后最常见的收口环节）

六、输出格式：固定六段式

技能强制了输出顺序（SKILL.md），任何回答都必须按此格式返回：

CAPABILITY
- one-paragraph restatement

CONSTRAINTS
- fixed rules, invariants, and boundaries

IMPLEMENTATION CONTRACT
- actors
- surfaces
- states and transitions
- interface/data implications

NON-GOALS
- what this lane explicitly does not own

OPEN QUESTIONS
- blockers or product decisions still required

HANDOFF
- what should happen next and which ECC lane should take it

六段与模板文件一一对应：CAPABILITY ↔ 模板的 Capability/Product Intent；CONSTRAINTS ↔ Constraints/Security and Policy；IMPLEMENTATION CONTRACT ↔ Actors and Surfaces/States and Transitions/Interface Contract/Data Implications；NON-GOALS、OPEN QUESTIONS、HANDOFF 则与模板同名片节直接对应。这种"输出格式即模板骨架"的设计让会话内产出的契约可以直接回填到持久文件（PRODUCT.md 或按模板新建的文件）中，形成可进 git、可 diff、可被下一条 lane 消费的工件——这与 docs/PLAN-PRD-PATTERN.md 中"每个阶段产出可提交的 markdown 暂存文件，下一命令以文件路径为输入"的流水线哲学一致。

七、在 ECC 规划流水线中的位置

从仓库现有命令与文档可以还原出 product-capability 所处的完整链条：

1. 需求阶段：/plan-prd 命令产出 .claude/prds/{name}.prd.md（见 docs/PLAN-PRD-PATTERN.md 的流程图）；若需求是"意图清楚但约束隐式"，则由 product-capability 技能介入，产出能力契约。
2. 能力契约阶段（本文主体）：product-capability 输出六段式契约，HANDOFF 给出三态之一。
3. 设计阶段：/plan 命令能直接消费 .prd.md 文件（PRD artifact mode，见 commands/plan.md 的输入模式表），选中下一个 pending 里程碑并写入 .claude/plans/{name}.plan.md；/plan 在写计划前会做 Pattern Grounding（命名、错误处理、日志、数据访问、测试五类既有模式），这与能力契约中"核对现有架构约束"的要求呼应。
4. 实现与验证阶段：tdd-workflow 测试先行实现；verification-loop 执行 build / type check / lint / test 四阶段验证（skills/verification-loop/SKILL.md）；最后 /pr 开 PR 并自动引用 PRD 与 plan 路径。

该技能也被其他工作流显式引用为"可复用的 SWE 表面"。例如 ML 工程工作流 skills/mle-workflow/SKILL.md 的表格中：

product-capability / architecture-decision-records —— Turn model work into explicit product contracts and record irreversible data, model, and rollout choices

其任务模拟表 MLE-01 也把"框定一个模糊的预测/排序/推荐能力"的标准路径写成 product-capability → plan → architecture-decision-records → mle-workflow。这说明 product-capability 在仓库内部被定位为跨领域的契约前置件，而非仅面向业务功能。

八、实战走查：从一条 roadmap 需求到 HANDOFF

以下示例基于技能的输入/输出规范推演，演示一次典型的调用与产出结构（具体内容为示意，非仓库既成事实）：

输入：一条 roadmap 笔记——"为公开 API 增加按用户的速率限制"，且该功能横跨 API 网关服务与计费服务。

技能读取（对应 Inputs 四类）：PRD 笔记（产品意图）、网关现有的中间件与路由代码（当前架构）、仓库中已有的限流相关 RFC（既有能力上下文）、鉴权与计费约束文档（交付约束）。

按六段式输出：

CAPABILITY
- 操作者为平台租户与运维；发布后每个 API 消费者拥有独立速率配额，
  超限返回 429 与 Retry-After；计费侧可按超限事件对账。

CONSTRAINTS
- fixed policy：超限必须限流而非静默丢弃；配额不可跨租户共享
- invariant：网关本地限流与计费记录必须在同一事务边界内一致
- trust boundary：配额配置仅运维角色可写
- rollout：按租户白名单灰度，支持随时回退到全量放行
- open：超限事件的计费口径（按次/按小时）未定

IMPLEMENTATION CONTRACT
- actors：租户、运维、计费对账作业
- surfaces：API 网关（429 响应面）、运维配置面、计费报表面
- states：unlimited -> limited -> throttled -> suspended
- interface/data：新增 tenant_quota 实体，事实来源为配置中心；
  限流判定需幂等，重试不重复计数

NON-GOALS
- 不实现多租户配额市场化（购买/转让配额）
- 不改动既有全局限流阈值

OPEN QUESTIONS
- 超限事件的计费口径需产品确认
- 灰度白名单初始范围未定

HANDOFF
- needs product clarification first
- 澄清计费口径后进入 tdd-workflow 实现；
  跨服务协调项移交 project-flow-ops

这个走查体现了三条规则的实际效果：规则 1（未决问题显式化）——计费口径落进 OPEN QUESTIONS 而非被假设；规则 3（约束分级）——CONSTRAINTS 中标注了 fixed policy 与 invariant；步骤 4（三态交接）——因存在产品未决项，HANDOFF 明确不是"ready for direct implementation"，避免了带着假设开工。

九、成功标准与适用前提

技能文档的 "Good Outcomes" 一节（SKILL.md）给出了三个可检验的成功标准：

• 产品意图已具体到"实现过程中不必重新发现隐藏约束"；
• 工程 review 拥有一份持久工件，而不是依赖工程师记忆或即时通讯软件里的上下文；
• 产出的计划可复用于 Claude Code、Codex、Cursor、OpenCode 及 ECC 2.0 的规划表面。

使用时的适用前提与限制，可归纳为：

1. 输入前提：必须存在可读取的产品意图载体（issue/PRD/讨论）与可核对的仓库现状（契约、schema、路由），否则"与既有约束冲突"无从判断；
2. 落盘前提：产物应写回持久产品上下文文件（PRODUCT.md 等）或按 模板 新建，而非停留在会话记录中——这是该技能区别于普通规划对话的核心；
3. 边界前提：它不承担产品诊断（"该不该做"由 product-lens 负责）与实现设计（文件级任务拆分由 /plan 负责），HANDOFF 的三态结论应被下游 lane 尊重。

综合来看，product-capability 在 ECC 中的价值可以用一句话概括：把"只在资深工程师脑子里"的实现前置约束，变成一份进版本库、可被任何 harness 会话续读、并带明确交接结论的工程契约——这正是仓库 WORKING-CONTEXT.md 所说"make hidden capability constraints durable and reusable"的落地方式。