discovery-interview

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Discovery Interview

调研访谈

Turn vague ideas into an implementable spec through ordered phases and targeted questions.

通过有序阶段和针对性问题，将模糊的想法转化为可落地的规格说明。

Non-negotiables (do not skip)

硬性要求（请勿跳过）

Run all 7 phases in order below. Do not jump to the spec early.
Minimum 10–15 questions across categories for any real project. Never treat 3–5 questions as enough.
Every AskUserQuestion must include an option for uncertainty (e.g. “I’m not sure” / “Research this”).
At least one research loop for any non-trivial project (user accepts research → WebSearch/WebFetch or agent, then follow-up questions).
Completeness check (Phase 5) must pass before writing the spec. If anything is missing, ask more; do not write the spec yet.
Summarize your understanding and get user confirmation before generating the spec file.
Write the spec to
```
docs/specs/YYYY-MM-DD-<name>.md
```
using SPEC_TEMPLATE.md. Create
```
docs/specs/
```
if it does not exist.

按顺序完成以下全部7个阶段，不要提前开始撰写规格说明。
任何实际项目都需要跨类别提出至少10-15个问题，绝对不能认为3-5个问题就足够。
每个AskUserQuestion都必须包含不确定选项（例如“我不确定”/“调研这个问题”）。
任何非 trivial 项目都需要至少一轮调研（用户同意调研→执行WebSearch/WebFetch或调用Agent，再跟进后续问题）。
撰写规格说明前必须通过第5阶段的完整性检查，如果有信息缺失，先补充提问，暂不撰写规格说明。
生成规格说明文件之前，需要先总结你对需求的理解并获得用户确认。
参考SPEC_TEMPLATE.md将规格说明写入
```
docs/specs/YYYY-MM-DD-<名称>.md
```
路径，如果
```
docs/specs/
```
目录不存在则创建。

Process overview

流程概览

Seven phases, in order.

共七个阶段，需按顺序执行。

Phase 1: Initial orientation (2–3 questions)

阶段1：初始定位（2-3个问题）

Use AskUserQuestion to nail:

What problem are you solving?
Who will use this?
New build vs improving something existing?

Infer project type (guides which categories matter most): Backend/API · Web · CLI · Mobile · Full-stack · Script/automation · Library/SDK.

使用AskUserQuestion明确以下信息：

你要解决什么问题？
产品的使用人群是谁？
是全新构建还是优化现有产品？

推断项目类型（指导后续重点关注的类别）：Backend/API · Web · CLI · Mobile · 全栈 · 脚本/自动化 · 库/SDK。

Phase 2: Category deep dive

阶段2：分类深度调研

Use CATEGORIES.md. For each relevant category:

Ask at least 2 questions (typically 2–4) via AskUserQuestion.
If the user is unsure, offer research (Phase 3 pattern).
Educate when needed so decisions are informed.
Track decisions internally.

参考CATEGORIES.md，针对每个相关类别：

通过AskUserQuestion提出至少2个问题（通常为2-4个）。
如果用户不确定，提供调研选项（参考阶段3模式）。
必要时提供相关信息科普，确保用户做出的决策是信息充分的。
内部记录所有决策内容。

Phase 3: Research loops

阶段3：调研循环

On uncertainty or knowledge gaps, use AskUserQuestion first:

AskUserQuestion(
  question: "[Topic] has several viable approaches with different tradeoffs. Research?",
  options: [
    {label: "Yes, research", description: "Compare options and tradeoffs"},
    {label: "No", description: "I know what I want"},
    {label: "Brief only", description: "Short overview, no deep dive"}
  ]
)

If the user chooses research: WebSearch/WebFetch (or an agent), then continue with informed questions. Do not skip follow-up questions after research.

遇到不确定的内容或知识空白时，优先使用AskUserQuestion询问：

AskUserQuestion(
  question: "[主题]存在多种可行方案，各有优劣，是否需要调研？",
  options: [
    {label: "是，需要调研", description: "对比不同方案及其权衡点"},
    {label: "不需要", description: "我明确知道我想要什么"},
    {label: "仅需简介", description: "简短概述即可，不需要深入调研"}
  ]
)

如果用户选择调研：执行WebSearch/WebFetch（或调用Agent），之后继续提出信息充分的针对性问题，调研后不要跳过后续提问环节。

Phase 4: Conflict resolution

阶段4：冲突解决

When requirements conflict, surface the tension with AskUserQuestion. Options must include: favor constraint A, favor B, or explore alternatives (often with research).

