Back to Details

requirement-workflow

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Requirement Workflow Orchestrator

需求工作流编排器

A state-machine driven orchestrator that provides structured development workflows for requirements of varying complexity.
一款基于状态机的编排器，为不同复杂度的需求提供结构化开发工作流。

When to Use

适用场景

Invoke this skill when:
  • User requests feature development: "build a user authentication system"
  • User needs bug fixes: "fix the login issue", "this button doesn't work"
  • User wants refactoring: "refactor this module", "clean up this code"
  • User asks about progress: "what's the status?", "where are we?"
  • Keywords detected: 
    feature
    , 
    bugfix
    , 
    refactor
    , 
    implement
    , 
    develop
    , 
    build
Do NOT invoke this skill when:
  • Simple Q&A or code explanations (no workflow needed)
  • Single-line code changes (too trivial for workflow tracking)
  • User explicitly declines: "just fix it, no workflow"
  • Only checking status of existing workflow (use 
    get-status.sh
    directly)
在以下场景调用本技能：
  • 用户请求功能开发："build a user authentication system"（开发用户认证系统）
  • 用户需要修复Bug："fix the login issue"（修复登录问题）、"this button doesn't work"（这个按钮无法正常工作）
  • 用户需要重构代码："refactor this module"（重构该模块）、"clean up this code"（清理这段代码）
  • 用户询问进度："what's the status?"（进度如何？）、"where are we?"（当前到哪一步了？）
  • 检测到关键词：
    feature
    、
    bugfix
    、
    refactor
    、
    implement
    、
    develop
    、
    build
请勿在以下场景调用本技能：
  • 简单问答或代码解释（无需工作流）
  • 单行代码修改（过于琐碎，无需工作流跟踪）
  • 用户明确拒绝："just fix it, no workflow"（直接修复，不要工作流）
  • 仅查询现有工作流状态（直接使用
    get-status.sh
    ）

Quick Start

快速开始

Step 1: Determine Requirement Level

步骤1：确定需求级别

LevelNameUse CaseEst. Time
L1QuickBug fixes, config changes, minor tweaks< 1h
L2StandardRegular feature development, API changes1-8h
L3FullComplex features, cross-module, security-sensitive> 8h
📖 See Level Selection Guide for detailed criteria
级别名称适用场景预计耗时
L1快速处理Bug修复、配置变更、小调整< 1小时
L2标准流程常规功能开发、API变更1-8小时
L3完整流程复杂功能、跨模块、安全敏感需求> 8小时
📖 详细标准请参考 级别选择指南

Step 2: Initialize Workflow

步骤2：初始化工作流

bash
./scripts/init-workflow.sh -r <project_root> -n <name> -t <type> [-l <level>]
Required Parameters:
  • -r, --root
    : Project root directory
  • -n, --name
    : Requirement name (lowercase, hyphenated)
Optional Parameters:
  • -t, --type
    : 
    feature
    | 
    bugfix
    | 
    refactor
    | 
    hotfix
    (default: feature)
  • -l, --level
    : 
    L1
    | 
    L2
    | 
    L3
    (default: L2)
Output:
  • Creates 
    .trae/workflow/{date}_{seq}_{type}_{name}/
    directory
  • Sets as active workflow (
    .trae/active_workflow
    )
bash
./scripts/init-workflow.sh -r <project_root> -n <name> -t <type> [-l <level>]
必填参数：
  • -r, --root
    ：项目根目录
  • -n, --name
    ：需求名称（小写，连字符分隔）
可选参数：
  • -t, --type
    ：
    feature
    | 
    bugfix
    | 
    refactor
    | 
    hotfix
    （默认：feature）
  • -l, --level
    ：
    L1
    | 
    L2
    | 
    L3
    （默认：L2）
输出：
  • 创建 
    .trae/workflow/{date}_{seq}_{type}_{name}/
    目录
  • 设置为当前活跃工作流（
    .trae/active_workflow
    ）

Step 3: Execute Workflow by Level

