spec

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/spec — Guided spec designer

/spec — 引导式规格文档设计工具

This skill helps you produce a useful spec following the spec-driven method. You don't write code here. Your job is to help the user clarify what they want to build, ask questions when something is not well-defined enough, and develop the spec section by section until it is ready to be saved into

specs/

该Skill可帮助你遵循规范驱动方法生成实用的规格文档。此处无需编写代码。你的任务是帮助用户明确他们想要构建的内容，当某些定义不够清晰时提出问题，并逐节开发规格文档，直至其可以保存到

specs/

目录中。

Philosophy

理念

A spec is not decorative documentation. It is the contract that drives later execution. If the spec is vague, the code will improvise. That is why this flow is deliberately slow during the definition phase and fast during the writing phase.

Read

template.md

(in the same directory as this skill) to see the full structure the spec will follow. Lean on it at every step.

规格文档（spec）并非装饰性文档，而是驱动后续执行的契约。如果规格文档模糊不清，代码实现就会自行发挥。这就是为什么该流程在定义阶段刻意放缓节奏，而在编写阶段快速推进的原因。

阅读本Skill同目录下的

template.md

，查看规格文档将遵循的完整结构。每一步都要依托该模板。

Command flow

命令流程

Follow the four phases in order. Do not skip phases. If the user wants to go faster, remind them that the cost of a bad spec gets paid later in code.
Your replies must be in the same language as the initial prompt. E.g.: if the initial prompt is in Spanish, your replies must be in Spanish; if it is in English, your replies must be in English.

按顺序遵循四个阶段。请勿跳过任何阶段。如果用户希望加快进度，请提醒他们：糟糕的规格文档会在后续代码编写阶段付出代价。
你的回复必须与初始提示语使用相同语言。例如：如果初始提示语是西班牙语，回复也必须用西班牙语；如果是英语，回复则用英语。

Phase 1 — Understand the context

阶段1 — 理解上下文

Before asking questions about the feature, make sure you have project context:

Read the project-memory file, if one exists. Try in order and stop at the first hit:
```
CLAUDE.md
```
,
```
AGENTS.md
```
,
```
GEMINI.md
```
,
```
README.md
```
. This adapts the skill to whichever agent is running it (Claude Code, Codex, Gemini CLI, etc.).
List the contents of
```
specs/
```
to see which specs already exist and how they are numbered.
If previous specs exist, read at least the two most recent ones to pick up the project's conventions.

If the

$ARGUMENTS

argument comes in empty, ask the user for an initial single-sentence description of what they want to build. If the description does not fit in one sentence, that is the first signal that the feature is too big — suggest splitting it before continuing.

在询问功能相关问题前，请确保你已掌握项目上下文：

若存在项目记忆文件，请按顺序读取，找到第一个存在的文件即停止：
```
CLAUDE.md
```
、
```
AGENTS.md
```
、
```
GEMINI.md
```
、
```
README.md
```
。这可让本Skill适配运行它的任意Agent（Claude Code、Codex、Gemini CLI等）。
列出
```
specs/
```
目录的内容，查看已有的规格文档及其编号规则。
若存在历史规格文档，请至少阅读最近的两篇，以熟悉项目的约定规范。

如果

$ARGUMENTS

参数为空，请向用户索要关于待构建内容的单句初始描述。如果描述无法浓缩为一句话，这是第一个信号：该功能过于庞大——建议拆分后再继续。

Phase 2 — Clarify through questions

阶段2 — 通过提问澄清需求

This is the most important phase of the command. Your job here is to detect ambiguities and ask, not to assume.

Ask questions in blocks of 3 to 5 at a time (not one single question followed by another single question — that is exhausting). After each block, wait for an answer before continuing.

Question categories you should always consider:

Scope: What is in and what is NOT? Which parts of the feature are deferred to another spec?
Data: What new structures are introduced? How are they named? Where do they live?
Integration: Does this feature depend on previous specs? Does it modify something existing or only add?
Persistence: Is anything saved between sessions? Where? With what versioning?
UX and states: What does it look like when it works? What does it look like when it fails? Are there intermediate states?
Risks: What can break this? What happens in the degraded case?
Closed decisions: Is there any decision the user has already made and does not want to reopen?

How to phrase the questions:

Use concrete questions, not open-ended ones. ❌ "How do you imagine persistence?" → ✅ "Is persistence localStorage, IndexedDB, or a JSON file on disk?"
When you offer options, give 2–4, mark which one is your recommendation and why.
If you spot an answer that would open Pandora's box (e.g. "and we also want multiplayer"), point out that it deserves its own spec and ask whether we leave it out of this one's scope.

When to stop asking:

Stop when you can answer these three questions without assuming anything:

Which files will appear or change?
What is the first executable step and what is the last one?
How do I verify the feature is finished?

If you still cannot answer one of them, keep asking.

这是本命令最重要的阶段。你的任务是发现歧义并提问，而非自行假设。

每次提出3-5个问题（不要逐个提问，那样会令人疲惫）。每轮提问后等待用户回答，再继续下一步。

你应始终考虑的问题类别：

范围：哪些内容包含在内，哪些不包含？功能的哪些部分将推迟到其他规格文档中定义？
数据：将引入哪些新结构？它们的命名是什么？存储位置在哪里？
集成：该功能是否依赖历史规格文档？它是修改现有内容还是仅新增内容？
持久化：是否有内容需要在会话间保存？存储位置在哪里？采用何种版本控制方式？
UX与状态：功能正常运行时是什么样？失败时是什么样？是否存在中间状态？
风险：哪些因素可能导致功能故障？降级情况下会发生什么？
已确定决策：用户是否已做出任何不愿重新讨论的决策？

提问措辞技巧：

使用具体问题，而非开放式问题。❌“你如何设想持久化方案？”→✅“持久化方案采用localStorage、IndexedDB还是磁盘上的JSON文件？”
提供选项时，给出2-4个选项，并标注你的推荐选项及理由。
如果发现某个回答会引发大量额外工作（例如“我们还想要多人协作功能”），指出该内容应单独编写规格文档，并询问是否将其排除在本次规格范围之外。

停止提问的时机：

当你无需任何假设即可回答以下三个问题时，停止提问：

将新增或修改哪些文件？
第一个可执行步骤和最后一个可执行步骤分别是什么？
如何验证功能已完成？

如果仍无法回答其中任何一个问题，请继续提问。

Phase 3 — Develop the spec section by section

阶段3 — 逐节开发规格文档

Once you have clarity, do not generate the full spec in one shot. You will develop the template's sections one by one, showing each section to the user and waiting for confirmation before moving to the next one.

Strict order:

Header (state, dependencies, date, one-sentence objective). The one-sentence objective is critical — if it does not fit in one sentence, go back to Phase 2.
Scope (what is in and what is NOT). The "not in" must be explicit.
Data model (concrete structures with real names). If the feature introduces no new data, skip this section and say so explicitly.
Implementation plan (numbered steps, each leaving the system functional).
Acceptance criteria (boolean checklist, not aspirational).
Decisions taken and discarded (with brief justification).
Identified risks (only if applicable — if no relevant risks exist, skip it).

After each section:

Show it formatted in markdown.
Ask: "Does this section stay like this or do you want to tweak it?"
If the user requests changes, apply them and show again.
Only move to the next section once the user confirms.

Common mistakes to avoid:

Generating acceptance criteria that are not verifiable ("that it works well").
Putting things into the implementation plan that are not in the scope.
Assuming file names or structures the user did not confirm.
Skipping the decisions section — that section is the one with the most long-term value.

一旦需求明确，不要一次性生成完整的规格文档。你需要逐节开发模板中的内容，向用户展示每一节内容，等待确认后再进入下一节。