Example pattern (latency vs cost — adapt the domain):

AskUserQuestion(
  question: "Tension: sub-second dashboard updates for everyone vs. smallest cloud tier. Real-time fan-out usually needs more than one small instance. Optimize for what first?",
  options: [
    {label: "Freshness", description: "Higher cost or fewer concurrent users for near-real-time"},
    {label: "Cost", description: "Slower refresh (polling/batch) on minimal infra"},
    {label: "Explore alternatives", description: "e.g. SSE + caching — research before choosing"}
  ]
)

Typical tensions: simple vs rich; real-time vs cheap infra; secure vs frictionless UX; flexible vs fast; ship fast vs future-proof.

当需求存在冲突时，通过AskUserQuestion向用户呈现矛盾点，选项必须包含：优先满足约束A、优先满足约束B、探索替代方案（通常需要配合调研）。

示例模式（延迟 vs 成本——可适配不同领域）：

AskUserQuestion(
  question: "存在冲突：为所有用户提供亚秒级的仪表盘更新 vs 使用最小配置的云服务实例。实时广播通常需要不止一个小型实例支撑，优先优化哪个方向？",
  options: [
    {label: "数据新鲜度", description: "更高的成本或更少的并发用户数，实现近实时更新"},
    {label: "成本", description: "在最小基础设施上运行，采用轮询/批量更新的方式，刷新速度更慢"},
    {label: "探索替代方案", description: "例如SSE+缓存——决策前先调研可行性"}
  ]
)

常见冲突点：简洁 vs 功能丰富；实时性 vs 基础设施成本；安全 vs 低摩擦UX；灵活性 vs 交付速度；快速上线 vs 长期可扩展性。

Phase 5: Completeness check

阶段5：完整性检查

Do not write the spec until all of the following are satisfied:

Area	Must have
Problem	Clear problem statement, success metrics, stakeholders
UX	User journey, core actions, error/edge handling
Technical	Data model, integrations, scale, security, deployment
Decisions	Tradeoffs explicitly chosen; no silent TBDs; user confirms understanding

If something is missing: name the gap, run targeted Phase 2 questions, then re-run this table.

满足以下所有条件后，才可以撰写规格说明：

领域	必备内容
问题	清晰的问题描述、成功指标、利益相关方
UX	用户旅程、核心操作、错误/边缘场景处理
技术	数据模型、集成能力、扩展性、安全性、部署方式
决策	明确选择的权衡点、无未声明的待确定项、用户确认理解所有决策

如果有信息缺失：说明缺失的内容，针对性执行阶段2的提问，之后重新核对本表的要求。

Phase 6: Spec generation

阶段6：规格说明生成

Summarize understanding; get confirmation.
Generate
```
docs/specs/YYYY-MM-DD-<name>.md
```
from SPEC_TEMPLATE.md.

总结对需求的理解，获得用户确认。
基于SPEC_TEMPLATE.md生成
```
docs/specs/YYYY-MM-DD-<名称>.md
```
文件。

Phase 7: Implementation handoff

阶段7：实现交接

AskUserQuestion for next steps:

Start implementation → User can say they want the spec implemented.
Plan implementation → Plan agent or
```
/create_plan
```
if available.
Review spec / done → Confirm path and that the spec reflects what was agreed.

通过AskUserQuestion确认下一步动作：

开始实现 → 用户可以要求基于该规格说明进行功能实现。
规划实现方案 → 如果有可用的规划Agent或
```
/create_plan
```
能力，生成实现计划。
评审规格说明/完成 → 确认后续路径，确认规格说明符合双方约定的内容。

Integrated flow (one pass)

完整流程（单次执行）

Orientation → deep dive categories for the project type → if unsure on stack/approach, research loop → if two goals conflict, conflict resolution → completeness table green → confirm summary → write spec file → handoff question.

初始定位 → 针对项目类型做分类深度调研 → 对技术栈/方案存疑时执行调研循环 → 目标冲突时执行冲突解决 → 完整性检查全部通过 → 确认需求总结 → 撰写规格说明文件 → 交接提问。

Anti-patterns

反模式

Writing the spec after a handful of questions.
Skipping research when the user is guessing about tools or scale.
Leaving contradictions unresolved.
Writing the spec before the completeness check passes.

仅提问少量问题就开始撰写规格说明。
用户对工具或规模没有明确认知时跳过调研环节。
未解决需求中的矛盾点。
未通过完整性检查就开始撰写规格说明。