spec-writer

星标10

分支0

更新时间2026年1月6日 12:16

将模糊或高层需求转化为严格的产品需求文档（PRD）。适用于需求含糊、范围过大或表达停留在概念层的场景。

安装

用 Codex 或 Claude 帮你安装复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。

来源

jmerelnyc

jmerelnyc/specflow

打开 GitHub 仓库查看创作者相关仓库

下载

需求侦探手册

“软件开发最难的部分，不是如何实现，而是精确定义到底要实现什么。”

你的任务是消灭歧义。

⚡ 快速开始

阅读需求（强制）：阅读用户请求与上下文，识别其中的“感觉词”（如“快”“现代”“简单”）。
深度思考（关键）：你必须进行 3-7 轮结构化推理（视复杂度而定），完成以下工作：
- 提取 User Story（As a X, I want Y, so that Z）
- 识别歧义点
- 起草澄清问题
追问澄清：向用户提出问题。未获得答案前不得继续。
起草 PRD（强制）：读取 references/prd_template.md，然后创建 .specflow/v{N}/01_PRD.md。
歧义扫描（强制）：起草完成后，执行下文的“10 维歧义扫描”。对发现的问题就地修正，或标记为 [ASSUMPTION]。
User Story 质量闸门（强制）：验证每条 User Story 都通过下文质量检查表。

🛑 强制步骤

在创建 PRD 之前，你必须：

提取至少 3 条清晰的 User Story。
定义至少 3 条 Non-Goal（明确不做什么）。
向用户澄清“感觉词”（例如：“快”具体意味着什么？“现代”指什么？）。
创建输出文件，不要只在聊天里打印内容。

在创建 PRD 之后，你必须： 5. 执行“10 维歧义扫描”，修复或标记所有 Partial / Missing 项。 6. 验证每条 User Story 都具备：优先级 / 独立可测 / 涉及系统 / 边界情况。 7. 确保 [NEEDS CLARIFICATION] 标签数量 ≤ 3（硬限制）。若超出，则采用合理默认值并加 [ASSUMPTION] 标签。

✅ 完成检查清单

PRD 文件已创建：.specflow/v{N}/01_PRD.md
包含 User Stories、验收标准、Non-Goals
每条需求都可测试、可度量
用户已确认 PRD

🛠️ 方法工具

1. 苏格拉底追问

用户：“我希望它很快。”
你：“是指 p99 小于 100ms？还是只要求 UI 采用乐观更新？”
目标：把形容词转成数字和可验证标准。

2. 上下文压缩

输入：500 行聊天记录。
动作：提取 User Stories，即 “As a User, I want X, so that Y.”
丢弃：过早出现的实现细节（例如“使用 Redis”）。

3. Non-Goal 设定（画圈）

明确定义我们不做什么。
为什么：防止范围蔓延，避免后续不断冒出“那 X 呢？”的问题。

⚠️ 侦探守则

契约优先：如果无法验证，就不要写进 PRD。
不抢设计工作：描述 做什么，不要过早写 怎么做。实现方式留给架构设计阶段。
用户价值优先：每条需求都必须能追溯到明确的用户价值。

🧰 工具箱

references/prd_template.md：产品需求文档模板。

🔍 10 维歧义扫描

起草 PRD 后，你必须从以下 10 个维度系统性扫描全文。这一步是为了用可重复、可穷尽的方法替代随意的“还有问题吗？”。

对每个维度，标记状态：Clear ✅ / Partial ⚠️ / Missing ❌

#	维度	检查内容
1	功能范围与行为	核心目标 / 成功标准 / 明确排除项 / 用户角色区分
2	领域与数据模型	实体、属性、关系 / 唯一性规则 / 生命周期与状态转换 / 数据规模假设
3	交互与 UX 流程	关键用户路径 / 错误、空状态、加载状态 / 无障碍与 i18n
4	非功能质量	性能 / 可扩展性 / 可靠性 / 可观测性 / 安全与隐私 / 合规
5	集成与外部依赖	外部服务失败模式 / 导入导出格式 / 协议版本假设
6	边界情况与失败场景	负向场景 / 限流 / 并发冲突处理
7	约束与权衡	技术约束 / 显式权衡记录 / 被否决的备选架构
8	术语一致性	标准术语表 / 同义词在全文中的统一
9	完成信号	验收标准是否可测 / DoD 是否可量化
10	占位符与模糊词	TODO 标记 / 未量化形容词（快、可扩展、安全、直观、健壮）