步骤3：按级别执行工作流

LevelFlowReference
L1PLANNING → IMPLEMENTING → TESTINGL1 Workflow
L2ANALYZING → PLANNING → DESIGNING → IMPLEMENTING → TESTING → DELIVERINGL2 Workflow
L3Extended analysis → Architecture review → Security audit → Implementation → Testing → ApprovalL3 Workflow
级别流程参考文档
L1PLANNING → IMPLEMENTING → TESTINGL1 快速工作流
L2ANALYZING → PLANNING → DESIGNING → IMPLEMENTING → TESTING → DELIVERINGL2 标准工作流
L3扩展分析 → 架构评审 → 安全审计 → 开发实现 → 测试 → 审批L3 完整工作流

Step 4: Progress and Status Management

步骤4：进度与状态管理

bash
./scripts/get-status.sh -r <project_root>           # Check status
./scripts/advance-stage.sh -r <project_root>        # Advance to next stage
./scripts/generate-report.sh -r <project_root>      # Generate report
bash
./scripts/get-status.sh -r <project_root>           # 查看状态
./scripts/advance-stage.sh -r <project_root>        # 推进到下一阶段
./scripts/generate-report.sh -r <project_root>      # 生成报告

Stage Execution Pattern

阶段执行规范

Every stage MUST follow this structure:
每个阶段必须遵循以下结构：

1. Stage Entry (Planning)

1. 阶段进入（规划）

📍 [STAGE_NAME] Starting

🎯 Objectives:
- {objective_1}
- {objective_2}

📋 Tasks:
1. {task_1}
2. {task_2}

📄 Expected Outputs:
- {output_file_1}
- {output_file_2}
📍 [STAGE_NAME] 启动

🎯 目标：
- {目标1}
- {目标2}

📋 任务：
1. {任务1}
2. {任务2}

📄 预期输出：
- {输出文件1}
- {输出文件2}

2. Stage Execution

2. 阶段执行

  • Use TodoWrite to track task progress
  • Execute tasks in order
  • Update output files in real-time
  • 使用 TodoWrite 跟踪任务进度
  • 按顺序执行任务
  • 实时更新输出文件

3. Stage Exit (Summary)

3. 阶段退出（总结）

✅ [STAGE_NAME] Completed

📊 Summary:
- Tasks completed: {N}/{M}
- Duration: {duration}

📄 Outputs:
- {file_1}: {brief_description}
- {file_2}: {brief_description}

➡️ Next Stage: {NEXT_STAGE}
Prerequisites: {what_next_stage_needs}
✅ [STAGE_NAME] 完成

📊 总结：
- 已完成任务：{N}/{M}
- 耗时：{duration}

📄 输出文件：
- {文件1}：{简要描述}
- {文件2}：{简要描述}

➡️ 下一阶段：{NEXT_STAGE}
前置条件：{下一阶段所需条件}

Stage Document Requirements

阶段文档要求

Each stage has explicit input and output documents:
StageInput (Prerequisites)Output (Must Produce)
ANALYZINGUser requirement
spec.md
(PRD)
PLANNING
spec.md
tasks.md
DESIGNING
spec.md
, 
tasks.md
design.md
IMPLEMENTING
design.md
, 
tasks.md
Code files, 
logs/impl.md
TESTINGCode files
checklist.md
DELIVERING
checklist.md
(all passed)
artifacts/report.md
每个阶段都有明确的输入和输出文档：
阶段输入（前置条件）输出（必须生成）
ANALYZING用户需求
spec.md
（产品需求文档）
PLANNING
spec.md
tasks.md
（任务分解文档）
DESIGNING
spec.md
、
tasks.md
design.md
（技术设计文档）
IMPLEMENTING
design.md
、
tasks.md
代码文件、
logs/impl.md
（开发日志）
TESTING代码文件
checklist.md
（测试 checklist）
DELIVERING
checklist.md
（全部通过）
artifacts/report.md
（交付报告）

Document Specifications

文档规范

