spec

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/spec — Relentless Specification Workflow

/spec — 严谨的规格文档制定工作流

What

功能概述

Converts an idea into a written, versioned specification that both the developer and Claude explicitly agree on — before any planning or code. The contract:

Never assume. Every gap in the idea becomes a question. If Claude catches itself thinking "probably", "presumably", or "the usual way" — that thought is a question to ask, not a decision to make.
Relentless, but structured. Questions come in focused rounds (3–5 at a time) across nine dimensions — not one overwhelming dump, and not a single polite round that stops early.
Agreement is explicit. Specs have a status lifecycle: Draft → In Review → Approved. Implementation never starts from a Draft. Approval requires the developer to read the final document and say so.
Specs are files, not chat. Output persists to
```
docs/specs/<NNN>-<slug>.md
```
and survives the session. Plans, tests, and commits reference it.

将想法转化为书面的、带版本控制的规格文档，确保开发者与Claude在开始规划或编码前就达成明确共识。遵循以下契约：

绝不主观假设：想法中的任何信息缺口都会转化为问题。如果Claude发现自己在想“可能”“大概”或“按常规方式”——这种想法必须转化为问题提出，而非直接做出决策。
严谨且结构化：问题分轮次提出（每次3-5个），覆盖九个维度——既不会一次性抛出大量问题让人无从应对，也不会浅尝辄止只进行一轮提问。
共识明确化：规格文档有状态生命周期：草稿→审核中→已获批。绝不能基于草稿开始实现。获批需要开发者通读最终文档并明确确认。
规格以文件形式留存：输出结果持久化存储至
```
docs/specs/<NNN>-<slug>.md
```
，不会随会话结束而消失。后续的计划、测试和代码提交都会引用该文档。

When

适用场景

Any feature too big to describe completely in one sentence
New product or module ideas ("I want to add team workspaces")
Before
```
/plan
```
for non-trivial features — plan consumes the approved spec
When requirements feel fuzzy mid-implementation: stop,
```
/spec
```
, re-plan
Trigger phrases: "spec", "requirements", "PRD", "define the feature", "acceptance criteria"

Skip for: bug fixes, refactors, single-endpoint CRUD where the entity is obvious.

任何无法用一句话完整描述的功能
新产品或模块想法（例如“我想添加团队工作空间”）
为非 trivial 功能执行/plan之前——/plan工具会调用已获批的规格文档
开发过程中需求变得模糊时：暂停开发，使用/spec明确需求后重新规划
触发关键词：“spec”“需求”“PRD”“定义功能”“验收标准”

无需使用的场景：bug修复、代码重构、实体明确的单端点CRUD操作。

How

操作流程

Step 1: Capture and Restate

步骤1：捕获与重述

Take the raw idea and restate it in one paragraph: what Claude understood, in its own words. End with: "Is this the idea? What did I get wrong?" Do not begin questioning until the developer confirms the restatement — questioning the wrong idea wastes everyone's time.

记录原始想法，并用一段文字重述：Claude对想法的理解，用自己的语言表达。结尾附上：“这是否符合你的想法？我有哪些理解错误？”在开发者确认重述内容正确之前，不要开始提问——针对错误的想法提问只会浪费时间。

Step 2: Questioning Rounds

步骤2：多轮提问

Work through the nine dimensions in order. Each round: pick the 3–5 most load-bearing unanswered questions (answers that reshape later questions come first). Where the harness supports selectable options, present choices with trade-offs — and a recommendation — but the developer chooses; a recommendation is never silently applied.

#	Dimension	What to pin down
1	Problem & users	Who hurts today, how they work around it, what success looks like
2	Scope	What is IN this iteration, what is explicitly OUT, where the MVP line sits
3	Domain & data	Entities, relationships, lifecycle (create→archive→delete?), retention
4	API contract	Resources, endpoints, request/response shapes, pagination, versioning
5	Authorization	Who can do what, role/claim model, tenant boundaries
6	Edge cases & failure modes	Concurrency, duplicates, idempotency, partial failure, limits
7	Non-functionals	Expected volume, latency budget, growth assumptions
8	Integrations	External services, published events, webhooks, side effects
9	Acceptance criteria	Testable Given/When/Then for every behavior in scope

