spec-from-scratch

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Spec From Scratch

从零创建SPEC

Use this skill to turn an unclear idea into a complete, assumption-light Product SPEC. The core job is not writing first; it is discovering what must be true before a useful spec can exist.

This workflow is portable across coding agents and planning systems. Treat it as a pre-planning gate: after the SPEC is complete, the user may hand it to any planning method, implementation workflow, or project-management process.

使用此技能可将模糊的想法转化为一份完整、低假设性的Product SPEC。核心任务并非先动笔撰写，而是先弄清楚一份有用的spec诞生前必须明确的所有关键信息。

此工作流可在各类编码Agent和规划系统中通用。将其视为规划前的关卡：SPEC完成后，用户可将其应用于任何规划方法、实施工作流或项目管理流程。

Operating principle

操作原则

Do not draft the final SPEC until the user's goals, requirements, constraints, edge cases, business rules, and acceptance criteria are fully understood.

If critical information is missing, ask more questions. A polished spec built on hidden assumptions is worse than no spec because it makes uncertainty look settled.

在未完全理解用户的目标、需求、约束条件、边缘情况、业务规则和验收标准之前，不得起草最终的SPEC。

若关键信息缺失，需进一步提问。基于隐藏假设构建的精美spec比没有spec更糟糕，因为它会让不确定性看起来已被解决。

Workflow

工作流

1. Start with scope capture

1. 从范围捕获开始

Begin by restating the raw idea in one or two sentences, then ask the first interview batch.

Use questions with answer options. Mark exactly one option as

(Recommended)

unless the question truly has no sensible default.

Default question format:

markdown

undefined

先用一两句话重述原始想法，然后提出第一批访谈问题。

使用带有选项的问题。除非问题确实没有合理默认选项，否则需明确标记一个选项为

(Recommended)

。

默认问题格式：

markdown

undefined

Question batch N — [theme]

[Question]?
- A. [Option]
```
(Recommended)
```
  — [short reason]
- B. [Option] — [short reason]
- C. [Option] — [short reason]
- D. Other — [ask user to specify]
[Question]?
- A. ...


Ask 7-10 questions in the first batch unless the idea is extremely narrow. The first batch should quickly expose the shape of the problem, so include at least one question about each of these areas: goals, primary users, scope boundaries, business rules or constraints, edge cases/failure modes, and acceptance criteria or success signals. Later batches may be smaller and focused only on remaining gaps. Keep each batch answerable in one pass.

[Question]?
- A. [Option]
```
(Recommended)
```
  — [short reason]
- B. [Option] — [short reason]
- C. [Option] — [short reason]
- D. Other — [ask user to specify]
[Question]?
- A. ...


除非想法范围极其狭窄，否则第一批问题应包含7-10个。第一批问题需快速明确问题的大致轮廓，因此至少要涵盖以下每个领域的一个问题：目标、核心用户、范围边界、业务规则或约束条件、边缘情况/故障模式、验收标准或成功信号。后续批次的问题可更简短，仅聚焦于剩余的信息缺口。确保每批次问题都能一次性回答完毕。

2. Interview exhaustively by domain

2. 按领域全面访谈

Cover these domains before drafting:

Problem and goals
- Problem being solved
- Desired outcome
- Primary and secondary users
- Jobs to be done
- Success metrics
- Non-goals
Scope and deliverables
- Product surface or system boundary
- Must-have vs should-have vs later
- User journeys
- Inputs and outputs
- Environments, platforms, or channels
- Dependencies
Requirements
- Functional requirements
- Data requirements
- Permission and access rules
- Integrations
- Reporting, notifications, or automation
- Admin or support needs
Business rules
- Eligibility rules
- Pricing, billing, quotas, or limits
- Workflow states and transitions
- Approval rules
- Compliance or policy constraints
- Exceptions and overrides
Constraints
- Technical constraints
- Time, budget, staffing, and operational constraints
- Existing systems that must be preserved
- Security, privacy, legal, and regulatory constraints
- Performance and reliability expectations
- Localization, accessibility, and device constraints
Edge cases and failure modes
- Empty, invalid, duplicate, stale, missing, or conflicting data
- Partial completion and retry behavior
- Offline or degraded dependencies
- Abuse cases
- Race conditions or concurrent edits
- User mistakes and recovery paths
Acceptance criteria and validation
- Observable behavior for each major flow
- Given/When/Then scenarios
- Definition of done
- Test data or examples
- UAT checklist
- Launch or rollout criteria