1. spec.md - Product Requirements Document

1. spec.md - 产品需求文档

Stage: ANALYZING Contents:
  • Background and objectives
  • User stories
  • Scope (In/Out)
  • Acceptance criteria
  • Constraints
阶段： ANALYZING 内容：
  • 背景与目标
  • 用户故事
  • 范围（包含/排除）
  • 验收标准
  • 约束条件

2. tasks.md - Task Breakdown

2. tasks.md - 任务分解文档

Stage: PLANNING Contents:
  • Task list with priorities
  • Time estimates
  • Dependencies
  • Assignees (if applicable)
阶段： PLANNING 内容：
  • 带优先级的任务列表
  • 时间估算
  • 依赖关系
  • 负责人（如有）

3. design.md - Technical Design

3. design.md - 技术设计文档

Stage: DESIGNING Contents:
  • Solution overview
  • Architecture design
  • API design (if applicable)
  • Data models
  • Risk assessment
阶段： DESIGNING 内容：
  • 方案概述
  • 架构设计
  • API设计（如适用）
  • 数据模型
  • 风险评估

4. logs/impl.md - Implementation Log

4. logs/impl.md - 开发日志

Stage: IMPLEMENTING Contents:
  • Progress tracking
  • Issues encountered and solutions
  • Code change summary
阶段： IMPLEMENTING 内容：
  • 进度跟踪
  • 遇到的问题及解决方案
  • 代码变更总结

5. checklist.md - Test Checklist

5. checklist.md - 测试 checklist

Stage: TESTING Contents:
  • Code quality checks (Lint, Type)
  • Test results
  • Coverage metrics
  • Security checks (if applicable)
阶段： TESTING 内容：
  • 代码质量检查（Lint、类型检查）
  • 测试结果
  • 覆盖率指标
  • 安全检查（如适用）

6. artifacts/report.md - Delivery Report

6. artifacts/report.md - 交付报告

Stage: DELIVERING Contents:
  • Workflow summary
  • Completed tasks
  • Change list
  • Test results
  • Lessons learned
阶段： DELIVERING 内容：
  • 工作流总结
  • 已完成任务
  • 变更列表
  • 测试结果
  • 经验总结

Workflow Levels Overview

工作流级别概述

L1: Quick Workflow

L1: 快速工作流

INIT → PLANNING → IMPLEMENTING → TESTING → DONE
  • Skip: spec.md, design.md
  • Required: tasks.md, checklist.md
  • Best for: Clear, low-risk changes
INIT → PLANNING → IMPLEMENTING → TESTING → DONE
  • 跳过： spec.md、design.md
  • 必需： tasks.md、checklist.md
  • 最佳适用： 明确、低风险的变更

L2: Standard Workflow

L2: 标准工作流

INIT → ANALYZING → PLANNING → DESIGNING → IMPLEMENTING → TESTING → DELIVERING → DONE
  • Full documentation: spec.md, design.md, tasks.md, checklist.md, report.md
  • Best for: Most feature development
INIT → ANALYZING → PLANNING → DESIGNING → IMPLEMENTING → TESTING → DELIVERING → DONE
  • 完整文档： spec.md、design.md、tasks.md、checklist.md、report.md
  • 最佳适用： 大多数功能开发场景

L3: Full Workflow

L3: 完整工作流

INIT → ANALYZING(ext) → PLANNING(ext) → DESIGNING(ext) → IMPLEMENTING → TESTING → DELIVERING → DONE
  • Extended stages: Threat modeling, architecture review, compliance check
  • Mandatory approvals: Security team / Tech Lead sign-off
  • Best for: Security-sensitive, cross-module, breaking changes
INIT → ANALYZING(ext) → PLANNING(ext) → DESIGNING(ext) → IMPLEMENTING → TESTING → DELIVERING → DONE
  • 扩展阶段： 威胁建模、架构评审、合规检查
  • 强制审批： 安全团队/技术负责人签字确认
  • 最佳适用： 安全敏感、跨模块、破坏性变更

