name: spec-workflow description: 规格驱动开发（SDD）工作流程自动触发强制执行。在子任务开始时确认AC、执行TDD、完成时进行AC检查。禁止范围外实现。适用于实现功能、创建新功能或当出现“实现”、“创建”、“开发”等关键词时使用。

规格驱动开发工作流程技能

规格驱动开发（SDD）的下游工程（实现）。基于EPIC → Story → Subtask的三层结构进行开发。

注意: 规格制定（上游工程）在 /spec 技能中进行。协同流程: /spec（规格制定）→ spec-workflow（实现）

触发条件

以下关键词/上下文中自动触发：

实现、创建、开发
新功能实现
子任务开始、故事开始
提及EPIC、故事、子任务

基本原则

1. 规格优先（必须）

实现前必须确认以下内容：

读取specs/{epic-id}/{story-id}/{subtask-id}.md
确认用户故事
理解AC
向用户确认“这个AC可以进行吗？”

2. 严格遵守TDD（必须）

🔴 红   : 从AC导出测试用例 → 编写失败的测试
🟢 绿 : 使测试通过的最小实现
🔵 重构 : 在保持测试的同时改善代码

EARS记法对应

如果AC用EARS记法描述，测试用例导出效率化：

// EARS记法的AC示例：
// WHEN 用户尝试登录时
// GIVEN 输入有效邮件和密码时
// THEN 系统发放JWT令牌
// AND 重定向到仪表板

// 转换为测试用例：
describe('登录', () => {
  it('有效认证信息发放JWT令牌', () => {
    // GIVEN: 设置前提条件
    const credentials = { email: 'valid@example.com', password: 'validPass' };

    // WHEN: 执行触发器
    const result = login(credentials);

    // THEN: 验证预期结果
    expect(result.token).toBeDefined();
  });

  it('成功时重定向到仪表板', () => {
    // AND条件的测试
  });
});

3. 范围管理（必须）

只实现AC中描述的功能
范围外的“顺便”实现不做
不明确的地方向用户确认

工作流程详情

第1阶段：子任务开始时（必须流程）

// 1. 读取子任务文件
const subtaskFile = await read(`specs/{epic-id}/{story-id}/{subtask-id}.md`)

// 2. 确认AC
const acceptanceCriteria = parseAC(subtaskFile)

// 3. 确认用户故事
const userStory = parseUserStory(subtaskFile)

// 4. 向用户确认
await ask(`以下AC进行实现。可以吗？
${acceptanceCriteria.map(ac => `- ${ac}`).join('
')}`)

// 5. 导出测试用例
const testCases = deriveTestCases(acceptanceCriteria)

第2阶段：TDD实现

// 🔴 红：先写测试
describe(subtaskTitle, () => {
  acceptanceCriteria.forEach(ac => {
    it(ac, async () => {
      // 从AC导出测试用例
    })
  })
})

// 确认测试失败
await runTests() // 预期：失败

// 🟢 绿：最小实现
// 实现满足AC的最小代码
await runTests() // 预期：通过

// 🔵 重构：代码改善
// 在保持测试的同时改善
await runTests() // 预期：通过

第3阶段：完成时（必须流程）

// 1. 检查所有AC项目
acceptanceCriteria.forEach(ac => {
  console.log(`✅ ${ac}`)
})

// 2. 确认所有测试通过
await runTests() // 所有测试通过

// 3. 更新状态
await updateSubtaskFile({
  status: 'completed',
  completed_at: new Date().toISOString()
})

// 4. 确认父故事
if (allSubtasksCompleted(storyId)) {
  await updateStoryFile({ status: 'completed' })
}

// 5. 提示下一个子任务
console.log(`下一个子任务：${getNextSubtask()}`)

范围判断

范围内（实现OK）

AC中明确描述的功能
为实现AC必须的技术实现
实现用户故事的价值的功能

范围外（提案）

AC中未描述的“顺便”改进
将来可能需要的“可能”功能
应在其他子任务/故事中处理的功能

范围外处理流程

