spec-builder

规格构建器

通过结构化访谈，将模糊的想法转化为具体、可执行的规格文档。

工作流

阶段 1：收集初始背景信息

首先，询问用户的想法：

What's the idea you'd like to turn into a spec?
Describe it however it exists in your head right now - it can be vague.

然后询问背景问题，以调整访谈深度：

AskUserQuestion:
1. "What's your background?"
   - Technical (developer/engineer)
   - Semi-technical (PM, designer, technical founder)
   - Non-technical (business, creative, general user)

2. "What's the goal for this spec?"
   - MVP/prototype to test the idea
   - Full product spec for development
   - Implementation plan for an AI coding agent
   - Pitch document for stakeholders
   - Personal reference to clarify my thinking

阶段 2：深入访谈

使用 AskUserQuestion，通过分批提问开展访谈（每批包含 2-4 个相关问题）。

规则：

• 不要做任何假设——遇到含糊之处时要提问
• 为每个问题提供合理的默认选项
• 在最佳默认选项后添加“（推荐）”
• 预判用户尚未考虑到的需求
• 根据用户的技术水平调整问题深度

根据用户背景调整问题：

主题	技术用户	非技术用户
架构	“REST、GraphQL 还是 tRPC？”	跳过——自行决定
数据存储	“SQL 还是 NoSQL？用哪个数据库？”	“是否需要在不同会话之间保留数据？”
UI 框架	“React、Vue 还是 Svelte？”	跳过——自行决定
托管	“无服务器、容器还是 VM？”	跳过——自行决定
身份验证	“OAuth、魔法链接还是密码？”	“用户应如何登录？”（使用通俗易懂的选项）
规模	“预计有多少并发用户？”	“可能有多少人会同时使用？”

优先讨论承重决策：

并非所有决策都同等重要。有些决策后续调整成本很低；另一些则是基础性决策——它们会影响核心架构、用户体验或物理设计，重做起来代价高昂或令人头疼。访谈必须识别出对于_此特定产品_而言哪些决策具有承重性，明确指出这些决策，并在继续之前取得用户的明确批准。此要求适用于所有产品类型。

判断标准：“如果在发布/投入生产后更改此决策，是否需要大量返工、数据迁移、工具链调整或重新设计？”如果是，这就是承重决策，必须提前讨论。如果不是，可以在后续迭代中调整，无需在访谈中深入讨论。

哪些决策具有承重性因产品而异。以下是一些帮助校准判断的例子：

• 存储与数据架构（软件）——内容存放在哪里、何时上传、什么是事实来源
• 异步处理模式（软件）——如何跟踪长时间运行的操作、由谁轮询、如何传达进度
• 并发模型（软件）——系统是否从一开始就支持并行工作负载，因为事后补上这项能力意味着重写
• 核心机制与形态（硬件）——产品的基本工作原理、尺寸和供电方式
• 制造工艺与材料（硬件）——注塑、CNC 加工还是 3D 打印，会影响成本、公差和交付周期
• 监管与认证要求（硬件）——事后再设计以满足合规要求，意味着高昂的重新设计成本
• UI/UX 模式（任何类型）——有时更改很简单（颜色、文案），有时则具有承重性（例如，实时协作界面与异步工作流之别，或整个数据模型都围绕其构建的信息流式布局）
• 第三方依赖项（任何类型）——更换提供商通常意味着重写集成，并处理不同的数据格式
• 身份验证与身份模型（软件/服务）——在不同身份验证系统之间迁移用户会造成极大干扰

这些只是示例，并非检查清单。针对每种产品，都要从基本原理出发，思考哪些东西是“浇筑在混凝土里的”，哪些只是“重新摆放家具”，并据此确定访谈重点。 对于技术用户，直接询问影响重大的决策。对于非技术用户，简化概念，但仍要征得他们的同意——例如，不要问“前端应该通过请求 ID 轮询，还是使用服务器发送事件？”，而是问“生成需要 30 秒时，用户应该看到实时进度更新，还是只在完成后收到通知？”

访谈时间应与决策的可逆难度成正比。 对于本产品中可以轻易更改的方面，不要深入探讨，除非用户主动提起。

需要涵盖的访谈领域（根据产品类型调整）：

对于软件产品：

• 核心功能（产品的用途是什么？）
• 用户类型和权限
• 关键用户流程（逐步说明）
• 数据模型（有哪些实体，它们之间有什么关系）
• 集成（外部服务、API、回退策略）
• 边缘情况和错误处理
• 安全与隐私要求
• 平台（Web、移动端、桌面端、CLI）

对于实体产品：