Working Directory Structure

工作目录结构

.trae/
├── active_workflow              # Path to current active workflow
└── workflow/
    └── {date}_{seq}_{type}_{name}/
        ├── workflow.yaml        # Workflow state
        ├── spec.md              # Requirements (L2, L3)
        ├── design.md            # Technical design (L2, L3)
        ├── tasks.md             # Task breakdown
        ├── checklist.md         # Test checklist
        ├── logs/
        │   └── impl.md          # Implementation log
        └── artifacts/
            └── report.md        # Final report
.trae/
├── active_workflow              # 当前活跃工作流的路径
└── workflow/
    └── {date}_{seq}_{type}_{name}/
        ├── workflow.yaml        # 工作流状态
        ├── spec.md              # 需求文档（L2、L3）
        ├── design.md            # 技术设计文档（L2、L3）
        ├── tasks.md             # 任务分解文档
        ├── checklist.md         # 测试 checklist
        ├── logs/
        │   └── impl.md          # 开发日志
        └── artifacts/
            └── report.md        # 最终报告

Scripts Quick Reference

脚本速查

ScriptPurposeRequired Args
init-workflow.sh
Initialize workflow
-r ROOT
, 
-n NAME
get-status.sh
Check status
-r ROOT
advance-stage.sh
Advance stage
-r ROOT
inject-skill.sh
Inject skill
-r ROOT
generate-report.sh
Generate report
-r ROOT
脚本用途必填参数
init-workflow.sh
初始化工作流
-r ROOT
、
-n NAME
get-status.sh
查看状态
-r ROOT
advance-stage.sh
推进阶段
-r ROOT
inject-skill.sh
注入技能
-r ROOT
generate-report.sh
生成报告
-r ROOT

Examples

示例

Example 1: Bug Fix (L1)

示例1：Bug修复（L1）

User: The login button doesn't respond when clicked

AI: This is a clear bug. Using L1 Quick workflow.

📊 Analysis:
- Type: bugfix
- Level: L1 (Quick)
- Impact: 1 file

Initializing workflow...
✅ Workflow: 20240115_001_bugfix_fix-login-button

[PLANNING] Analyzing and planning fix
- Found: onClick handler has typo

[IMPLEMENTING] Executing fix
- Fixed: handleLgoin → handleLogin

[TESTING] Verifying
- ✅ TypeScript: passed
- ✅ ESLint: passed
- ✅ Tests: passed

[DONE] Workflow complete
- Duration: ~5 minutes
- Files changed: 1
用户：登录按钮点击无响应

AI：这是明确的Bug，使用L1快速工作流。

📊 分析：
- 类型：bugfix
- 级别：L1（快速）
- 影响范围：1个文件

初始化工作流...
✅ 工作流：20240115_001_bugfix_fix-login-button

[PLANNING] 分析并规划修复方案
- 问题：onClick处理函数存在拼写错误

[IMPLEMENTING] 执行修复
- 修复：handleLgoin → handleLogin

[TESTING] 验证
- ✅ TypeScript检查：通过
- ✅ ESLint检查：通过
- ✅ 测试：通过

[DONE] 工作流完成
- 耗时：约5分钟
- 修改文件数：1

Example 2: New Feature (L2)

示例2：新功能开发（L2）

User: I need a user avatar upload feature

AI: Standard feature development. Using L2 Standard workflow.

📊 Analysis:
- Type: feature
- Level: L2 (Standard)
- Modules: User, Storage

Initializing workflow...
✅ Workflow: 20240115_002_feature_user-avatar-upload

[ANALYZING] Requirements clarification
- Max size: 2MB
- Formats: jpg, png
- Crop: circular preview

[PLANNING] Task breakdown
- 6 tasks identified
- Est. time: 4h

[DESIGNING] Technical design
- API: POST /api/users/avatar
- Storage: S3 /avatars/{userId}/{timestamp}.{ext}

[IMPLEMENTING] Coding
- ✅ All 6 tasks completed

