Hooke / mlaj

Go to a project
Toggle navigation Toggle navigation pinning
Switch branch/tag
hardcore-speckit-specify-template.md 11.3 KB

硬核 /speckit.specify 提示模板（可验证验收标准版）

用途：帮助你在调用 /speckit.specify 时，把需求描述成更可验证、更稳定的规格说明，让后续 /speckit.plan、/speckit.tasks、/speckit.implement 的输出更可控。

一、使用方式总览

  • 在聊天里调用命令时，将本模板中的「完整提示文案」作为补充说明一起发给智能体，例如：
    • /speckit.specify 001-recall-activity-history-state ActivityHistoryPage 增加一个空状态提示 + 列表加载失败提示（不改接口）
    • 然后追加一段话：「请严格按照《硬核 /speckit.specify 提示模板（可验证验收标准版）》来生成 specs/001-recall-activity-history-state/spec.md」
  • 规格说明的目标：
    • 明确 做什么 / 为什么做，不写具体实现细节。
    • 每条验收标准都能被前端 / 后端 / 测试同事用「条件 + 操作 + 预期结果」直接验证。
    • 所有分支（成功 / 无数据 / 失败 / 边界情况）都有清晰的预期。

二、规格结构模板（spec.md 结构）

输出文件固定为：specs/<feature_key>/spec.md，推荐结构如下：

  1. 背景与目标

    • 背景：说明业务场景、已有行为中的问题或机会。
    • 目标：本次改动要解决什么问题、带来什么价值。
    • 非目标：本次明确不做的范围（例如「不改接口、不动路由、不调整整体布局」）。

  2. 用户画像与使用场景

    • 谁在用（角色、平台、入口）。
    • 在什么场景下触发（来源页面、入口按钮、链路前后步骤）。

  3. 需求范围

    • 页面 / 入口：涉及到哪些页面、弹窗或组件。
    • 核心流程：从用户视角按步骤描述主流程。
    • 状态与异常分支：列出所有状态（正常、有数据、无数据、加载中、失败等）和切换条件。

  4. 用户故事（User Stories）

    • 使用「作为……我想……以便……」的句式，每个故事只描述一个明确目的。

  5. 验收标准（Acceptance Criteria）——重点加强部分

    • 使用「可验证条件」描述，每条至少包含：
      • 前置条件（环境、数据状态、接口返回等）。
      • 用户操作（点击、进入页面、刷新、重试等）。
      • 预期结果（UI 展示、状态变化、接口调用、副作用）。
    • 必要时补充「不允许出现的结果 / 行为」以减少歧义。

  6. 交互与视觉要点

    • 交互：点击反馈、加载状态、重试行为、动画等。
    • 视觉：布局位置、层级关系、是否与现有组件对齐。
    • 终端：默认移动端优先，如有 PC 差异需单独说明。

  7. 数据与接口

    • 数据字段：只描述字段含义，不写具体数据结构实现细节。
    • 接口约定：本项目约定所有接口返回结构均为 { code, data, msg }：
      • code = 1 表示成功；
      • code ≠ 1 表示失败；
      • data 为业务数据；
      • msg 为提示文案（前端可用作错误提示文本来源）。

  8. 边界条件与风险

    • 写出「极端但可能真实发生」的情况以及期望行为。
    • 对于不确定的行为，用自然语言描述当前的默认假设。

  9. 待确认事项

    • 所有不确定点都必须以 [NEEDS CLARIFICATION] 开头。
    • 每条都要写成一个具体的问题，便于后续和产品 / 业务沟通。

三、硬核验收标准书写规范

编写验收标准时，建议将每条标准写成「编号 + 条件 + 操作 + 预期结果」的形式，示例如下：

  • AC1：正常有数据时展示列表

    • 条件：接口 searchOldActivityAPI 请求成功，返回 code = 1，data.list 为长度 ≥ 1 的数组。
    • 操作：用户进入 ActivityHistoryPage，页面完成首次数据加载。
    • 预期结果：
    • 列表区域展示所有活动记录卡片，条数等于 data.list.length。
    • 不展示空状态文案、不展示失败状态或重试按钮。
    • 顶部 Banner、底部固定按钮等既有内容保持当前实现，不被遮挡或改变行为。

  • AC2：无数据时展示空状态

    • 条件：接口 searchOldActivityAPI 请求成功，返回 code = 1，但 data.list 为空数组或不存在可用记录。
    • 操作：用户进入 ActivityHistoryPage，页面完成首次数据加载。
    • 预期结果：
    • 列表原本展示卡片的位置，显示空状态区域（如「暂无活动记录」文案）。
    • 空状态展示在页面内容区域内，不通过 Toast 作为唯一反馈。
    • 不展示失败状态或重试按钮。
    • 顶部 Banner、底部按钮与其他入口可正常点击、滚动不受影响。

  • AC3：请求失败时展示失败状态 + 重试按钮

    • 条件：
    • 接口 searchOldActivityAPI 返回 code ≠ 1；或
    • 请求发生网络异常 / JS 异常导致无法获取数据。
    • 操作：用户进入 ActivityHistoryPage，触发列表加载。
    • 预期结果：
    • 列表区域显示失败状态区域，包含错误提示文案和「重试」按钮。
    • 提示文案优先使用接口返回的 msg 字段；若 msg 为空或不可用，则使用默认文案（例如「加载失败，请稍后重试」）。
    • 不展示有效的活动卡片，不展示空状态提示。
    • 顶部 Banner、底部按钮与其他入口仍可正常使用。

  • AC4：点击重试后的行为

    • 条件：页面当前处于失败状态，且显示重试按钮。
    • 操作：用户点击失败状态区域中的「重试」按钮。
    • 预期结果：
    • 重新发起一次 searchOldActivityAPI 请求，使用与首次请求相同的参数。
    • 在请求结果返回前，页面可选择短暂展示「加载中」状态或保持失败状态（需在规格中明确）；无论哪种方式，都不得多次并发重复请求。
    • 重试成功且有数据：页面展示列表卡片，隐藏失败状态与重试按钮。
    • 重试成功但无数据：页面展示空状态，隐藏失败状态与重试按钮。
    • 重试仍然失败：保持或更新失败状态提示文案（可使用新的 msg），重试按钮仍可再次点击。

  • AC5：缓存或参数异常时的行为

    • 条件：本地缓存的查询参数缺失、格式异常或读取缓存时抛出异常。
    • 操作：用户正常进入 ActivityHistoryPage。
    • 预期结果：
    • 页面不会出现崩溃或白屏。
    • 若无法构造有效请求参数，则进入失败状态，并展示失败提示与重试按钮。
    • 若重试按钮依赖重新读取缓存，则需要在规格中说明默认兜底行为（例如「使用默认时间范围重试」或「继续展示失败状态并提示用户稍后重试」）。

