requirement-workflow

需求工作流（SDD）

基于规范驱动开发的结构化开发编排器：先定义规范，再分解任务，通过质量门执行，并依据验收标准进行验证。

核心原则：规范是唯一事实来源。代码应遵循规范，而不是反过来。

前置条件

• Node.js >= 18
• 可写入工作流状态文件的项目目录（.trae/workflow/）

快速开始

User says anything about building/implementing/fixing →
  1. AI classifies the request (type + size + risk)
  2. AI runs: node init.cjs -r <root> -n <name> -t <type> -s <size> -k <risk>
  3. AI fills spec.md with structured requirements (EARS format)
  4. AI decomposes spec.md into tasks.md
  5. AI implements task by task, advancing stages
  6. AI verifies against checklist.md

工作模式

此技能支持两种模式，根据分类进行选择：

Agent 模式（默认）

对于范围为小型/微型或类型为缺陷修复的任务：跳过规范阶段，直接开始实现。

INIT → IMPLEMENTING → TESTING → DONE

规范模式（SDD）

对于范围为中型/大型或风险为较高/严重的任务：执行完整的 SDD 生命周期。

INIT → DEFINING → PLANNING → DESIGNING → IMPLEMENTING → TESTING → DELIVERING → DONE

分类矩阵

信号	类型	大小	风险
“修复错误”、“故障”、“崩溃”	缺陷修复	微型-小型	正常
“添加功能”、“实现”、“构建”	功能	小型-大型	正常
“重构”、“清理”、“重新组织”	重构	小型-中型	正常
“技术债务”、“升级”、“迁移”	技术债务	中型-大型	较高
身份验证、支付、数据、安全	任意	任意	较高-严重
预计涉及 >15 个文件	任意	大型	较高

大小启发式规则

大小	文件数	时长	阶段
微型	≤2	<30 分钟	INIT → IMPLEMENTING → DONE
小型	3-5	30 分钟-2 小时	INIT → IMPLEMENTING → TESTING → DONE
中型	6-15	2 小时-1 天	完整 SDD
大型	>15	>1 天	完整 SDD + 所有检查点

SDD 生命周期

阶段 1：INIT

对请求进行分类、初始化工作流并创建产物目录。

node init.cjs -r <project_root> -n "<name>" -t <type> -s <size> -k <risk>

输出：workflow.yaml、空白的 spec.md、tasks.md、checklist.md

阶段 2：DEFINING（仅限规范模式）

使用 EARS 格式填写 spec.md 中的结构化需求：

# Feature Name

## Background
{Why this is needed — problem statement}

## Scope
- In: {what IS included}
- Out: {what is NOT included}

## Acceptance Criteria (EARS format)
- [ ] When <condition>, the system shall <response>
- [ ] While <state>, the system shall <behavior>
- [ ] Where <constraint>, the system shall <limit>

## Constraints
- {Performance, security, compatibility requirements}

## Out of Scope
- {Explicitly deferred items}

检查点：如果风险为较高/严重，暂停并等待用户审阅 spec.md。

钩子：pre_stage_DEFINING → iron-audit-pm、problem-definer、risk-auditor

阶段 3：PLANNING（仅限规范模式）

将 spec.md 分解为 tasks.md——每项验收标准至少对应 1 个任务：

# Tasks

## Phase 1: Foundation
- [ ] Task 1.1: {description} [files: x, y]
- [ ] Task 1.2: {description} [files: z]

## Phase 2: Core Logic
- [ ] Task 2.1: {description} [files: a, b]

## Phase 3: Integration & Polish
- [ ] Task 3.1: {description} [files: c]

## Verification
- [ ] All acceptance criteria pass
- [ ] Lint clean
- [ ] Type check pass

规则：每个任务都必须是原子性的（可独立完成），并且可追溯到某个规范条目。

钩子：pre_stage_PLANNING → story-mapper、mvp-freeze-architect

阶段 4：DESIGNING（仅限规范模式）

创建 design.md（仅适用于中型及以上规模），记录架构决策：

• 组件结构
• 数据流
• API 契约
• 关键权衡

检查点：如果风险为较高/严重，暂停并等待用户审阅。

钩子：pre_stage_DESIGNING → domain-modeler、architecture-advisor、responsibility-modeler

阶段 5：IMPLEMENTING

按顺序执行 tasks.md 中的任务。对每项任务：

1. 阅读任务描述
2. 实现变更
3. 在 tasks.md 中将任务标记为 [x]
4. 如有相关测试，则运行测试