[TESTING] Verification
- ✅ Tests: 12/12 passed
- ✅ Coverage: 75%

[DELIVERING] Report generation
- Report saved to artifacts/report.md

[DONE] Workflow complete
- Duration: 3h 45m
用户：我需要一个用户头像上传功能

AI：标准功能开发，使用L2标准工作流。

📊 分析：
- 类型：feature
- 级别：L2（标准）
- 涉及模块：用户、存储

初始化工作流...
✅ 工作流：20240115_002_feature_user-avatar-upload

[ANALYZING] 需求澄清
- 最大尺寸：2MB
- 支持格式：jpg、png
- 裁剪：圆形预览

[PLANNING] 任务分解
- 识别出6项任务
- 预计耗时：4小时

[DESIGNING] 技术设计
- API：POST /api/users/avatar
- 存储：S3 /avatars/{userId}/{timestamp}.{ext}

[IMPLEMENTING] 编码
- ✅ 所有6项任务完成

[TESTING] 验证
- ✅ 测试：12/12通过
- ✅ 覆盖率：75%

[DELIVERING] 生成报告
- 报告已保存至 artifacts/report.md

[DONE] 工作流完成
- 耗时：3小时45分钟

Example 3: Security Feature (L3)

示例3：安全功能开发（L3）

User: We need to integrate OAuth 2.0 for Google/GitHub login

AI: Security-sensitive feature. Using L3 Full workflow.

📊 Analysis:
- Type: feature
- Level: L3 (Full)
- Security: High
- Requires: Threat modeling, security review

Initializing workflow...
✅ Workflow: 20240115_003_feature_oauth-integration

[ANALYZING - Extended]
Threat modeling (STRIDE):
- Spoofing: High risk → Validate OAuth state
- Token leakage: High risk → HttpOnly cookies

[PLANNING - Extended]
- Timeline: ~5 days
- Rollback strategy: Feature flag

[DESIGNING - Extended]
Security design:
- State: encrypted random + timestamp
- Token: encrypted storage
- Scope: minimal permissions

🔒 Approvals required:
- [ ] Security team
- [ ] Tech Lead

User: Both approved

[IMPLEMENTING] Coding with security scanning
[TESTING - Extended] Security testing passed
[DELIVERING - Extended] Compliance sign-off complete

[DONE] Workflow complete
- Duration: 5 days
- Security review: Passed
用户：我们需要集成OAuth 2.0实现Google/GitHub登录

AI：安全敏感功能，使用L3完整工作流。

📊 分析：
- 类型：feature
- 级别：L3（完整）
- 安全等级：高
- 要求：威胁建模、安全评审

初始化工作流...
✅ 工作流：20240115_003_feature_oauth-integration

[ANALYZING - 扩展]
威胁建模（STRIDE）：
- 仿冒：高风险 → 验证OAuth state
- 令牌泄露：高风险 → 使用HttpOnly Cookie

[PLANNING - 扩展]
- 时间线：约5天
- 回滚策略：功能开关

[DESIGNING - 扩展]
安全设计：
- State：加密随机值+时间戳
- 令牌：加密存储
- 权限范围：最小权限原则

🔒 需要审批：
- [ ] 安全团队
- [ ] 技术负责人

用户：双方已审批

[IMPLEMENTING] 编码并进行安全扫描
[TESTING - 扩展] 安全测试通过
[DELIVERING - 扩展] 合规签字完成

[DONE] 工作流完成
- 耗时：5天
- 安全评审：通过

References

参考资料

Workflow Documentation

工作流文档

  • L1 Quick Workflow
  • L2 Standard Workflow
  • L3 Full Workflow
  • L1 快速工作流
  • L2 标准工作流
  • L3 完整工作流

Technical References

技术参考

  • Level Selection Guide
  • State Machine Specification
  • Skill Injection Guide
  • 级别选择指南
  • 状态机规范
  • 技能注入指南

Templates

模板

  • Document Templates
  • Example Configurations
  • 文档模板
  • 示例配置