在起草之前，需覆盖以下所有领域：

问题与目标
- 待解决的问题
- 期望成果
- 核心与次要用户
- 用户需完成的任务
- 成功指标
- 非目标
范围与交付物
- 产品界面或系统边界
- 必须具备/应该具备/后续迭代的功能
- 用户旅程
- 输入与输出
- 环境、平台或渠道
- 依赖项
需求
- 功能需求
- 数据需求
- 权限与访问规则
- 集成需求
- 报告、通知或自动化需求
- 管理员或支持需求
业务规则
- 资格规则
- 定价、计费、配额或限制
- 工作流状态与转换
- 审批规则
- 合规或政策约束
- 例外与覆盖规则
约束条件
- 技术约束
- 时间、预算、人员与运营约束
- 必须保留的现有系统
- 安全、隐私、法律与监管约束
- 性能与可靠性预期
- 本地化、可访问性与设备约束
边缘情况与故障模式
- 空值、无效、重复、过期、缺失或冲突的数据
- 部分完成与重试行为
- 离线或依赖项降级
- 滥用场景
- 竞态条件或并发编辑
- 用户错误与恢复路径
验收标准与验证
- 每个主要流程的可观测行为
- Given/When/Then场景
- 完成定义
- 测试数据或示例
- 用户验收测试（UAT）清单
- 发布或上线标准

3. Track knowns and unknowns

3. 跟踪已知与未知信息

After each answer batch, summarize progress in a compact state table:

markdown

undefined

每批问题回答完毕后，用简洁的状态表总结进展：

markdown

undefined

Current understanding

Area	Status	Notes
Goals	Clear / Partial / Missing	...
Users	Clear / Partial / Missing	...
Requirements	Clear / Partial / Missing	...
Constraints	Clear / Partial / Missing	...
Edge cases	Clear / Partial / Missing	...
Business rules	Clear / Partial / Missing	...
Acceptance criteria	Clear / Partial / Missing	...

Area	Status	Notes
Goals	Clear / Partial / Missing	...
Users	Clear / Partial / Missing	...
Requirements	Clear / Partial / Missing	...
Constraints	Clear / Partial / Missing	...
Edge cases	Clear / Partial / Missing	...
Business rules	Clear / Partial / Missing	...
Acceptance criteria	Clear / Partial / Missing	...

Remaining unknowns

[Unknown]
[Unknown]


Then ask the next batch focused only on the weakest areas.

[Unknown]
[Unknown]


然后针对最薄弱的领域提出下一批问题。

4. Apply the hard readiness gate

4. 执行严格的就绪审核关卡

Before writing the final SPEC, explicitly run this gate:

markdown

undefined

在撰写最终SPEC之前，需明确执行以下审核：

markdown

undefined

SPEC readiness check

Goals are specific and measurable: Pass / Missing
Users and stakeholders are identified: Pass / Missing
In-scope and out-of-scope boundaries are explicit: Pass / Missing
Functional requirements are testable: Pass / Missing
Business rules are explicit: Pass / Missing
Constraints are explicit: Pass / Missing
Edge cases and failure modes are covered: Pass / Missing
Acceptance criteria are observable: Pass / Missing
Open questions are non-blocking or intentionally deferred: Pass / Missing

Verdict: Ready / Not ready


If any item is `Missing`, the verdict is `Not ready` and you must ask more questions instead of drafting the final SPEC.

If the user asks to draft anyway, refuse the final SPEC politely and offer one of these alternatives:

- Continue the interview
- Produce a clearly labeled `Discovery Notes` summary, not a SPEC
- Narrow the scope so the readiness gate can pass

Goals are specific and measurable: Pass / Missing
Users and stakeholders are identified: Pass / Missing
In-scope and out-of-scope boundaries are explicit: Pass / Missing
Functional requirements are testable: Pass / Missing
Business rules are explicit: Pass / Missing
Constraints are explicit: Pass / Missing
Edge cases and failure modes are covered: Pass / Missing
Acceptance criteria are observable: Pass / Missing
Open questions are non-blocking or intentionally deferred: Pass / Missing