• 核心功能
• 用户交互（如何使用？）
• 制造方面的考量
• 安全要求
• 包装与交付

对于所有产品：

• 确定该产品中影响重大的决策（见上文）

对于所有产品：

• 成功标准（如何判断产品是否正常运行？）
• 约束条件（预算、时间线、必备项）
• 反目标（明确指出产品不应该做什么）

分批提问示例：

AskUserQuestion (batch):
1. "Who are the main users of this product?"
   - Single user type (just me / general public)
   - Two distinct roles (e.g., admin + regular user)
   - Multiple user types (need to define each)

2. "Do users need accounts?"
   - No accounts needed (Recommended for MVP)
   - Simple accounts (email/password)
   - Social login (Google, GitHub, etc.)
   - Enterprise SSO

阶段 3：审阅草案

涵盖核心问题（约 10-15 批）后，提供一份大纲草案：

Here's the spec outline based on our conversation so far:

## [Product Name] - Spec Outline

**Overview:** [1-2 sentences]

**Core Features:**
1. [Feature A]
2. [Feature B]
...

**User Types:** [list]

**Key Flows:** [list main workflows]

**Technical Approach:** [high-level decisions]

**Open Questions:** [things still unclear]

---

Does this capture your vision? What's missing or wrong?

然后使用 AskUserQuestion 征求反馈：

1. "How does this outline look?"
   - Looks good, continue with details
   - Missing something important (I'll explain)
   - Some parts are wrong (I'll clarify)
   - Let's pivot direction

阶段 4：深入探讨

根据反馈，针对以下内容提出详细的后续问题：

• 大纲中的不明确之处
• 边缘情况和错误状态
• 具体的 UI/UX 细节
• 技术约束
• 任何标记为“待解决问题”的事项

继续提问，直到确信所有歧义都已解决。

阶段 5：编写规格说明

在当前目录中将最终规格说明写入 spec-<product-name>.md。

规格说明的格式原则：

• 细节足够丰富，可供 AI 编码 Agent 实现
• 便于人工快速浏览（使用标题、项目符号、表格）
• 不使用模糊表述——每项要求都必须具体
• 明确列出反目标和范围外事项
• 写成独立文档——绝不提及访谈过程，也不引用“我们的对话”

规格说明结构（根据产品类型调整各部分）：

# [Product Name] Spec

## Overview

[2-3 sentences: what it is, who it's for, core value prop]

## Goals & Non-Goals

### Goals

- [Concrete goal 1]
- [Concrete goal 2]

### Non-Goals (explicitly out of scope)

- [What this product will NOT do]

## User Types

[Table or list of user types and their permissions/capabilities]

## Core Features

### Feature 1: [Name]

**Purpose:** [Why this feature exists]
**Behavior:**

- [Specific behavior 1]
- [Specific behavior 2]
  **UI:** [Description or wireframe reference]

[Repeat for each feature]

## User Flows

### Flow 1: [Name]

1. User does X
2. System responds with Y
3. User sees Z
   ...

[Repeat for key flows]

## Data Model

[Tables, entities, relationships - for software]
[Components, materials - for physical products]

## Technical Decisions

[Architecture choices, technologies, integrations]
[Explicitly document every load-bearing decision (storage, async patterns, concurrency, etc.) and note that it was discussed and approved during the interview]
[For non-technical users, describe these in plain language; for physical products, skip]

## Edge Cases & Error Handling

- When X happens, the system should Y
- If Z fails, show error message: "..."

## Open Questions

[Anything that still needs resolution before building]

## Future Considerations

[Ideas mentioned but explicitly deferred]

核心原则

1. 优先处理影响重大的决策——在花时间讨论之后容易更改的细节之前，先识别并解决难以撤销的架构决策。访谈的首要任务是找出这些决策并征得明确同意。
2. 深入细致——多提问题。对于复杂产品，进行 10-20 批提问很正常。
3. 绝不臆测——如果存在两种可能的理解，就询问用户选择哪一种。
4. 提供默认选项——每个问题都应提供合理选项，并给出推荐选择。
5. 调整深度——向技术用户提出技术问题；对非技术用户使用通俗语言。但即使是非技术用户，也必须同意影响重大的决策——只需用简单的方式解释。
6. 揭示未知事项——询问用户可能尚未考虑到的问题。
7. 具体明确——最终规格说明中不应有任何模糊要求。

自我检查

在完成规格说明之前，先问自己：

• “还有哪些影响重大的决策尚未提出？这份规格说明中是否有任何内容在构建完成后会很难更改，而我还没有明确向用户确认？”
• “有哪些边缘情况是我没有考虑到的？”