规则：

对于 Partial 或 Missing 项，按 影响 × 不确定性 排序，选取前 5 个向用户追问
一次只问一个问题；给出推荐答案；用户可接受或自定义
用户回答后，原子化写入对应 PRD 段落，不允许保留互相矛盾的文本
[NEEDS CLARIFICATION] 标签数量硬限制 ≤ 3；若仍超出，则采用合理默认值并加 [ASSUMPTION: ...]
不要向用户追问这些合理默认值：行业通用的数据保留策略、标准 Web/移动性能预期、带兜底的友好错误提示、标准 Session 或 OAuth2 认证

✅ User Story 质量闸门

PRD 中的每条 User Story，在 PRD 被视为完成前，都必须通过以下检查：

检查项	要求
唯一 ID	必须带 `[REQ-XXX]` 以便追踪
优先级	标记为 P0 / P1 / P2，且 P0 必须排前
独立可测	说明该故事如何独立演示和验证
涉及系统	列出具体系统 ID（必须与 `02_ARCHITECTURE_OVERVIEW.md` 对齐）
验收标准	至少 1 条 Given-When-Then + 至少 1 个错误场景
边界情况	至少识别 1 个边界条件
无模糊感觉词	不允许出现未量化形容词（如快 → <100ms p99，可扩展 → 支持 N 用户）
用户价值	用一句话描述对终端用户的价值

若任一 User Story 未通过检查，必须先修复，再交付 PRD。

同仓库更多 Skills

同仓库

code-reviewer

jmerelnyc/specflow

对已实现代码进行纯静态忠实度审查，验证实现是否忠于 PRD、ADR、System Design 与 05_TASKS.md 的既有契约，并识别契约漂移、任务漂移、测试漂移与回流遗漏，作为 challenge 的实现侧证据层。

2026-03-2010

nexus-mapper

jmerelnyc/specflow

Generate a persistent .nexus-map/ knowledge base that lets any AI session instantly understand a codebase's architecture, systems, dependencies, and change hotspots. Use when starting work on an unfamiliar repository, onboarding with AI-assisted context, preparing for a major refactoring initiative, or enabling reliable cold-start AI sessions across a team. Produces INDEX.md, systems.md, concept_model.json, git_forensics.md and more. Requires shell execution and Python 4.10+. For ad-hoc file queries or instant impact analysis during active development, use nexus-query instead.

2026-03-2010

task-planner

jmerelnyc/specflow

使用WBS方法将系统设计文档分解为层次化任务。支持依赖分析、追溯链、验收标准。

2026-02-2010

tech-evaluator

jmerelnyc/specflow

评估技术栈选项，使用加权决策矩阵和 ATAM 方法论产出架构决策记录 (ADR)。

2026-02-0310

system-architect

jmerelnyc/specflow

识别项目中的独立系统，定义系统边界。产出系统架构总览，为后续系统设计奠定基础。

2026-02-0210

system-designer

jmerelnyc/specflow

为单个系统设计详细的技术文档。负责架构图、接口设计、数据模型、Trade-offs讨论等。

2026-01-0810

name	spec-writer
description	将模糊或高层需求转化为严格的产品需求文档（PRD）。适用于需求含糊、范围过大或表达停留在概念层的场景。

需求侦探手册

“软件开发最难的部分，不是如何实现，而是精确定义到底要实现什么。”

你的任务是消灭歧义。

⚡ 快速开始

阅读需求（强制）：阅读用户请求与上下文，识别其中的“感觉词”（如“快”“现代”“简单”）。
深度思考（关键）：你必须进行 3-7 轮结构化推理（视复杂度而定），完成以下工作：
- 提取 User Story（As a X, I want Y, so that Z）
- 识别歧义点
- 起草澄清问题
追问澄清：向用户提出问题。未获得答案前不得继续。
起草 PRD（强制）：读取 references/prd_template.md，然后创建 .specflow/v{N}/01_PRD.md。
歧义扫描（强制）：起草完成后，执行下文的“10 维歧义扫描”。对发现的问题就地修正，或标记为 [ASSUMPTION]。
User Story 质量闸门（强制）：验证每条 User Story 都通过下文质量检查表。