钩子：pre_stage_IMPLEMENTING → tdd-coach

阶段 6：TESTING

运行完整测试套件。更新 checklist.md：

# Checklist

## Code Quality
- [ ] Implementation complete
- [ ] Lint clean (run lint command)
- [ ] Type check pass (run typecheck command)

## Tests
- [ ] Unit tests pass
- [ ] Integration tests pass (if applicable)

## Acceptance Criteria
- [ ] AC 1: {criterion from spec} — verified
- [ ] AC 2: {criterion from spec} — verified

## Review
- [ ] Self-review complete
- [ ] No TODO/FIXME left unresolved

钩子：pre_stage_TESTING → test-strategy-advisor、test-strategist、code-reviewer

阶段 7：DELIVERING（仅限规范模式）

根据 spec.md 进行最终验证。确保每项验收标准均已满足。

钩子：post_stage_DELIVERING → code-reviewer、tech-design-reviewer

阶段 8：DONE

工作流完成。输出摘要：

• 交付内容
• 变更的文件
• 通过的测试
• 已用时间

阶段推进

# Check current status
node status.cjs -r <project_root>

# Advance to next stage
node advance.cjs -r <project_root>

# Force advance (skip checkpoint)
node advance.cjs -r <project_root> --force

钩子系统

钩子是在阶段转换时运行的 Agent/技能。包含三个作用域：

作用域	文件	优先级
全局	hooks.yaml（技能目录）	最低
项目	.trae/workflow/hooks.yaml	中
工作流	workflow.yaml（工作流目录中）	最高

钩子点

钩子	时机	默认 Agent
pre_stage_DEFINING	填写规范前	iron-audit-pm, risk-auditor
pre_stage_PLANNING	任务拆分前	story-mapper, mvp-freeze-architect
pre_stage_DESIGNING	架构设计前	domain-modeler, architecture-advisor
pre_stage_IMPLEMENTING	编码前	tdd-coach
pre_stage_TESTING	测试阶段前	test-strategy-advisor, code-reviewer
post_stage_DELIVERING	最终检查后	tech-design-reviewer

# List hooks
node hooks.cjs -r <project_root> list

# Add a hook
node hooks.cjs -r <project_root> add pre_stage_TESTING -n my-validator --type skill

质量门禁

检查点规则

阶段	检查点触发条件
DEFINING	risk = elevated 或 critical
PLANNING	size = large 或 risk ≥ elevated
DESIGNING	size ≥ medium 或 risk ≥ elevated
TESTING	始终触发（所有风险等级）

在检查点，AI 会暂停并询问用户，确认后再继续。

SDD 可追溯性规则

每一行代码都必须追溯到：

1. tasks.md 中的一个任务
2. 该任务可追溯到 spec.md 中的一项验收标准

如果发现自己编写的代码没有任何任务覆盖，请停止并先更新 tasks.md。

错误处理

问题	解决方案
用户提出的请求含糊不清	归类为 feature/small，使用 Agent Mode，在实现过程中细化
规范不完整	在进入 PLANNING 前补充缺失的验收标准
任务过大	拆分为子任务，每个子任务最多修改 1 个文件
TESTING 期间测试失败	留在 TESTING，修复问题并重新运行
用户拒绝检查点	留在当前阶段，根据反馈修改产物
工作流中止	无需清理，状态会保留在 .trae/workflow/ 中

脚本

脚本	用途
init.cjs	根据分类初始化工作流
advance.cjs	进入下一阶段
status.cjs	显示当前工作流状态
hooks.cjs	管理钩子注册
lib/common.cjs	共享 YAML 工具

Agent

完整注册表请参见 AGENTS.md。各阶段的关键 Agent：

阶段	Agent	方法论
DEFINING	iron-audit-pm	PRD 审核、DNA 提取
DEFINING	risk-auditor	风险扫描
DEFINING	problem-definer	Weinberg 问题分析
PLANNING	story-mapper	Patton 用户故事映射
PLANNING	mvp-freeze-architect	范围冻结
DESIGNING	domain-modeler	DDD/Evans 建模
DESIGNING	architecture-advisor	质量属性
IMPLEMENTING	tdd-coach	Beck TDD 循环
TESTING	test-strategist	Crispin 测试策略
TESTING	code-reviewer	代码审查
DELIVERING	tech-design-reviewer	架构审查

参考资料

• 快速参考 - 精简决策表