spec-builder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Spec Builder

Transform vague ideas into concrete, actionable spec documents through structured interviews.

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

Workflow

工作流程

Phase 1: Gather Initial Context

第一阶段：收集初始背景信息

First, prompt for the idea:

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.

Then ask background questions to calibrate the interview depth:

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
   - Pitch document for stakeholders
   - Personal reference to clarify my thinking

首先，询问用户的想法：

你想要转化为规格文档的想法是什么？
按照你脑海中的样子描述即可——可以是模糊的表述。

接着提出背景问题，以调整访谈的深度：

AskUserQuestion:
1. "你的背景是什么？"
   - 技术背景（开发者/工程师）
   - 半技术背景（产品经理、设计师、技术创始人）
   - 非技术背景（商务、创意、普通用户）

2. "这份规格文档的目标是什么？"
   - MVP/原型，用于测试想法
   - 供开发使用的完整产品规格
   - 用于向利益相关者展示的推介文档
   - 用于理清自身思路的个人参考资料

Phase 2: Deep Interview

第二阶段：深度访谈

Conduct the interview using AskUserQuestion with batched questions (2-4 related questions per batch).

Rules:

Never assume - if something is ambiguous, ask
Provide sensible default options for every question
Add "(Recommended)" to the best default option
Anticipate needs the user hasn't considered
Adapt question depth based on user's technical level

Question calibration by user background:

Topic	Technical User	Non-Technical User
Architecture	"REST vs GraphQL vs tRPC?"	Skip - decide yourself
Data storage	"SQL vs NoSQL? Which DB?"	"Does it need to remember data between sessions?"
UI framework	"React, Vue, or Svelte?"	Skip - decide yourself
Hosting	"Serverless, containers, or VMs?"	Skip - decide yourself
Auth	"OAuth, magic links, or password?"	"How should users log in?" (plain language options)
Scale	"Expected concurrent users?"	"How many people might use this at once?"

Interview domains to cover (adapt based on product type):

For software products:

Core functionality (what does it do?)
User types and permissions
Key user flows (step by step)
Data model (what entities exist?)
UI/UX preferences (style, layout, interactions)
Integrations (external services, APIs)
Edge cases and error handling
Security and privacy requirements
Platform (web, mobile, desktop, CLI)

For physical products:

Core functionality
Materials and form factor
User interaction (how do you use it?)
Manufacturing considerations
Safety requirements
Packaging and delivery

For all products:

Success criteria (how do we know it works?)
Constraints (budget, timeline, must-haves)
Anti-goals (what it explicitly should NOT do)

Example batched question:

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

使用AskUserQuestion工具，以批量提问的方式开展访谈（每批2-4个相关问题）。

规则：

绝不主观假设——若存在歧义，务必询问
每个问题都提供合理的默认选项
为最佳默认选项标注“（推荐）”
预判用户未考虑到的需求
根据用户的技术水平调整问题深度

按用户背景调整问题：

主题	技术背景用户	非技术背景用户
架构	"REST vs GraphQL vs tRPC?"	跳过——自行决定
数据存储	"SQL vs NoSQL? 选择哪种数据库？"	"它需要在会话之间保存数据吗？"
UI框架	"React, Vue, or Svelte?"	跳过——自行决定
托管	"Serverless, containers, or VMs?"	跳过——自行决定
认证	"OAuth, magic links, or password?"	"用户应该如何登录？"（使用通俗易懂的选项）
规模	"预期并发用户数是多少？"	"可能同时有多少人使用它？"

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

针对软件产品：

核心功能（它能做什么？）
用户类型与权限
关键用户流程（分步说明）
数据模型（存在哪些实体？）
UI/UX偏好（风格、布局、交互）
集成（外部服务、API）
边缘情况与错误处理
安全与隐私要求
平台（网页、移动端、桌面端、CLI）

针对实体产品：

核心功能
材料与外形
用户交互方式（如何使用？）
制造考量因素
安全要求
包装与配送

针对所有产品：

成功标准（如何判断它有效？）
约束条件（预算、时间线、必备要素）
反向目标（明确说明它不应该做的事情）

批量提问示例：

AskUserQuestion (batch):
1. "这款产品的主要用户是谁？"
   - 单一用户类型（仅我自己 / 普通大众）
   - 两种不同角色（例如：管理员 + 普通用户）
   - 多种用户类型（需要分别定义）

2. "用户需要账号吗？"
   - 无需账号（MVP推荐选项）
   - 简易账号（邮箱/密码）
   - 社交登录（Google、GitHub等）
   - 企业级SSO

Phase 3: Draft Review

第三阶段：草稿审核

After covering core questions (~10-15 batches), present a draft outline:

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

