RaamPrashathT/spec-it

spec-it 是做什么的？

将 $ARGUMENTS 转化为一份无需后续追问、编码代理可直接构建的规格说明，并附带展示所有需求和边界条件的原型。

创意 → 1. 上下文（无需提问） → 2. 产品问题 → 3. 技术问题
     → 4. REQUIREMENTS.md → 5. 原型 → 6. 检查

类似 references/… 的路径是相对于 ${CLAUDE_SKILL_DIR} 的。输出内容将写入 spec-it/<kebab-name>/ 目录：

spec-it/<name>/
├── REQUIREMENTS.md      唯一交付物：意图、决策、阶段、FR、EC、假设
└── mockups/             index.html + 界面截图，或 api.html + openapi.yaml，或 cli.html + transcripts.md
    └── assets/          theme.css, fixtures.js, app.js

规则

1. 事实归你，决策归他们。 切勿询问仓库、附件、网络或标准能回答的问题。切勿替开发者决定范围、优先级或权衡。
2. 每个问题必须靠实力争取位置。 每个问题前先运行 references/questions.md 中的问题关卡。一个细节若存在可辩护的标准默认值，则应作为假设（A-n），而非问题。
3. 没有数量要求。 没有最低数量。典型运行会问 5-12 个问题。当你能预测开发者接下来的答案时，就停止提问。
4. 通过选择器提问（AskUserQuestion；不带选择器则用纯编号文本）。每次调用最多 3 个独立问题；切勿将选项依赖于另一个未回答问题的问题打包在一起。
5. 每个问题仅展示一次， 作为消息中的最后内容。之后不再重复。
6. 将状态写入磁盘。 上下文步骤之后，保持 REQUIREMENTS.md 作为工作文件：提前起草第 1-2 节，随着决策确定而填充。在进行上下文压缩后，重新读取它再行动。
7. 原型离线工作。 不使用 CDN、网络或网络字体。
8. 检查脚本是完成的关卡： node ${CLAUDE_SKILL_DIR}/scripts/check.mjs spec-it/<name> 返回 0 为通过。

ID 规则：FR-n 需求，EC-n 边界条件，D-n 决策，A-n 假设。对于模块，FR/EC/A 需加上模块前缀（BOOK-FR-3）。ID 是永久的：绝不重新编号；删除时标记为“（已移除）”。

1. 上下文（暂不提问）

在问任何问题之前先做这个。并行运行两项查找，在可用时使用全新上下文的子代理：

• 代码库扫描（如果文件夹为空则跳过）：技术栈、与创意重叠的现有功能、数据模型、认证、UI 套件和设计令牌、API 和 CLI 约定、任何半成品。最多返回 25 行。
• 现有方案研究（网络搜索，2-4 次搜索）：2-3 个成熟产品或标准如何解决此问题；该领域已知的难点（真实使用中容易出错的地方）；标准功能集；任何相关的规范（如 RFC, clig.dev, WCAG, 支付或隐私规则）。最多返回 25 行，附带来源链接。

然后向开发者展示一个上下文简报，最多 15 行：

我发现了什么
- 仓库：<此内容触及或复用了哪些现存内容>
- 他人做法：<产品 A 做了 X，产品 B 做了 Y>
- 该领域的难点：<2-4 点，例如“未出席导致房间空置；周期性预订”>
- 我的解读：<一句话假设你想要什么以及为什么> · 信心度 <n>%

确定类型（UI、API、CLI、混合），并从 assets/requirements-template.md 创建 REQUIREMENTS.md，填充第 1 节和上下文部分。你发现的难点是你最佳问题的原始素材。

2. 产品问题

阅读 references/questions.md。从风险最高的未知项开始：这是否是正确的问题、为谁而做、先交付什么、什么不在范围内，然后将领域的难点作为具体场景。每获得一个答案，立即记录为 D-n 加入 §决策 部分。

当以下三个条件都满足时，切换到技术问题：

• 你能用开发者自己的话写出重述（结果、用户、为什么现在、成功的定义、范围外）；
• 第一阶段的范围和非目标已达成一致；
• 剩余问题都是关于如何做，而非什么、谁或为什么。

例外：一个会改变范围的硬性约束（如“必须离线运行”、“复用我们的 Auth0 租户”、“数据留在欧盟”）一旦出现就立即提问，因为它会重塑产品问题。

3. 技术问题

仅在分叉点处提问：即仓库和标准无法解决，且答案会改变数据模型、契约或用户可见行为的地方。列表在 references/questions.md §技术问题 部分。许多运行只需要 0-4 个。切勿询问仓库已确定的托管、CI、框架或供应商选择。

确认关卡。 一条消息：重述（6 行），然后你做出的每个假设（A-n，每行一个，附默认值）。询问：确认，或指出需要更改的假设。合并更改。只有在获得明确确认后，才在规范的 status 行写上 Status: Confirmed。