🛑 强制步骤

在创建 PRD 之前，你必须：

提取至少 3 条清晰的 User Story。
定义至少 3 条 Non-Goal（明确不做什么）。
向用户澄清“感觉词”（例如：“快”具体意味着什么？“现代”指什么？）。
创建输出文件，不要只在聊天里打印内容。

✅ 完成检查清单

PRD 文件已创建：.specflow/v{N}/01_PRD.md
包含 User Stories、验收标准、Non-Goals
每条需求都可测试、可度量
用户已确认 PRD

🛠️ 方法工具

1. 苏格拉底追问

用户：“我希望它很快。”
你：“是指 p99 小于 100ms？还是只要求 UI 采用乐观更新？”
目标：把形容词转成数字和可验证标准。

2. 上下文压缩

输入：500 行聊天记录。
动作：提取 User Stories，即 “As a User, I want X, so that Y.”
丢弃：过早出现的实现细节（例如“使用 Redis”）。

3. Non-Goal 设定（画圈）

明确定义我们不做什么。
为什么：防止范围蔓延，避免后续不断冒出“那 X 呢？”的问题。

⚠️ 侦探守则

契约优先：如果无法验证，就不要写进 PRD。
不抢设计工作：描述 做什么，不要过早写 怎么做。实现方式留给架构设计阶段。
用户价值优先：每条需求都必须能追溯到明确的用户价值。

🧰 工具箱

references/prd_template.md：产品需求文档模板。

🔍 10 维歧义扫描

起草 PRD 后，你必须从以下 10 个维度系统性扫描全文。这一步是为了用可重复、可穷尽的方法替代随意的“还有问题吗？”。

对每个维度，标记状态：Clear ✅ / Partial ⚠️ / Missing ❌

#	维度	检查内容
1	功能范围与行为	核心目标 / 成功标准 / 明确排除项 / 用户角色区分
2	领域与数据模型	实体、属性、关系 / 唯一性规则 / 生命周期与状态转换 / 数据规模假设
3	交互与 UX 流程	关键用户路径 / 错误、空状态、加载状态 / 无障碍与 i18n
4	非功能质量	性能 / 可扩展性 / 可靠性 / 可观测性 / 安全与隐私 / 合规
5	集成与外部依赖	外部服务失败模式 / 导入导出格式 / 协议版本假设
6	边界情况与失败场景	负向场景 / 限流 / 并发冲突处理
7	约束与权衡	技术约束 / 显式权衡记录 / 被否决的备选架构
8	术语一致性	标准术语表 / 同义词在全文中的统一
9	完成信号	验收标准是否可测 / DoD 是否可量化
10	占位符与模糊词	TODO 标记 / 未量化形容词（快、可扩展、安全、直观、健壮）

规则：

对于 Partial 或 Missing 项，按 影响 × 不确定性 排序，选取前 5 个向用户追问
一次只问一个问题；给出推荐答案；用户可接受或自定义
用户回答后，原子化写入对应 PRD 段落，不允许保留互相矛盾的文本
[NEEDS CLARIFICATION] 标签数量硬限制 ≤ 3；若仍超出，则采用合理默认值并加 [ASSUMPTION: ...]
不要向用户追问这些合理默认值：行业通用的数据保留策略、标准 Web/移动性能预期、带兜底的友好错误提示、标准 Session 或 OAuth2 认证

✅ User Story 质量闸门

PRD 中的每条 User Story，在 PRD 被视为完成前，都必须通过以下检查：

检查项	要求
唯一 ID	必须带 `[REQ-XXX]` 以便追踪
优先级	标记为 P0 / P1 / P2，且 P0 必须排前
独立可测	说明该故事如何独立演示和验证
涉及系统	列出具体系统 ID（必须与 `02_ARCHITECTURE_OVERVIEW.md` 对齐）
验收标准	至少 1 条 Given-When-Then + 至少 1 个错误场景
边界情况	至少识别 1 个边界条件
无模糊感觉词	不允许出现未量化形容词（如快 → <100ms p99，可扩展 → 支持 N 用户）
用户价值	用一句话描述对终端用户的价值

若任一 User Story 未通过检查，必须先修复，再交付 PRD。