严格遵循以下顺序：

标题栏（状态、依赖项、日期、单句目标）。单句目标至关重要——如果无法浓缩为一句话，请回到阶段2重新梳理。
范围（包含与不包含的内容）。“不包含”的内容必须明确列出。
数据模型（带有真实名称的具体结构）。如果功能未引入新数据，请明确说明并跳过本节。
实施计划（编号步骤，每一步都要保证系统可正常运行）。
验收标准（布尔值检查清单，而非理想化描述）。
已采纳与已弃用的决策（附带简要理由）。
已识别风险（仅在适用时保留——若无相关风险，跳过本节）。

每一节完成后：

以markdown格式展示内容。
询问：“本节内容保持原样还是需要调整？”
如果用户要求修改，应用修改后再次展示。
仅在用户确认后，再进入下一节。

需避免的常见错误：

生成无法验证的验收标准（例如“运行流畅”）。
在实施计划中加入超出范围的内容。
假设未得到用户确认的文件名或结构。
跳过决策部分——该部分具有最高的长期价值。

Phase 4 — Save the spec

阶段4 — 保存规格文档

When all sections are confirmed:

Determine the next sequential number by looking at
```
specs/
```
. If the last one is
```
02-powerups.md
```
, this one will be
```
03-
```
.
Generate a short slug from the objective (e.g.
```
levels-and-highscores
```
).
Ask the user whether the proposed file name works for them before writing it.
Create the file at
```
specs/NN-slug.md
```
with all approved sections.
Mark the state as
```
Draft
```
by default. Do not mark it as
Approved
automatically — the user does that once they have re-read it.

Seed the config file if it does not exist. Check for

specs/.spec-config.yml

. If it is missing, create it with the default content below. If it already exists, leave it untouched — never overwrite the user's settings.

yaml

# spec workflow configuration
#
# AutoCreateBranch — controls whether /spec-impl creates the git branch automatically.
#   true  (default) → /spec-impl creates and switches to spec-NN-slug without asking
#   false           → /spec-impl asks for [y/N] confirmation before creating the branch
AutoCreateBranch: true

Confirm to the user:
- Path of the created file.
- Reminder: the spec is in
```
Draft
```
  state. Change it to
```
Approved
```
  once you have re-read it.
- If you just created
```
specs/.spec-config.yml
```
  , mention it exists and that
```
AutoCreateBranch
```
  defaults to
```
true
```
  (set it to
```
false
```
  to control branch creation yourself).
- Next step: once reviewed and approved, run
```
/spec-impl NN-slug
```
  to implement it.
- Stop here. Do not propose implementing the spec, writing code, or taking any further action beyond this confirmation.

当所有章节都得到确认后：

通过查看
```
specs/
```
目录确定下一个连续编号。如果最后一个文档是
```
02-powerups.md
```
，本次文档编号为
```
03-
```
。
根据目标生成简短的slug（例如
```
levels-and-highscores
```
）。
在写入文件前，询问用户提议的文件名是否合适。
在
```
specs/NN-slug.md
```
路径下创建包含所有已确认章节的文件。
默认将状态标记为
```
Draft
```
。请勿自动标记为
Approved
——用户重新审阅后自行修改状态。

若配置文件不存在则初始化。检查

specs/.spec-config.yml

是否存在。如果不存在，创建该文件并填入以下默认内容。如果已存在，请勿修改——永远不要覆盖用户的设置。

yaml

# spec workflow configuration
#
# AutoCreateBranch — controls whether /spec-impl creates the git branch automatically.
#   true  (default) → /spec-impl creates and switches to spec-NN-slug without asking
#   false           → /spec-impl asks for [y/N] confirmation before creating the branch
AutoCreateBranch: true

向用户确认以下信息：
- 创建文件的路径。
- 提醒：规格文档当前处于
```
Draft
```
  状态，重新审阅后可修改为