在覆盖核心问题后（约10-15批问题），呈现草稿大纲：

以下是根据我们的对话整理的规格文档大纲：

[Product Name] - Spec Outline

[产品名称] - 规格文档大纲

Overview: [1-2 sentences]

Core Features:

[Feature A]
[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?


Then use AskUserQuestion to get feedback:

"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

undefined

概述： [1-2句话]

核心功能：

[功能A]
[功能B] ...

用户类型： [列表]

关键流程： [主要工作流程列表]

技术方案： [高层决策]

待明确问题： [仍不清楚的事项]

这是否符合你的预期？有哪些遗漏或错误的地方？


随后使用AskUserQuestion获取反馈：

"这份大纲看起来如何？"
- 看起来不错，继续完善细节
- 遗漏了重要内容（我会说明）
- 部分内容有误（我会澄清）
- 我们需要调整方向

undefined

Phase 4: Deep Dive

第四阶段：深入挖掘

Based on feedback, ask detailed follow-up questions on:

Unclear areas from the outline
Edge cases and error states
Specific UI/UX details
Technical constraints
Anything marked as "Open Questions"

Continue until confident all ambiguity is resolved.

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

大纲中不明确的部分
边缘情况与错误状态
具体的UI/UX细节
技术约束条件
所有标记为“待明确问题”的事项

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

Phase 5: Write Spec

第五阶段：撰写规格文档

Write the final spec to

spec-<product-name>.md

in the current directory.

Spec format principles:

Detailed enough for an AI coding agent to implement
Skimmable for human review (use headers, bullets, tables)
No vague language - every requirement must be concrete
Include explicit anti-goals and out-of-scope items
Write as a standalone document - never mention the interview process or reference "our conversation"

Spec structure (adapt sections based on product type):

markdown

undefined

在当前目录下将最终规格文档写入

spec-<product-name>.md

文件。

规格文档格式原则：

详细程度需满足AI编码Agent可直接实现的要求
便于人工快速浏览（使用标题、项目符号、表格）
避免模糊表述——每个需求都必须具体明确
包含明确的反向目标与超出范围的内容
作为独立文档撰写——绝不要提及访谈过程或引用“我们的对话”

规格文档结构（根据产品类型调整章节）：

markdown

undefined

[Product Name] Spec

[产品名称] 规格文档

Overview

概述

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

[2-3句话：产品是什么、面向谁、核心价值主张]

Goals & Non-Goals

目标与非目标

Goals

目标

[Concrete goal 1]
[Concrete goal 2]

[具体目标1]
[具体目标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]

功能1：[名称]

Purpose: [Why this feature exists] Behavior:

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

[Repeat for each feature]

目的： [该功能存在的原因] 行为：

[具体行为1]
[具体行为2] UI： [描述或线框图参考]

[为每个功能重复上述结构]

User Flows

用户流程

Flow 1: [Name]

流程1：[名称]

User does X
System responds with Y
User sees Z ...

[Repeat for key flows]

用户执行操作X
系统响应Y
用户看到Z ...

[为每个关键流程重复上述结构]

Data Model

数据模型

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

[表格、实体、关系——针对软件产品] [组件、材料——针对实体产品]

Technical Decisions

技术决策

[Architecture choices, technologies, integrations] [Skip for non-technical users or physical products]

[架构选择、技术栈、集成项] [针对非技术背景用户或实体产品可跳过此章节]

Edge Cases & Error Handling

边缘情况与错误处理

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

当X发生时，系统应执行Y
如果Z失败，显示错误提示："..."

Open Questions

待明确问题

[Anything that still needs resolution before building]

[在开始开发前仍需解决的事项]

Future Considerations

未来考量

[Ideas mentioned but explicitly deferred]

undefined

[已提及但明确推迟的想法]

undefined

Key Principles

核心原则

Be thorough - Ask many questions. 10-20 batches is normal for a complex product.
Never assume - If two interpretations are possible, ask which one.
Provide defaults - Every question should have reasonable options with a recommended choice.
Adapt depth - Technical users get technical questions; non-technical users get plain language.
Surface unknowns - Ask about things the user probably hasn't considered yet.
Stay concrete - The final spec should have zero vague requirements.

全面详尽——提出大量问题。对于复杂产品，10-20批问题是正常的。
绝不假设——如果存在两种解读可能，务必询问确认。
提供默认选项——每个问题都应包含合理选项，并标注推荐选择。
调整深度——为技术背景用户提供技术问题；为非技术背景用户提供通俗易懂的表述。
挖掘未知事项——询问用户可能尚未考虑到的内容。
保持具体——最终规格文档中不能有任何模糊的需求。