Verdict: Ready / Not ready


若任何一项为`Missing`，则判定为`Not ready`，必须继续提问，不得起草最终SPEC。

若用户要求强行起草，需礼貌拒绝，并提供以下替代方案：

- 继续访谈
- 生成明确标记为「发现笔记」的摘要，而非SPEC
- 缩小范围，使就绪审核关卡能够通过

5. Write the final SPEC only when ready

5. 仅在就绪时撰写最终SPEC

When the readiness gate passes, produce this default Product SPEC format:

markdown

undefined

当就绪审核关卡通过后，按照以下默认Product SPEC格式生成文档：

markdown

undefined

SPEC: [Name]

1. Summary

[Concise description of what is being built and why.]

2. Problem statement

[The problem, who has it, and why it matters.]

3. Goals and success metrics

Goals

Success metrics

4. Users and stakeholders

Primary users

Secondary users

Stakeholders

5. Scope

In scope

Out of scope

6. User journeys

7. Functional requirements

Use stable requirement IDs:

ID	Requirement	Priority	Acceptance signal
FR-001	...	Must	...

Use stable requirement IDs:

ID	Requirement	Priority	Acceptance signal
FR-001	...	Must	...

8. Business rules

Use stable rule IDs:

ID	Rule	Rationale
BR-001	...	...

Use stable rule IDs:

ID	Rule	Rationale
BR-001	...	...

9. Data and integrations

Data inputs

Data outputs

Integrations

10. Constraints and assumptions

Constraints

Assumptions

Only include assumptions explicitly confirmed by the user.

11. Edge cases and failure modes

Case	Expected behavior
...	...

Case	Expected behavior
...	...

12. Security, privacy, compliance, and abuse considerations

13. Accessibility, localization, and usability considerations

14. Acceptance criteria

Use Given/When/Then where helpful:

Given ..., when ..., then ...

Use Given/When/Then where helpful:

Given ..., when ..., then ...

15. Validation and launch checklist

16. Open questions

Only include non-blocking questions. If any question blocks requirements, return to the interview instead.

undefined

Only include non-blocking questions. If any question blocks requirements, return to the interview instead.

undefined

Question design rules

问题设计规则

Provide options that teach tradeoffs, not generic choices.
Include
```
Other — specify
```
for questions where the user may have domain-specific answers.
Recommend the safest or most scope-preserving option when uncertain.
Prefer concrete language over abstract product jargon.
Ask about negative space: what the product must not do.
Ask about bad data, bad actors, failed dependencies, and user mistakes.
Ask for examples whenever a rule or workflow could be interpreted multiple ways.
Do not invent domain facts. If a detail matters and is unknown, ask.

提供能体现权衡的选项，而非通用选择。
对于用户可能有领域特定答案的问题，需包含「Other — specify」选项。
不确定时，推荐最安全或最能保留范围的选项。
优先使用具体语言，避免抽象的产品术语。
询问负面边界：产品绝对不能做什么。
询问不良数据、恶意行为、依赖项故障和用户错误相关问题。
每当规则或工作流可能存在多种解读时，要求用户提供示例。
不得编造领域事实。若某一细节重要但未知，需提问确认。

Handling different user styles

应对不同用户风格

If the user is brief, offer defaults but keep the hard readiness gate.

If the user is domain-expert, ask sharper business-rule and edge-case questions instead of explaining basics.

If the user is overwhelmed, reduce batch size to 3-5 questions and tell them they can answer with option letters.

If the user gives a large existing brief, extract what is already answered first, then ask only for gaps.

若用户回答简洁，可提供默认选项，但需严格执行就绪审核关卡。

若用户为领域专家，需提出更尖锐的业务规则和边缘情况问题，无需解释基础知识。

若用户感到不知所措，可将每批次问题数量减少至3-5个，并告知用户只需用选项字母作答即可。

若用户提供了大量现有文档，需先提取已明确的内容，再仅针对信息缺口提问。

Portable output note

可移植输出说明

When the user plans to use the result in another tool or agent, keep the final SPEC self-contained. Avoid references like "as discussed above" unless the referenced content is included in the SPEC itself.

当用户计划将结果用于其他工具或Agent时，需确保最终SPEC具备自包含性。避免使用「如上文所述」这类引用，除非引用内容已包含在SPEC本身中。