mcpField
P
productspec

productspec

github.com/gokulrajaram开发31347 次安装15 周前更新
代码仓库

关于 productspec

productspec 是一项 Agent 技能，指导在软件规划和实现中将 Product Spec 作为契约。它帮助 Agent 将工作对应到验收标准、维护产品意图，并核对证据与完成情况。

主要功能

  1. 01规划或编码前先读规格
  2. 02任务映射到验收标准
  3. 03遵循范围与依赖关系
  4. 04明确处理意图变更
  5. 05核对证据与完成情况

适用场景

  1. 01依据规格制定实现计划
  2. 02识别可构建规格及其依赖
  3. 03处理代码与产品意图冲突
  4. 04附带证据汇报进度

MCP 相关

若可使用 ProductSpec MCP，该技能会指导 Agent 在规划和汇报时调用 begin_spec_session、check_spec_session、get_spec_graph 和 get_evidence_checklist 等工具。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/gokulrajaram/productspec --skill productspec

安装后在 Claude Code 中输入/productspec确认已加载。

详细介绍

ProductSpec Agent 技能

产品规格是重要软件工作的产品契约。

如果仓库使用 Agent Run 文件，请将它们视为某次 Agent 执行所依据的固定版本 Product Spec 的凭据。

在规划、编码、测试或变更范围之前，请在仓库中查找相关的 .product-spec.md 文件。常见位置包括：

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

如果存在相关的 Product Spec，请先阅读再采取行动。

如何使用 Product Spec

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

  1. Problem：谁遇到了问题，以及这项工作为何重要。
  2. Hypothesis：产品背后的因果假设。
  3. Product Summary：工作完成后应该具备什么。
  4. Scope：包含、排除以及有意删减的内容。
  5. Acceptance Criteria：构建契约，包括其中的 AI 评估。
  6. Success Metrics：发布后的结果检查。
  7. Related Artifacts：工作所依赖的议题、拉取请求、评估运行、仪表板、设计、工程规格或其他 Product Spec。

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

AI 评估是验收标准中的发布前门槛，不是单独的 ## AI Evals 章节。在实现或更改模型行为时，请引用 EVAL-<number>。

成功指标衡量发布后的结果。不要将 SM-<number> 项目视为实现任务。

规划规则

创建实现计划时：

  • 列出你要实现的 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 Specs、Agent Runs、Decision Traces 和证据链接的仓库，请在选择工作前运行 productspec garden <repo> --json。利用它查找缺失的证据、过时的修订版本固定信息、运行缺口、Decision Trace 缺口、未界定范围的规格、冲突以及工作波次。
  • 如果另一个 Agent 可能正在处理同一文件夹，请从同一次调用中读取 contention 和 waves。同时触及同一表面的两个规格不得同时构建，即使二者都可构建。请从当前波次中选择工作，并将列在 unscoped 中的规格视为范围未知，而非范围安全。
  • 将 RESOLVE-IN-PLAN: 标记视为尚未解决的技术绑定。在编码前，根据代码库逐一解决这些标记，并附上源代码引用。
  • 不要将猜测的表名、字段、端点、服务或文件路径当作具有约束力的指令来实现。

变更规则

不要悄悄更改产品意图。

如果实现压力与 Product Spec 冲突，请说明冲突，并提出以下一种做法：

  • 更新 Product Spec
  • 更新实现
  • 接受权衡并记录 Decision Trace
  • 重新开启工作

如果实现后行为发生变化，应提出修订 Product Spec 或添加 Decision Trace 条目，而不是将代码偏离视为产品意图。

输出规则

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

  • 如果 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>。在宣布工作完成之前，修复缺少的已检查项、失败项、过时的规范修订、没有证据的通过项，或缺少 Decision Trace 的偏移。
  • 注明 Product Spec 路径和 spec_revision
  • 注明已覆盖的验收标准
  • 注明新增或更改的 AI 评估
  • 列出有意推迟的范围项
  • 如有相关问题、拉取请求、评估运行或仪表板，请提供链接

评论

支持 Markdown