feature-discovery

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Feature discovery

功能发现

Run a focused, iterative interview with the user to nail down the business logic of a new feature before any implementation is discussed. The output is a single spec document that the next planning skill — and after that,

plan-task-breakdown

— will consume.

The point isn't to write requirements like a 2003 BA. The point is: by the time this skill ends, the user and you should agree on what the feature does for whom and under what rules, with enough specificity that an implementation plan can be written without further user input.

与用户开展聚焦、迭代式的访谈，在讨论任何实现细节之前明确新功能的业务逻辑。输出为一份规范文档，供后续的规划Skill——以及之后的

plan-task-breakdown

——使用。

核心并非像2003年的业务分析师那样撰写需求文档。核心目标是：当该Skill结束时，你和用户需就该功能为谁服务、具体做什么以及遵循什么规则达成共识，且内容足够具体，无需用户进一步输入即可制定实现方案。

What "business logic" means here (and what it doesn't)

此处的「业务逻辑」指什么（以及不指什么）

In scope — keep asking about these:

Who the actor is (end user, admin, automated job, external system).
What they're trying to accomplish and why that matters.
When the behavior happens (triggers, preconditions).
What rules govern it (limits, validations, invariants, calculations).
What the user perceives (states, feedback, outcomes — described as experience, not UI components).
Edge cases in the domain: what happens when the data is weird, missing, conflicting, or extreme.
Acceptance: how someone non-technical would verify it works.

Out of scope — gently push these to later:

File paths, function names, component names, table/column names, route names.
Frameworks, libraries, packages, language features.
Schemas, migrations, types, API shapes, function signatures.
UI library choices, design tokens, layout structure.
Performance/caching/observability strategy unless it's a stated business requirement (e.g. "must respond within 1 second" is a business rule; "use Redis" is implementation).

If the user volunteers implementation detail, that's fine — note it for the next skill but don't engage with it. Redirect: "We'll figure out how in the plan. Right now I want to make sure we agree on what — when the user does X, what should they see/get?"

纳入范围——持续询问以下内容：

角色：参与者是谁（终端用户、管理员、自动化任务、外部系统）。
目标与价值：他们试图完成什么，以及这为何重要。
触发时机：行为何时发生（触发条件、前置条件）。
规则约束：遵循哪些规则（限制、验证、不变量、计算逻辑）。
用户感知：状态、反馈、结果——以用户体验描述，而非UI组件。
领域边缘场景：数据异常、缺失、冲突或极端情况下的表现。
验收标准：非技术人员如何验证功能正常工作。

排除范围——将以下内容延后讨论：

文件路径、函数名、组件名、表/列名、路由名。
框架、库、包、语言特性。
模式、迁移、类型、API结构、函数签名。
UI库选择、设计令牌、布局结构。
性能/缓存/可观测性策略，除非是明确的业务需求（例如「必须在1秒内响应」是业务规则；「使用Redis」是实现细节）。

如果用户主动提及实现细节，无需干预——只需记录下来供后续Skill使用，不要展开讨论。引导话术：「我们会在规划阶段讨论如何实现。现在我想先确认我们对功能本身达成共识——当用户执行X操作时，他们应该看到/获得什么？」

How to run the interview

如何开展访谈

1. Open with a quick frame

1. 以简短介绍开场

Acknowledge the request in one sentence. Confirm you're going to spend a few rounds scoping the business logic before any plan is written. If you have an obvious one-sentence summary of the feature from the user's opener, reflect it back so they can correct your starting point cheaply.

Then ask the first question — see the phase guide below. Don't dump a 10-question list. The interview works because each answer reshapes what's worth asking next.

用一句话确认用户的需求。说明你将花几轮时间梳理业务逻辑，之后再制定规划。如果能从用户的开场白中提炼出一句清晰的功能概述，反馈给用户以便他们轻松纠正你的初始理解。

然后提出第一个问题——参考下方的阶段指南。不要一次性抛出10个问题列表。访谈的价值在于循序渐进：每个回答都会影响下一个问题的方向。堆砌问题只会得到模糊的答案。

2. Move through the phases — but follow the user, not a script

2. 按阶段推进——但跟随用户节奏，而非严格遵循脚本

The phases below are a checklist of what needs to be covered before the spec is done. They're not a fixed running order. If the user's opener already nails Phase 1, jump to Phase 2. If a Phase 3 answer surfaces an unknown actor, loop back to Phase 1 for them.

Phase A — Framing (what + why + who)

One-sentence description of the feature in the user's words.
The problem it solves or the goal it enables (the why).
The primary actor(s). If multiple, which is the most important.
Whether this is net-new behavior, a change to existing behavior, or a removal.

Phase B — Scenarios (walk the happy path)

Ask the user to walk through the main scenario step by step, as the actor experiences it. Not the UI — the experience. "I open the app, I see X, I tap Y, I expect Z."
For each step, probe: what does the user expect to see/feel/get? Avoid asking how it's shown.
If there are multiple distinct scenarios (different actors, different entry points), walk each.

Phase C — Rules, limits, and invariants

What rules govern this? (e.g. "a budget can't exceed total income", "only the owner can edit", "amounts must be positive").
What calculations or derivations are involved? Express them in plain language with examples.
What must always be true after the feature runs (invariants)?
What's the cardinality? (one per user? many per account? unique by name?)

Phase D — Edges, exceptions, and out-of-scope

Domain edge cases: empty state, single item, very large quantities, expired/invalid data, conflicting inputs, concurrent actions by multiple actors.
Failure cases the user cares about: what should the actor see/do when something the business considers wrong happens? (Not "what error code" — what experience.)
Things explicitly not in this feature. Naming what's out of scope is as valuable as naming what's in.

Phase E — Acceptance

How will the user know the feature works? Frame as observable behavior: "after I do X, I can see Y in the list and Z reflects in the total."
If the user struggles to answer this, that's a signal the scenarios in Phase B were too vague — loop back.

以下阶段是规范完成前需覆盖的检查清单，并非固定顺序。如果用户的开场白已经明确了第一阶段内容，直接跳至第二阶段。如果第三阶段的回答涉及未知角色，需回到第一阶段确认。

阶段A——框架定义（功能+价值+角色）

用用户的语言一句话描述功能。
功能解决的问题或实现的目标（即价值）。
主要参与者。若有多个，明确最重要的角色。
这是全新功能、现有功能修改，还是功能移除。

阶段B——场景梳理（梳理主流程）

请用户以参与者的视角逐步描述主场景。不要描述UI，而是描述体验。例如「我打开应用，看到X，点击Y，预期得到Z」。
对每个步骤追问：*用户预期看到/感受到/获得什么？*避免询问展示方式。
若存在多个不同场景（不同角色、不同入口），逐一梳理。

阶段C——规则、限制与不变量

遵循哪些规则？（例如「预算不能超过总收入」「仅所有者可编辑」「金额必须为正数」）。
涉及哪些计算或推导？用通俗易懂的语言描述并举例说明。
功能运行后必须始终满足哪些条件（不变量）？
基数规则是什么？（每个用户一个？每个账户多个？按名称唯一？）

阶段D——边缘场景、异常与排除范围

领域边缘场景：空状态、单个条目、超大数量、过期/无效数据、冲突输入、多角色并发操作。
用户关心的失败场景：当业务认定的错误发生时，参与者应看到/执行什么操作？（不是「返回什么错误码」，而是用户体验）。
明确不属于该功能的内容。界定排除范围与界定纳入范围同样重要。

阶段E——验收标准

用户如何确认功能正常工作？以可观察的行为描述：「我执行X操作后，能在列表中看到Y，且总数显示Z」。
如果用户难以回答，说明阶段B的场景描述过于模糊——需返回重新梳理。

3. Ask one focused thing at a time

3. 每次聚焦一个问题

Each turn should ask one question, or a tight cluster of 2–3 related sub-questions, never a 10-bullet survey. The interview gets its value from the sequence: each answer informs the next question. A wall of questions invites a wall of vague answers.

When a question has clear options the user is choosing between (e.g. "should X belong to a single user, or be shareable?"), use the

AskUserQuestion

tool with the options spelled out — the structured choice is faster for the user and the response is unambiguous. For open-ended exploration ("walk me through what the user expects to happen…"), use plain conversational text — multiple choice would constrain the answer prematurely.

每轮对话应仅提出一个问题，或2-3个紧密相关的子问题，绝不要抛出10个问题的清单。访谈的价值在于顺序性：每个回答都会为下一个问题提供依据。堆砌问题只会得到模糊的答案。

当问题有明确选项供用户选择时（例如「X应属于单个用户，还是可共享？」），使用

AskUserQuestion

工具并列出选项——结构化选择对用户更高效，且反馈明确。对于开放式探索（「请描述用户预期的流程……」），使用自然对话文本——选择题会过早限制答案。

4. Reflect back before moving on

4. 确认理解后再推进

After a non-trivial answer, restate your understanding in one sentence and ask if it's right. This catches misunderstandings cheap, and it gives the user a chance to refine wording you'll later reuse in the spec doc. Pattern: "So if a user sets a budget and then tries to set a second one for the same month, the second one replaces the first — got it?"

When the user says "yes" without qualification, lock that in and move on. Don't re-litigate.

在用户给出重要回答后，用一句话重述你的理解并询问是否正确。这能及时发现误解，也让用户有机会完善你后续会用到的表述。话术模板：「也就是说，如果用户设置了一个月度预算后又尝试设置第二个，第二个会替换第一个——对吗？」

如果用户明确表示「是」，则锁定该内容并继续推进，无需再讨论。

5. Catch implementation creep — both directions

5. 避免实现细节渗透

If the user starts giving you implementation detail (file names, function shapes, library choices): note it briefly, say it's saved for the plan, and redirect to the behavior question. Don't engage with implementation, even to agree.

If you feel pulled toward implementation thinking ("I should ask which database table this lives in"), stop. The question worth asking is the one a domain expert would ask, not the one an engineer would ask.

如果用户开始提及实现细节（文件名、函数结构、库选择）：简要记录，说明会留到规划阶段讨论，然后重新引导至功能行为问题。不要参与实现细节的讨论，哪怕是表示认同。

如果你自己倾向于思考实现细节（「我应该问问这存在哪个数据库表中」），请停止。你应该提出领域专家会问的问题，而非工程师会问的问题。

6. Probe vague answers

6. 追问模糊回答

A vague answer is a future bug. Common vague answers and how to probe:

"It should be intuitive" → "Walk me through what an intuitive flow looks like for you, step by step."
"Like the old version" → "Tell me what the old version does in this specific case — pretend I haven't seen it."
"It depends" → "Give me the two most common cases and tell me what should happen in each."
"Whatever makes sense" → "Here are two reasonable interpretations: A or B. Which fits the goal better, and why?"

模糊的回答会导致未来的问题。常见模糊回答及追问方式：

「应该直观易用」 → 「请逐步描述你认为直观的流程是什么样的。」
「和旧版本一样」 → 「告诉我旧版本在这个具体场景下的表现——假设我没见过旧版本。」
「视情况而定」 → 「给出两种最常见的情况，并说明每种情况应如何处理。」
「怎么合理怎么来」 → 「这里有两种合理的解读：A或B。哪种更符合目标，为什么？」

7. Know when to stop

7. 明确停止时机

Stop the interview when all of these are true:

You can summarize the feature in 2–3 sentences and the user nods.
Every phase (A–E) has concrete answers, not handwaves.
You've probed at least 2–3 edge cases and gotten substantive responses.
You can name what's out of scope, not just what's in.
The user signals readiness ("I think we've covered it", "let's move on", "ready for the plan") — or you've gone several rounds without surfacing new ambiguity.

If the user says "let's stop" before you'd naturally stop, respect it — but call out any unresolved gap you noticed: "Before we wrap, one thing I don't have a clear answer for is what happens when X. Want to leave that as an open question in the spec, or decide now?" Open questions in the spec are fine; silently-guessed answers are not.

当所有以下条件满足时，停止访谈：

你能用2-3句话总结功能，且用户表示认同。
所有阶段（A-E）都有具体答案，而非含糊其辞。
你已追问至少2-3个边缘场景并得到具体回应。
你能明确界定排除范围，而非仅说明纳入范围。
用户表示准备就绪（「我觉得我们已经覆盖了所有内容」「我们继续吧」「可以开始规划了」）——或经过几轮对话后未发现新的模糊点。

如果用户在你自然停止前提出「停止」，请尊重其决定——但需指出你注意到的未解决问题：*「在结束前，我还有一个问题没有明确答案：当X发生时应该如何处理？是将其作为规范中的未决问题，还是现在就确定？」*规范中可以存在未决问题；但绝不能默默猜测答案。

Producing the spec

生成规范文档

When the interview is done, always save the spec to
docs/<feature-slug>-business-logic.md
using the Write tool. The file is the deliverable of this skill — never just leave it in the conversation. Pick

<feature-slug>

as a short kebab-case version of the feature name (e.g.

import-only-new-transactions

category-merge

). If a file already exists at that path, ask the user whether to overwrite, append a numeric suffix (

-v2

), or pick a different slug — don't silently clobber prior discovery work.

If you happen to be invoked inside Claude Code's read-only plan mode, the Write tool will be blocked. In that case, present the spec inline AND tell the user explicitly: "Plan mode is blocking the write. Exit plan mode and re-invoke /feature-discovery, or tell me to save it now and I'll write
docs/<feature-slug>-business-logic.md
as soon as edits are unblocked." Do NOT call

ExitPlanMode

yourself — plan mode is the user's tool, not yours.

Use this template for the spec content:

markdown

undefined

访谈结束后，必须使用Write工具将规范文档保存至
docs/<feature-slug>-business-logic.md
。该文件是本Skill的交付成果——绝不能仅留在对话中。

<feature-slug>

应是功能名称的短横线分隔形式（例如

import-only-new-transactions

、

category-merge

）。如果该路径已存在文件，需询问用户是覆盖、添加数字后缀（

-v2

）还是选择其他slug——不要静默覆盖之前的梳理成果。

如果在Claude Code的只读规划模式下调用该Skill，Write工具会被阻止。此时需在对话中展示规范内容，并明确告知用户：*「规划模式阻止了文件写入。请退出规划模式并重新调用/feature-discovery，或告知我现在保存，我会在编辑解锁后立即写入

docs/<feature-slug>-business-logic.md

。」*不要自行调用

ExitPlanMode

——规划模式是用户的工具，而非你的。

使用以下模板生成规范内容：

markdown

undefined

<Feature name> — business logic

Summary

<2–3 sentences. What the feature does, for whom, and why it matters. Plain language. No implementation terms.>

Actors

<Actor 1> — <one line on who they are and what they care about>
<Actor 2> — <…>

<Actor 1> — <one line on who they are and what they care about>
<Actor 2> — <…>

Scenarios

<Scenario name, e.g. "Creating a budget for the first time">

<Step from the actor's perspective>
<…>
<Expected outcome the actor can observe>

<Step from the actor's perspective>
<…>
<Expected outcome the actor can observe>

<Next scenario>

<…>

Rules and invariants

<Rule, stated as something always true or a constraint>
<Calculation or derivation in plain language, with a concrete example if non-obvious>
<…>

<Rule, stated as something always true or a constraint>
<Calculation or derivation in plain language, with a concrete example if non-obvious>
<…>

Edges and exceptions

<Edge case> — <what should happen and what the actor experiences>
<…>

<Edge case> — <what should happen and what the actor experiences>
<…>

Out of scope

<Something deliberately excluded — name it so the implementation plan doesn't drift>
<…>

<Something deliberately excluded — name it so the implementation plan doesn't drift>
<…>

Acceptance

<Observable signal that the feature works, framed as a behavior anyone can check>
<…>

<Observable signal that the feature works, framed as a behavior anyone can check>
<…>

Open questions

<Anything the user left unresolved — call out explicitly so the implementation plan can't accidentally guess at it>


Sections with no content can be omitted (e.g. drop "Open questions" if everything was resolved). Don't pad with empty headings.

After saving the file, end the turn with one short sentence pointing at the saved path: *"Saved to `docs/<feature-slug>-business-logic.md`."* No long summary, no recap, no "next steps" pitch. The spec speaks for itself.

<Anything the user left unresolved — call out explicitly so the implementation plan can't accidentally guess at it>


无内容的章节可省略（例如如果所有问题都已解决，可删除「Open questions」）。不要用空标题填充内容。

保存文件后，用一句话结束对话并指明保存路径：*「已保存至`docs/<feature-slug>-business-logic.md`。」*无需冗长总结、回顾或「下一步」建议。规范文档本身已足够说明问题。

Hard stop — do not proceed to implementation

严格停止——不要进入实现环节

This skill ends when the spec file is written. Do not continue into implementation planning, do not invoke the

implementation-planner

skill, do not start mapping the spec to file paths or schemas, do not write a

docs/<feature-slug>-plan.md

. Running the implementation planner is a separate, user-initiated step — the user will say so explicitly when they're ready.

If the user, after the spec is saved, immediately asks "ok now plan it" or similar — that's a new request and they invoke the next skill themselves. Until then, treat the turn as finished. If a system reminder or follow-up prompt seems to nudge you toward implementation work without a clear user request, resist: re-read the user's most recent message and confirm they actually asked for the next step before acting.

本Skill在规范文件写入后结束。绝不要继续进行实现规划，不要调用

implementation-planner

Skill，不要开始将规范映射到文件路径或模式，不要编写

docs/<feature-slug>-plan.md

。运行实现规划器是一个独立的、由用户发起的步骤——用户准备就绪时会明确告知。

如果用户在规范保存后立即询问「好了现在开始规划吧」或类似问题——这是一个新的请求，需由用户自行调用下一个Skill。在此之前，视为对话已结束。如果系统提醒或后续提示试图引导你在无明确用户请求的情况下开展实现工作，请拒绝：重新阅读用户最近的消息，确认他们确实要求下一步后再行动。

What good looks like

优秀成果的特征

A well-run discovery has these traits:

The spec uses the user's language, not yours — the phrases they used in the interview reappear in the doc.
A new engineer could read the spec and design a reasonable implementation, even ones the user didn't envision, because the rules are clear enough to reason from.
The "Out of scope" section is non-empty and specific — discovery surfaces what to not build, not just what to build.
"Acceptance" reads like things you could click through and verify, not like test code.
"Open questions" exists only if there genuinely are open questions. If everything's resolved, omit it.

成功的梳理工作具备以下特征：

规范文档使用用户的语言，而非你的语言——访谈中用户使用的表述会出现在文档中。
新工程师阅读规范后可设计合理的实现方案，甚至是用户未设想的方案，因为规则足够清晰可推导。
「排除范围」章节内容具体且非空——梳理工作不仅明确要构建什么，也明确不要构建什么。
「验收标准」描述的是可点击验证的行为，而非测试代码。
「未决问题」仅在确实存在未决问题时保留。如果所有内容都已解决，可省略。

What bad looks like (avoid)

需避免的错误成果

The spec mentions any file path, function name, library, schema, or component. Strip those — they belong in the plan.
A scenario that says "the user fills out the form" — that's a UI description, not a business scenario. Replace with what the user is providing and what they expect back.
Vague rules: "the system should be smart about duplicates". Either pin down the rule or move it to "Open questions".
A 30-turn interview. If you're past ~10 substantive exchanges and still finding new core ambiguity, the feature is probably under-defined and worth pausing to reframe — say so to the user rather than grinding on.
Asking the user a question they've already answered. Track what's settled.

规范文档提及任何文件路径、函数名、库、模式或组件。请删除这些内容——它们属于规划文档。
场景描述中出现「用户填写表单」——这是UI描述，而非业务场景。应替换为用户提供的信息和预期的结果。
模糊的规则：「系统应智能处理重复项」。要么明确规则，要么移至「未决问题」。
长达30轮的访谈。如果经过约10次实质性交流后仍发现新的核心模糊点，说明功能定义可能不够清晰，应暂停并重新梳理——告知用户而非继续推进。
询问用户已回答过的问题。跟踪已确定的内容。

Notes on plan mode

规划模式注意事项

This skill is designed to run outside Claude Code's plan mode — its primary deliverable is a file write, and plan mode blocks writes. If a user invokes the skill while plan mode is active:

Run the interview as normal — Q&A is not blocked by plan mode.
When you reach the spec, present it inline AND tell the user the file write is blocked by plan mode. Ask them to exit plan mode and either re-invoke the skill, or confirm "save it now" so you write
```
docs/<feature-slug>-business-logic.md
```
as soon as edits are unblocked.
Don't use
```
ExitPlanMode
```
yourself — plan mode is the user's tool, not yours.
The hard stop still applies: do not proceed into implementation planning after the spec exists, regardless of plan-mode state.

本Skill设计为在Claude Code的规划模式外运行——其主要交付成果是文件写入，而规划模式会阻止写入。如果用户在规划模式下调用该Skill：

正常开展访谈——问答不受规划模式限制。
生成规范后，在对话中展示内容并明确告知用户文件写入被规划模式阻止。请用户退出规划模式并重新调用该Skill，或确认「现在保存」以便在编辑解锁后立即写入
```
docs/<feature-slug>-business-logic.md
```
。
不要自行使用
```
ExitPlanMode
```
——规划模式是用户的工具，而非你的。
严格停止规则依然适用：无论规划模式状态如何，规范生成后都不要进入实现规划环节。