编写其他页面的验收标准时，可参考上述形式，将核心场景拆分为 AC1 / AC2 / AC3...，每条都保证：

  • 可以通过明确的前置条件在测试环境中复现；
  • 可以通过清晰的操作步骤验证结果；
  • 可以通过观察 UI 或接口行为判断是否通过。

四、可直接复用的 /speckit.specify 提示文案

当你在聊天中描述新需求时，可以在自然语言需求后追加如下提示，引导智能体按「硬核」方式输出规格说明：

请将上述需求整理为 Spec Kit 规格说明，输出到 specs/&lt;feature_key&gt;/spec.md，并严格遵守以下要求：

  1. 使用本项目既有的 spec 结构：背景与目标、用户画像与使用场景、需求范围、用户故事、验收标准、交互与视觉要点、数据与接口、边界条件与风险、待确认事项。
  2. 所有说明使用中文，专注描述「做什么 / 为什么」，不要写实现细节（例如具体组件名、函数名、接口实现代码）。
  3. 在「验收标准」一节中，以 AC1 / AC2 / AC3... 的形式列出所有可验证的标准。每条必须包含：
    • 条件：清晰的前置条件（数据状态、接口返回、环境等）；
    • 操作：用户在前端界面上的具体操作；
    • 预期结果：界面展示、状态变化、接口调用或其他可观察行为；
    • 如有必要，补充「不允许出现的结果」。
  4. 明确区分以下几类场景，并分别给出验收标准：
    • 正常有数据时的行为；
    • 无数据时的行为；
    • 请求失败 / 异常时的行为；
    • 点击重试或重新加载时的行为；
    • 缓存缺失、参数异常等边界条件。
  5. 在「数据与接口」部分中，明确约定接口返回结构统一为 { code, data, msg }：
    • code = 1 视为成功，code ≠ 1 视为失败；
    • msg 用作错误提示文案的主要来源；
    • 若本次需求不允许改动接口，请在此处显式说明「不新增接口、不修改现有接口」。
  6. 所有不确定点必须写入「待确认事项」并使用 [NEEDS CLARIFICATION] 前缀，形式为可直接询问产品 / 业务同学的具体问题。
  7. 请避免在验收标准中使用模糊描述（例如「尽量」「可能」「大概」），改用可观测、可验证的具体条件（例如「当 X 时必须显示 Y 文案，不展示 Z」）。

五、示例：ActivityHistoryPage 空状态 + 失败提示（摘要示例）

以下是基于 ActivityHistoryPage 需求的验收标准摘要示例，可作为编写类似功能规格时的参考：

  • AC1：有历史活动时

    • 条件：searchOldActivityAPI 返回 code = 1 且 data.list 长度 ≥ 1。
    • 操作：进入 ActivityHistoryPage，等待列表加载完成。
    • 预期结果：
    • 页面展示等同于 data.list 数量的活动卡片；
    • 不展示空状态和失败状态；
    • 头部 Banner、底部按钮和「没找到我的星球活动」入口可正常使用。

  • AC2：没有历史活动时

    • 条件：searchOldActivityAPI 返回 code = 1 且 data.list 为空数组或无可展示记录。
    • 操作：进入 ActivityHistoryPage，等待列表加载完成。
    • 预期结果：
    • 列表区域展示空状态文案（如「暂无活动记录」）；
    • 不展示失败状态和重试按钮；
    • 其他区域交互行为与有数据时保持一致，不出现遮挡。

  • AC3：接口失败或异常时

    • 条件：searchOldActivityAPI 返回 code ≠ 1，或请求抛出异常。
    • 操作：进入 ActivityHistoryPage，触发列表加载。
    • 预期结果：
    • 列表区域展示失败状态文案，优先使用接口返回的 msg，否则使用默认文案（如「加载失败，请稍后重试」）；
    • 同时展示「重试」按钮；
    • 不展示列表卡片和空状态；
    • 用户仍可操作顶部和底部区域。

  • AC4：点击重试

    • 条件：页面处于失败状态。
    • 操作：点击失败状态中的「重试」按钮。
    • 预期结果：
    • 重新调用 searchOldActivityAPI；
    • 根据新结果切换到 AC1 或 AC2 描述的状态；
    • 若依旧失败，保持或更新失败状态提示文案，仍可再次重试。

在实际书写 spec.md 时，可在此基础上补全其它章节（背景、用户故事、边界条件等），并针对具体业务做适当调整。