vid coding - spec kit 工具链
编写需求文档
3️⃣ 推荐做法
-
保留敏捷风格的 User Story
- 作为团队沟通、迭代和 backlog 使用
-
在 User Story 上增加 Spec Kit 辅助字段（可以称作“增强 PRD”）
- 用户状态（User State）
- 可判定触发条件
- 决策分支
- 策略意图
- 明确约束
这是一个非常关键且前置的问题。你已经走到 Vid Coding / Spec-driven Development 的“地基层”了。
我直接给你结论型答案，然后给一套可直接要求 PM 执行的文档规范，目标只有一个：
让 PM 写的文档，能被 AI 稳定、低歧义地转换为 Spec Kit 输入。
一句话总规范（你可以直接写进团队规范）
PM 需求文档必须“语义完整、结构稳定、避免隐式决策”，
但不包含任何系统实现细节。
PM 需求文档必须满足的 6 大规范（核心）
明白了，你希望我基于 Spec Kit 官方建议，重新梳理一套 PM 编写 PRD 的规范，做到：
- 更贴近官方字段定义
- 更易理解，避免和我之前给的 7 条规则混淆
- 便于 AI 转成 Spec Kit 规范
我帮你重新整理如下。
基于官方建议的 PM PRD 编写规范
目标：PM 写出的 PRD 能被 AI 或工具稳定转换为 Spec Kit 的结构化规范，减少歧义。
1️⃣ Intent（必写）
定义：用户目标/意图，系统响应的触发依据。
规范写法：
- 描述用户希望达成的目标或行为
- 可包含触发条件和问题定义，但保持高层次，不写具体系统动作
示例：
用户希望查看购物车内商品明细，但未登录时无法访问。
2️⃣ Action（强烈推荐）
定义：系统在用户触发 Intent 后应执行的动作（可选简化，简单故事可省略）。
规范写法：
- 用动词描述系统行为
- 不写 UI 实现细节
- 对复杂流程推荐明确 action
示例：
系统提示用户登录，提供登录入口。
3️⃣ State（可选）
定义：执行动作前后状态对业务逻辑或验收有影响时写。
规范写法：
- 明确状态名称
- 仅在状态变化影响业务或后续判断时写
- 不必写所有系统状态
示例：
未登录 -> 已登录
4️⃣ Constraint（可选）
定义：动作或流程必须遵守的规则或边界。
规范写法：
- 明确禁止或限制行为
- 可写安全、业务或合规要求
示例：
不得显示其他用户信息。
登录失败不得泄露密码。
5️⃣ Acceptance Criteria（必写）
定义：验收标准，保证系统行为可测试、可执行。
规范写法：
- 描述可观察的用户行为或系统状态
- 与 Intent/Action 对应
- 可包含成功和失败的判断条件
示例：
- 用户输入正确凭证后，成功登录并可访问购物车。
- 用户输入错误凭证后，显示明确错误提示。
6️⃣ 决策分支（隐式）
定义：官方字段里没有单独字段，但在 PRD 中可通过 Intent + State + Action 组合描述分支逻辑，便于 AI 转 Spec Kit。
规范写法：
- 用 if-then 风格描述不同判定条件
- 不写执行实现细节，只描述决策条件和预期结果
示例：
如果用户凭证正确，则登录成功；
如果密码错误，则提示错误；
如果连续 5 次失败，则锁定账户。
7️⃣ 用户故事模板（推荐）
### Intent（必写）
- 用户目标/意图：
### Action（强烈推荐）
- 系统应执行的动作：
### State（可选）
- 执行动作前后的状态变化（如有影响）：
### Constraint（可选）
- 规则或边界：
### Acceptance Criteria（必写）
- 可观察的成功或失败标准：
### 决策分支（隐式）
- 不同条件下的判定逻辑
用户登录User Story例子
Intent（必写）
用户希望访问个人购物车和订单信息，但当前尚未完成登录认证。
Action（强烈推荐）
系统在检测到用户未登录时，应引导用户完成登录认证流程。
State（可选，因影响业务逻辑而必写）
- 初始状态：未登录（Unauthenticated）
- 目标状态：已登录（Authenticated）
Constraint（可选）
- 登录失败时不得泄露任何账户敏感信息（如是否存在该用户、密码规则等）。
- 系统不得绕过认证直接授予访问权限。
- 同一账户连续多次登录失败时需触发安全限制策略。
Acceptance Criteria（必写）
- 当用户输入正确的账号和密码时：
- 系统将用户状态从「未登录」切换为「已登录」
- 用户可正常访问购物车和订单页面
- 当用户输入错误的账号或密码时：
- 系统拒绝登录
- 系统向用户展示明确但不泄露敏感信息的错误提示
- 当同一账户连续 5 次登录失败时：
- 系统阻止继续登录尝试
- 系统提示用户需要进行额外验证或稍后再试
决策分支（隐式，用于理解与转换）
- 如果凭证校验成功 → 登录成功 → 状态变更为「已登录」
- 如果凭证校验失败 → 登录失败 → 状态保持「未登录」
- 如果失败次数达到阈值 → 触发安全限制策略
✅ 说明
- 触发条件 + 问题定义 → 合并到 Intent
- 目标/成功标准 → Acceptance Criteria
- 策略意图 → 可选写入 Action
- 约束/禁止项 → Constraint
- 状态变化影响 → State
- 决策分支 → 隐式写在 PRD 或 Acceptance Criteria 中
变更
修改BUG
明白你的疑问了，本质是 Spec Kit 如何区分“这是一个 bug 修复的 Spec”还是普通的用户故事 Spec”，尤其当 bug 修复可能影响之前的设计时。下面我详细解释官方的做法和实践策略：
1️⃣ Spec Kit 区分类型的机制
Spec Kit 并不是完全依赖命令本身去区分类型，而是 依赖 Spec 的元数据和上下文标签（metadata/labels） 来标记 Spec 的类型。常用做法：
| 元素 | 说明 |
|---|---|
| Type / Category | Spec 可以在创建时标记类型，例如 feature、bugfix、hotfix、refactor 等 |
| Parent / Related Spec | 可以关联已有用户故事或设计 Spec，表示该 bug 修复影响某个原功能或设计 |
| Version / Iteration | 标记 Spec 所属迭代或版本（v1, v2, hotfix-v1.1） |
所以
/specify本身只是“创建一个 Spec”，它可以是用户故事、bug、设计变更，都由元数据标识类型。
2️⃣ 创建 Bug Spec 的流程
-
/specify + 类型标记
/specify type=bugfix related=US-101 description="登录页报错"type=bugfix→ 指明这是 bug 修复related=US-101→ 关联原用户故事或功能- Spec Kit 会识别这是一个 bug Spec，而不是新功能需求
-
填写结构化字段
- Intent：用户期望行为
- Action：出错行为 + 修复动作
- State：出错前/修复后状态
- Constraint：修复条件
- Acceptance Criteria：验证标准
-
/plan → /tasks → /implement
- Spec Kit 会根据 type 自动生成任务，并把任务和原用户故事关联起来
- 如果修复影响原设计，也可以生成“设计修改任务”，并保留 trace
3️⃣ 如果 Bug 修复需要修改之前的设计
-
在
/specify type=bugfix的时候：- Action / State 可以写“同时修改 X 设计”，并在 related=原设计 Spec 里关联
- Spec Kit 会自动把设计变更任务纳入当前 workflow
- 这样即使你执行
/specify创建 Bug Spec，它也能追踪到原设计，生成对应修改任务
要点：关键不是命令 /specify 本身，而是 Type + Related Spec + Metadata 来区分“普通需求”、“Bug 修复”还是“设计变更”。
4️⃣ 实践建议
- 所有 Bug 都用
type=bugfix或hotfix标记 - 关联原用户故事/设计，保证影响可追踪
- 设计变更不要单独再写一个普通 Spec，直接在 Bug Spec 中通过 Action/State 体现
- 版本管理：给 Bug Spec 打版本号（v1.1.1 或 hotfix-v1.1）
修改设计
明白了，你说的情况是 “直接修改已有设计 Spec，而代码已经实现了旧设计”，这种场景属于 设计变更（Design Change），影响已经存在的任务和代码。下面我按照 Spec Kit 的管理逻辑详细说明：
1️⃣ 核心原则
- Spec Kit 的源头是 Spec（设计/用户故事），所有变更都从 Spec 出发。
- 代码已经实现 → 修改设计意味着需要追踪哪些代码和任务受影响，并生成对应更新任务。
- 区别于 bug 修复：不是修复错误，而是修改设计逻辑或行为，所以 Type 通常是
design-change或直接修改原 Spec。
2️⃣ 正确流程（官方建议）
步骤 1：修改设计 Spec
-
执行
/specify或在已有 Spec 上直接编辑：- 修改 Action、State、必要时修改 Constraint 或 Acceptance Criteria
- 保留原用户故事 ID 或功能 ID
- 标记类型
type=design-change（可选，但推荐）
步骤 2：生成计划
-
/plan→ Spec Kit 会对比 旧设计 Spec vs 新设计 Spec -
自动标记哪些 任务受影响：
- 修改任务：原代码需要调整的逻辑
- 新增任务：新设计增加的功能或接口
- 废弃任务：旧设计不再需要的逻辑或模块
步骤 3：拆解任务
/tasks→ 拆解成可执行任务（开发/测试/文档）- 每个任务关联到原代码模块，便于追踪
步骤 4：实现与验证
/implement→ 执行修改任务- 更新代码、接口、数据库或前端逻辑
- 根据 Spec 的 Acceptance Criteria 验证功能正确性
3️⃣ 补充说明
-
历史追踪：旧设计和旧代码保留，生成新版本（v2、hotfix-v1.1 等），保证可回滚。
-
与 Bug 区别：
类型 特点 Bug 修复 修复错误，恢复期望行为，通常 type=bugfix 设计变更 修改原本正确实现的功能或逻辑，type=design-change，可能影响多模块 -
任务生成：Spec Kit 会自动把受影响的实现任务标记为“需要更新”，避免遗漏。
4️⃣ 实践建议
- 直接在原 Spec 上修改设计，而不是新建一个普通 Spec（否则追踪关系丢失）。
- 保留旧版本（v1），新版本（v2）作为迭代/设计变更记录。
- 关联原任务和模块，方便开发知道哪些代码需要改。
- 生成 Acceptance Criteria，确保修改后的设计能被验证。
生成自动化测试脚本
一、先给结论（非常关键）
Spec Kit 默认只会稳定生成「单元测试（Unit Test）」
不会自动生成 E2E / UI / API 自动化测试，除非你显式“把测试意图写进 Spec”
这不是 bug，是 设计取舍。
二、为什么 Spec Kit 会“只生成单元测试”
1️⃣ Spec Kit 的默认假设
Spec Kit 在设计时的隐含假设是：
“我看到的是代码仓库 + 需求规范
那我最安全、最确定的测试是什么？
—— 单元测试。”
原因有三点：
| 原因 | 解释 |
|---|---|
| 确定性最高 | 单元测试可以直接基于函数/类生成 |
| 不依赖环境 | 不需要浏览器、服务、数据 |
| LLM 成功率最高 | 不容易生成不可运行代码 |
所以如果你什么都不额外声明：
👉 Spec Kit 会保守地生成 unit tests
2️⃣ Spec Kit 不“猜”自动化测试
Spec Kit 不会擅自假设：
- 你用 Playwright 还是 Cypress
- 是否已有 E2E 测试框架
- API 是否可直接访问
- 测试环境如何启动
因此它不会默认生成：
- UI 自动化
- API 集成测试
- 跨模块 E2E
三、什么时候 Spec Kit 才会生成“自动化测试”
一句话：
当 Spec 中出现“跨边界行为”且你明确声明测试类型时
关键判断点
Spec Kit 内部会判断：
| 行为特征 | 结果 |
|---|---|
| Action 是函数调用 | 单元测试 |
| Action 是 HTTP / 页面 / 用户行为 | 可能是自动化测试 |
| Acceptance Criteria 是 Given/When/Then + 系统行为 | 可以生成 E2E |
| 没声明 test scope | 回退为 unit test |
四、你现在项目“为什么没生成自动化测试”
根据你描述的现象，90% 是下面这个原因：
你的 Spec 没有显式声明：
「这是 E2E / API / 自动化测试」
例如，你的 Spec 可能是这样：
Action:
- validate user input
- save order
Spec Kit 会理解为：
👉 这是函数/模块行为 → 单元测试
而不是：
Action:
- User submits order via checkout page
- Backend API creates order
五、如何“强制”Spec Kit 生成自动化测试（实战）
方式一（最推荐）：在 Spec 中声明 Test Scope
在 /specify 中明确写：
Test Scope:
- e2e
Test Framework:
- Playwright
或：
Non-Functional Requirement:
- E2E tests must be provided for critical user flows
方式二：在 Acceptance Criteria 中写“系统级行为”
❌ 不推荐（函数级）：
Then order is saved successfully
✅ 推荐（系统级）：
Then user is redirected to /order/success
And order appears in order history page
方式三：显式加一条“测试需求 Spec”
很多成熟团队会这样做：
/specify
Type: test
Intent: Validate checkout flow end-to-end
Actions:
- Open checkout page
- Submit order
- Verify success page
Acceptance Criteria:
- Given user is logged in
When user submits checkout form
Then order success page is shown
👉 Spec Kit 几乎 100% 会生成 E2E 测试任务
六、一个现实但重要的判断
Spec Kit 更像“测试架构师”，不是“测试执行器”
它：
- 能判断 应该有哪些测试
- 能生成 测试任务 / 测试规范
- 能生成 unit test 代码
但：
- 自动化测试代码的生成，需要你“点名”
七、给你一个可执行的改进清单
你可以现在就这样做：
-
回到你的小项目 Spec
-
修改其中一个 Spec，加上：
- Test Scope: e2e
- Target Framework: Playwright
-
把 Action 改成「用户行为 + 系统反应」
-
重新跑
/plan → /tasks
你会看到：
- 新增 E2E / automation test tasks
- 而不是只有 unit test
浙公网安备 33010602011771号