Rules of relentless questioning:

Record every answer in the draft spec immediately — answers are requirements, not conversation.
Challenge contradictions on the spot: "In round 1 you said X; this answer implies not-X. Which wins?"
"I don't know" is a legal answer → moves to Deferred Decisions with an explicit fallback the developer chooses now ("default to soft-delete until decided"). Silent deferral is forbidden.
A dimension is done when a follow-up round generates zero new questions for it.
The questioning phase is done when ALL nine dimensions are done. Do not stop because the conversation feels long — stopping early is how assumptions sneak in.

按顺序覆盖九个维度。每一轮：挑选3-5个最关键的未解决问题（那些答案会影响后续问题的优先提问）。如果工具支持可选选项，需呈现带有权衡分析的选项，并给出建议——但最终由开发者选择；绝不能默默应用建议。

序号	维度	需要明确的内容
1	问题与用户	当前受影响的用户群体、他们的临时解决方案、成功的衡量标准
2	范围	本次迭代包含的内容、明确排除的内容、MVP的边界
3	领域与数据	实体、关系、生命周期（创建→归档→删除？）、数据留存规则
4	API契约	资源、端点、请求/响应格式、分页、版本控制
5	权限控制	不同角色的操作权限、角色/声明模型、租户边界
6	边缘案例与故障模式	并发、重复请求、幂等性、部分失败、限制条件
7	非功能性需求	预期流量、延迟预算、增长假设
8	集成	外部服务、发布事件、Webhook、副作用
9	验收标准	每个范围内功能的可测试Given/When/Then场景

严谨提问规则：

立即将所有答案记录到草稿规格文档中——答案即需求，而非对话内容。
当场指出矛盾：“在第一轮你提到X，但这个答案暗示非X。以哪个为准？”
“我不知道”是合法答案→移至延迟决策部分，并由开发者选择明确的临时方案（例如“在做出决定前默认使用软删除”）。禁止默默延迟决策。
当针对某个维度的后续提问无法产生新问题时，该维度的提问完成。
当所有九个维度的提问都完成后，提问阶段结束。不要因为对话时长而提前停止——提前停止会导致主观假设混入其中。

Step 3: Draft the Spec File

步骤3：起草规格文档

Determine the next number from existing files in

docs/specs/

(create the directory if missing). Write

docs/specs/<NNN>-<slug>.md

markdown

undefined

根据

docs/specs/

目录中的现有文件确定下一个编号（如果目录不存在则创建）。编写

docs/specs/<NNN>-<slug>.md

文件：

markdown

undefined

Spec NNN: <Title>

规格文档 NNN: <标题>

Status: Draft Date: <today>

状态: 草稿 日期: <今日>

Problem

问题背景

Scope

范围界定

Domain Model

领域模型

API Contract

API契约

Authorization

权限控制

Edge Cases & Failure Modes

边缘案例与故障模式

Non-Functional Requirements

非功能性需求

Integrations

集成

Acceptance Criteria

验收标准

Deferred Decisions

延迟决策

Open Questions

未解决问题

undefined

undefined

Step 4: Review Loop

步骤4：审核循环

Set status to In Review. Present the complete spec and ask: "Read this end-to-end. What is wrong, missing, or over-engineered?" Fold corrections in and re-present. Repeat until the developer has no further changes. New answers may spawn new questions — that is the process working, not a failure to converge.

将状态设置为审核中。呈现完整的规格文档并询问：“请通读全文。是否存在错误、遗漏或过度设计的内容？”整合修正内容后重新呈现。重复此过程直到开发者没有进一步修改意见。新的答案可能会引发新的问题——这是流程正常运作的表现，而非无法收敛的失败。

Step 5: The Agreement Gate

步骤5：共识确认环节

Approval is a deliberate act, never inferred from silence or "looks good" in passing. Ask explicitly: "Do you approve this spec? After approval, code follows the spec — changes go through the spec first." On approval, set

**Status:** Approved (<date>)