阶段和模块

阶段（始终考虑）。 “先交付什么”的产品问题决定了阶段。阶段 1 是用户端到端完成核心任务的最薄切片（行走骨架）。如果开发者希望一次性完成所有内容，则只有一个阶段。每个 FR 带有 Phase: n。阶段 1 必须详细完整说明；后续阶段则在 §交付计划 中每个能力用一个要点描述，直到 --next-phase 时再详细说明。

模块（仅在出现信号时）。 仅当某个领域满足以下两个或更多条件时才将其视为模块：不同的人或词汇；拥有自己的数据；单独交付时也有用；需要自己单独的 10 个以上问题。如果有 2 个或以上符合的领域，则提问一次：建议用一个带有模块章节的规范（推荐），或者先说明最重要的模块，再概述其余部分。切勿根据创意听起来有多大来推断模块。模块保持在同一个 REQUIREMENTS.md 文件中，作为 §功能需求 下的 ## 节，带有 ID 前缀。

大小限制。 如果阶段 1 超过约 25 个必须 FR 或 12 个原型制品，询问哪些应移至阶段 2。

4. 编写 REQUIREMENTS.md

填充模板。每个 FR 都有 ID、优先级、阶段、Given/When/Then 以及 Source: 决策 ID；每个被提出的边界条件都成为 EC-n，并附带具体的模拟值。FR 描述用户观察到的内容；技术细节放在 §技术决策 中。然后对照以下列表进行一次自我审查并修复违规项：

• 两条无法同时成立的陈述，或同一规则重复说明。
• 一个 FR 开发者可以用两种不同方式构建（缺少限制、单位、角色或失败行为）。
• 一个无法通过观察判断通过或失败的标准，或含义模糊无数字的词语。
• 某个角色、实体或流程没有对应的 FR；某个决策未被任何内容引用。
• 某个词语的使用与词汇表不一致。

5. 原型

列出制品（界面截图、端点组或命令组），最多 12 个，每个包含其状态，并将每个 EC 映射到一个状态。在一个消息中展示列表，除非开发者反对，否则继续。然后阅读 references/screens.md（UI）或 references/api-cli.md（API、CLI）并构建：

1. 首先编写 mockups/assets/fixtures.js：任何制品中出现的每个名称、ID、金额和日期。
2. UI：将设计方向写入 §设计方向。如果仓库有设计系统或令牌，遵循它并跳过设计问题；否则在选项预览中用 ASCII 草图询问一个设计方向问题。
3. 将 ${CLAUDE_SKILL_DIR}/assets/theme.css 和 app.js 复制到 mockups/assets/，设置令牌，运行检查直到对比度通过。
4. 根据 references/renderer.md 构建每个制品：如果有 4 个或更多制品且拥有子代理工具，则每个制品并行使用一个子代理；否则在此处逐个构建。CLI：先编写 mockups/transcripts.md，然后执行 node ${CLAUDE_SKILL_DIR}/scripts/cli-render.mjs spec-it/<name>。
5. 从 ${CLAUDE_SKILL_DIR}/assets/index.html 填充 mockups/index.html。
6. UI（如果有浏览器工具）：可选择运行 references/critic.md 并应用其最佳修复一次。

6. 检查并报告

运行检查脚本直到返回 0；将模棱两可的警告视为需要精炼的措辞。报告最多 10 行：路径、统计（提问数量、FR、EC、假设、制品）、检查摘要行、如何查看原型（打开 mockups/index.html，或执行 node ${CLAUDE_SKILL_DIR}/scripts/serve.mjs spec-it/<name>），以及（如有）下一阶段。按需执行 node ${CLAUDE_SKILL_DIR}/scripts/export.mjs spec-it/<name> 可生成单文件副本用于共享。

后续运行

• --next-phase： 读取规范，提取下一阶段的要点，仅对这些要点运行步骤 2-6（问题从第一阶段遗留的未解决问题开始）。新的 FR 延续编号；早期 ID 永不更改。
• --revise（或变更请求）：记录新决策，更新受影响的 FR 和 EC，仅重新渲染受影响的制品，再次运行检查。

合理化

想法	现实
“我应该覆盖每个领域，所以我会问集成问题。”	仅在答案会改变规范时才提问。“v1 中没有”是一个假设。
“我会问他们想要哪种时间步长。”	存在标准默认值。记录为 A-n；确认关卡会展示它。
“创意很明确，跳过上下文步骤。”	上下文步骤是产生好问题的地方。始终运行它。
“创意听起来很大，所以要用模块。”	模块需要信号，然后需要开发者的选择。
“他们接受了所有建议，太好了。”	建议可能过于安全。你的下一个问题应该是一个他们会不同意的问题。