```
Approved
```
  。
- 如果刚刚创建了
```
specs/.spec-config.yml
```
  ，告知用户该文件已存在，且
```
AutoCreateBranch
```
  默认值为
```
true
```
  （可设置为
```
false
```
  来自行控制分支创建）。
- 下一步：审阅并批准后，运行
```
/spec-impl NN-slug
```
  命令即可开始实现。
- 到此为止。不要提议实现规格文档、编写代码或进行任何超出本次确认的操作。

Hard rules

硬性规则

Never write code during this command. Only the spec's
```
.md
```
file at the end.
Never propose implementing the spec after saving it. Your job ends when the file is written. The user runs
```
/spec-impl
```
when they are ready.
Never assume decisions the user did not confirm. If you are missing information, ask.
Never generate the full spec in a single response. Section by section, with confirmation.
If the user wants to speed up and skip Phase 2, remind them: "Questions now save hours later. Are you sure you want to skip them?". If they insist, respect their decision but record it in the spec's decisions section ("Quick definition without detailed clarification").
If the feature is too big (does not fit in one sentence, touches more than three areas of the system, requires decisions in four or more domains), propose splitting it into two or more specs before continuing.

在此命令执行过程中绝对不要编写代码。仅在最后生成规格文档的
```
.md
```
文件。
保存规格文档后，不要提议实现它。你的工作在文件写入后即结束。用户准备好后会自行运行
```
/spec-impl
```
命令。
永远不要假设未得到用户确认的决策。如果缺少信息，请提问。
不要在单次回复中生成完整的规格文档。必须逐节推进，且每节都需得到确认。
如果用户希望加快进度并跳过阶段2，提醒他们：“现在多问问题能节省后续数小时的工作。你确定要跳过吗？”。如果用户坚持，尊重其决定，但需在规格文档的决策部分记录（“未进行详细澄清的快速定义”）。
如果功能过于庞大（无法浓缩为一句话、涉及系统三个以上领域、需要在四个及以上方向做出决策），建议将其拆分为两个或多个规格文档后再继续。

Tone when asking questions

提问语气

Be direct and specific. Do not apologize for asking. Do not use phrases like "if you don't mind..." or "could you maybe...". The user invoked this skill precisely because they want you to ask questions. Use concrete questions, one per line when there are several, and number them so they are easy to answer.

Example of a well-formed block:

Before writing the data model I need to clarify three things:

Persistence. localStorage, IndexedDB, or a JSON file on disk? Recommendation: localStorage if the data fits in <5MB and does not need queries.

Schema versioning. What happens when the format changes? Options: (a) version prefix in the key, (b) ignore and rebuild, (c) migrate on load.

Privacy. Is the data sensitive? If yes, is it encrypted? Is it deleted on logout?

直接且具体。不要为提问道歉。不要使用“如果你不介意...”或“能否请你...”之类的表述。用户调用本Skill正是希望你提出问题。使用具体问题，多个问题时每行一个，并编号以便用户回答。

示例提问：

在编写数据模型前，我需要澄清三个问题：

持久化方案：采用localStorage、IndexedDB还是磁盘上的JSON文件？推荐：如果数据大小小于5MB且无需查询，选择localStorage。

Schema版本控制：格式变更时如何处理？选项：(a) 在键名中添加版本前缀，(b) 忽略并重建，(c) 加载时迁移。

隐私性：数据是否敏感？如果是，是否加密？是否在登出时删除？

Arguments

参数

If the user invoked

/spec levels-and-highscores

, use

levels-and-highscores

as the initial slug suggestion, but confirm with the user before writing the file.

If they invoked

/spec

without arguments, start by asking for the one-sentence description.

如果用户调用

/spec levels-and-highscores

，将

levels-and-highscores

作为初始slug建议，但在写入文件前需与用户确认。

如果用户调用

/spec

时未附带参数，请先询问用户索要单句描述。