if (isOutOfScope(request)) {
  const response = `
  您请求的「${request}」不在当前子任务的AC中。

  当前AC：
  ${currentAC.map(ac => `- ${ac}`).join('
')}

  方案：
  1. 当前子任务不实现
  2. 作为另一个子任务提出

  您选择哪个？」

  await ask(response)
}

测试文件布局

specs/{epic-id}/{story-id}/{subtask-id}.md  # 子任务定义
{feature}/
├── service.ts         # 实现文件
└── __dev__/
    └── service.test.ts  # 测试文件（Colocation）

禁止事项

❌ 无AC开始实现
❌ 无测试实现（违反TDD）
❌ 范围外的“顺便”实现
❌ 同时实现多个功能（1个子任务=1个功能）
❌ 未经用户确认的规格变更
❌ 未确认完成状态的更新

错误处理

AC模糊时

if (isACAmbiguous(ac)) {
  await ask(`
  以下AC模糊，无法开始实现。

  模糊的AC：${ac}

  建议明确化如下：
  '${suggestedAC}'

  按这个明确化进行可以吗？
  `)
}

测试不通过时

if (testsFailed) {
  // 修改实现（达到Green）
  // 如果是测试本身的问题则修正
  // 如果是对AC的解释有问题则向用户确认
}

分支&PR协同

本技能自动调用/branch和/pr。

协同流程

spec-workflow 开始
    │
    ├─ 子任务文件读取
    │
    ├─ AC确认&用户批准
    │       │
    │       └─ 批准后 → /branch 发火
    │          分支：impl/{subtask-id}-{description}
    │
    ├─ TDD实现
    │   - 🔴 红：测试创建
    │   - 🟢 绿：最小实现
    │   - 🔵 重构：改善
    │
    ├─ AC所有项目检查
    │
    └─ 完成时 → /pr 发火
        PR：实现审查用

/branch调用

AC确认&批准后自动发火：

Claude: 以下AC进行实现。可以吗？
        - AC1: ...
        - AC2: ...

用户：OK

Claude: 创建实现用分支。

        分支名：impl/001-01-01-user-auth
        基础：main

        可以创建吗？

/pr调用

AC所有项目检查完毕后自动发火：

Claude: 所有AC都满足了。

        ✅ AC1: 有效认证信息登录成功
        ✅ AC2: 无效认证信息显示错误
        ✅ AC3: MFA代码验证

        创建PR吗？
        标题：impl: 用户认证功能实现

        ## 摘要
        - 实现001-01-01
        - 登录/登出功能

        ## AC确认
        - [x] AC1
        - [x] AC2
        - [x] AC3

参考文档

SPEC_FORMAT.md - 规格格式定义
WORKFLOW.md - 工作流程详情

使用示例

示例1: 新子任务实现

用户：「001-01-01的设置要求子任务实现」

[自动] spec-workflow Skill触发
[自动] specs/001-environment-setup/001-01-common-config/001-01-01-config-requirements.md 读取

Claude: 「以下AC进行实现。可以吗？
- 配置文件布局方针已明确决定
- ESLint、Prettier、TypeScript的设置内容已作为规格确定
- package.json脚本的统一方针已决定」

用户：「OK」

Claude: 「🔴 红：导出测试用例...」
（以下，TDD周期）

示例2: 范围外请求

用户：「顺便CI/CD也设置一下」

Claude: 「您请求的「CI/CD设置」不在当前子任务的AC中。

当前AC：
- 配置文件布局方针已明确决定
- ESLint、Prettier、TypeScript的设置内容已作为规格确定

方案：
1. 当前子任务不实现（推荐）
2. 定义为新的子任务

您选择哪个？」

规格驱动开发工作流程 spec-workflow

规格驱动开发工作流程技能

触发条件

基本原则

1. 规格优先（必须）

2. 严格遵守TDD（必须）

EARS记法对应

3. 范围管理（必须）

工作流程详情

第1阶段：子任务开始时（必须流程）

第2阶段：TDD实现

第3阶段：完成时（必须流程）

范围判断

范围内（实现OK）

范围外（提案）

范围外处理流程

测试文件布局

禁止事项

错误处理

AC模糊时

测试不通过时

分支&PR协同

协同流程

/branch调用

/pr调用

参考文档

相关技能

整体协同流程

使用示例

示例1: 新子任务实现

示例2: 范围外请求