spec

/spec — 务求彻底的规格说明工作流

是什么

将一个想法转化为一份成文且带版本的规格说明，开发者和 Claude 会在开始任何规划或编码之前明确达成一致。约定如下：

• 绝不假设。 想法中的每个空白都会变成一个问题。如果 Claude 发现自己在想“可能”“大概”或“通常的做法”，就应把这个想法作为问题提出，而不是自行做决定。
• 务求彻底，但结构清晰。 问题分成有重点的多轮（每轮 3–5 个），覆盖九个维度；既不是一次抛出令人应接不暇的问题，也不是礼貌地问一轮就早早结束。
• 明确达成一致。 规格说明有状态生命周期：Draft → In Review → Approved。绝不能基于 Draft 开始实施。开发者必须阅读最终文档并明确表示已读，才能批准。
• 规格说明是文件，不是聊天记录。 输出会保存到 docs/specs/<NNN>-<slug>.md，并在会话结束后保留。计划、测试和提交都会引用它。

适用场景

• 任何无法用一句话完整描述的大型功能
• 新产品或模块构想（“我想添加团队工作区”）
• 非简单功能在执行 /plan 之前——规划会使用已批准的规格说明
• 实施过程中发现需求模糊时：暂停，执行 /spec，重新规划
• 触发短语：“spec”“requirements”“PRD”“define the feature”“acceptance criteria”

以下情况跳过： Bug 修复、重构、实体明确的单端点 CRUD。

如何使用

步骤 1：记录并复述

将原始想法用一段话复述出来：用 Claude 自己的话说明它理解的内容。最后问：“这就是你的想法吗？我理解错了什么？”在开发者确认复述内容之前，不要开始提问——围绕错误的想法提问会浪费所有人的时间。

步骤 2：分轮提问

按顺序梳理九个维度。每一轮：挑出 3–5 个尚未解答且最关键的问题（答案会影响后续问题的优先提出）。如果当前运行环境支持选择选项，就提供带有权衡说明的选项，并给出建议；但由开发者选择，绝不能在未说明的情况下直接采用建议。

#	维度	需要明确的内容
1	问题与用户	目前谁受到困扰、他们如何变通、成功的标准是什么
2	范围	本次迭代包含什么、明确排除什么、MVP 的界限在哪里
3	领域与数据	实体、关系、生命周期（创建→归档→删除？）、保留策略
4	API 契约	资源、端点、请求/响应结构、分页、版本管理
5	授权	谁可以做什么、角色/声明模型、租户边界
6	边缘情况与故障模式	并发、重复、幂等性、部分失败、限制
7	非功能性需求	预期用量、延迟预算、增长假设
8	集成	外部服务、发布的事件、Webhooks、副作用
9	验收标准	范围内每种行为都要有可测试的 Given/When/Then

务求彻底的提问规则：

• 立即将每个答案记录到规格说明草稿中——答案是需求，不是聊天内容。
• 当场指出矛盾：“你在第 1 轮说了 X；这个答案意味着不是 X。应该以哪个为准？”
• “我不知道”是合理答案 → 将其移至待定决策，并明确记录由开发者现在选择的后备方案（“决定之前默认采用软删除”）。禁止默默延后决策。
• 当后续一轮不再产生任何新问题时，该维度才算完成。
• 只有九个维度全部完成，提问阶段才算结束。不要因为对话时间太长就停止——过早停止正是假设悄悄混入的方式。

步骤 3：起草规格说明文件

根据 docs/specs/ 中已有文件确定下一个编号（如果目录不存在则创建）。写入 docs/specs/<NNN>-<slug>.md：

# Spec NNN: <Title>

**Status:** Draft
**Date:** <today>

## Problem            
## Scope              
## Domain Model       
## API Contract       
## Authorization      
## Edge Cases & Failure Modes
## Non-Functional Requirements
## Integrations
## Acceptance Criteria  
## Deferred Decisions   
## Open Questions       

第 4 步：评审循环

将状态设为 评审中。展示完整的规范，并询问：“从头到尾读一遍。有什么错误、遗漏或过度设计的地方？”纳入修正内容并重新展示。重复此过程，直到开发者没有进一步修改意见。新的回答可能会引出新问题——这说明流程正在发挥作用，而不是无法收敛。

第 5 步：批准关卡

批准是一项有意为之的行为，绝不能根据沉默或随口一句“看起来不错”来推断。明确询问：“你是否批准这份规范？批准后，代码将遵循这份规范——任何变更都要先修改规范。”获批后，设置 **Status:** Approved (<date>)。

• 未解决问题必须为空。 如果仍有任何未解决问题，就不能批准规范——请明确解决或推迟处理每个问题。
• 如果实现过程中发现假设有误：停止工作，将状态改回评审中，与开发者一起修正规范，然后继续。代码绝不会悄然偏离已批准的规范。

第 6 步：交接

• /plan 读取已批准的规范，并将验收标准映射为实现步骤
• /tdd 将验收标准转化为首批失败测试（AC-n → 测试名称）
• 此功能的提交需引用规范：feat: team workspaces (spec 004)

示例

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.

相关内容

• /plan — 使用已批准的规范；没有规范时，绝不规划需要编写规范的功能
• /tdd — 验收标准将成为首批失败测试
• /scaffold — 生成计划所需的切片
• architecture-advisor — 如果该功能需要做出架构决策，请在第 2 步加载