Open Questions must be empty. If any remain, the spec cannot be approved — resolve or defer each one explicitly.
If implementation later reveals a wrong assumption: stop, set status back to In Review, fix the spec with the developer, then resume. Code never silently diverges from an approved spec.

获批是一个明确的动作，绝不能从沉默或随口的“看起来不错”中推断。需明确询问：“你是否批准此规格文档？获批后，代码开发必须遵循该文档——任何变更都需先修改规格文档。”获批后，将状态设置为

**状态:** 已获批 (<日期>)

。

未解决问题必须为空。如果仍有未解决问题，规格文档无法获批——需明确解决或延迟每个问题。
如果后续开发中发现错误的假设：暂停开发，将状态改回审核中，与开发者一起修正规格文档，然后继续开发。代码绝不能擅自偏离已获批的规格文档。

Step 6: Handoff

步骤6：交接

```
/plan
```
reads the approved spec and maps acceptance criteria to implementation steps
```
/tdd
```
turns acceptance criteria into the first failing tests (AC-n → test name)
Commits for the feature reference the spec:
```
feat: team workspaces (spec 004)
```

```
/plan
```
工具会读取已获批的规格文档，并将验收标准映射为开发步骤
```
/tdd
```
工具会将验收标准转化为初始失败测试用例（AC-n → 测试名称）
该功能的代码提交需引用规格文档：
```
feat: team workspaces (spec 004)
```

Example

示例

User: /spec users should be able to invite teammates

Claude: Here's what I understood: an existing user can invite another person
  to join their... workspace? account? That's already my first gap.
  Is this the idea? What did I get wrong?

User: yes, invite to their organization

Claude: Round 1 — Scope & Users:
  1. Can invitees be people without an existing account, or only registered users?
  2. Who can invite — any member, or only admins/owners?
  3. Is there a limit on pending invites (per org, per plan)?
  4. Out of scope check: bulk invites and SSO-provisioned members — both OUT for now?

User: 1: both. 2: admins only. 3: no limit. 4: correct, both out.

Claude: Round 2 — Edge cases (your "both" in Q1 raises these):
  1. Inviting an email that already has a pending invite — error, or resend?
  2. Invite expiry — 7 days, 30 days, never?
  3. Invitee already belongs to another org — multi-org membership or rejection?
  ...

[…rounds continue until all nine dimensions are exhausted…]

Claude: Spec written to docs/specs/004-team-invitations.md (In Review).
  Read it end-to-end. What is wrong, missing, or over-engineered?

User: looks right. approved.

Claude: Status: Approved (2026-06-12). Next: /plan to map AC-1..AC-9
  to implementation steps.

用户: /spec 用户应该能够邀请队友加入

Claude: 我的理解是：现有用户可以邀请其他人加入他们的……工作空间？账号？这是第一个信息缺口。
  这是否符合你的想法？我有哪些理解错误？

用户: 是的，邀请加入他们的组织

Claude: 第一轮 —— 范围与用户：
  1. 被邀请人可以是没有现有账号的人，还是仅针对已注册用户？
  2. 谁可以发送邀请——任何成员，还是仅管理员/所有者？
  3. 待处理邀请是否有数量限制（按组织，或按订阅计划）？
  4. 范围排除确认：批量邀请和SSO配置的成员——目前都排除在外？

用户: 1: 两者都可以。2: 仅管理员。3: 无限制。4: 正确，都排除。

Claude: 第二轮 —— 边缘案例（你在问题1中回答“两者都可以”引发以下问题）：
  1. 邀请已存在待处理邀请的邮箱——返回错误，还是重新发送邀请？
  2. 邀请有效期——7天、30天，还是永久有效？
  3. 被邀请人已属于其他组织——支持多组织成员身份还是拒绝邀请？
  ...

[…多轮提问持续到所有九个维度都覆盖完毕…]

Claude: 规格文档已写入docs/specs/004-team-invitations.md（状态：审核中）。
  请通读全文。是否存在错误、遗漏或过度设计的内容？

用户: 没问题，批准。

Claude: 状态：已获批 (2026-06-12)。下一步：使用/plan将AC-1..AC-9映射为开发步骤。