Back to Details

devdocs-dev-workflow

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

开发工作流

Development Workflow

执行单个开发任务的工作流指导，采用自顶向下开发模式和分层 TDD。
Workflow guidance for executing individual development tasks, using top-down development mode and layered TDD.

语言规则

Language Rules

  • 支持中英文提问
  • 统一中文回复
  • Supports Chinese and English queries
  • Responses are uniformly in Chinese

触发条件

Trigger Conditions

  • 用户开始执行某个任务（如 T-01）
  • 用户需要开发指导
  • 用户从 devdocs-dev-tasks 进入开发阶段
  • 关键词："开发任务"、"执行任务"、"开始 T-XX"
  • User starts executing a task (e.g., T-01)
  • User needs development guidance
  • User enters the development phase from devdocs-dev-tasks
  • Keywords: "execute task", "start T-XX", "开发任务", "执行任务"

前置条件

Preconditions

  • 任务文档：
    docs/devdocs/04-dev-tasks.md
  • 任务已定义并包含：关联需求、验收标准、测试方法
  • Task document: 
    docs/devdocs/04-dev-tasks.md
  • Task is defined and includes: associated requirements, acceptance criteria, testing methods

工作流程

Workflow

1. 读取任务定义
   ├── 从 04-dev-tasks.md 获取任务详情
   ├── 确认关联的 F-XXX、AC-XXX
   └── 确认关联的测试用例 UT/IT/E2E-XXX
           │
           ▼
2. 生成骨架代码（自顶向下）
   ├── 接口骨架 + @requirement/@satisfies 标注
   └── 测试骨架 + @verifies/@testcase 标注
           │
           ▼
3. 执行开发（分层 TDD）
   ├── 核心逻辑 🔴：测试先行
   ├── 接口层 🟡：推荐测试先行
   ├── UI 层 🟢：可实现后补测试
   └── 基础设施 ⚪：集成测试验证
           │
           ▼
4. 完成检查
   ├── 基础检查（始终执行）
   │   ├── 验收标准全部满足
   │   ├── 测试通过
   │   └── Review 要点自查
   │
   └── 对抗式验证（🔴自动触发 / 其他层级 --review 手动触发）
       ├── 🔍 代码质量审查（/code-quality 视角）
       ├── 🧪 测试完备性审查（/testing-guide 视角）
       └── 📋 综合审查报告
           │
           ▼
4.5 更新自描述（/code-self-describe --update）
           │
           ▼
5. 提交代码（遵循 /commit-convention）
           │
           ▼
6. 更新追溯（运行 /devdocs-sync --trace）
1. Read Task Definition
   ├── Retrieve task details from 04-dev-tasks.md
   ├── Confirm associated F-XXX, AC-XXX
   └── Confirm associated test cases UT/IT/E2E-XXX
           │
           ▼
2. Generate Skeleton Code (Top-Down)
   ├── Interface skeleton + @requirement/@satisfies annotations
   └── Test skeleton + @verifies/@testcase annotations
           │
           ▼
3. Execute Development (Layered TDD)
   ├── Core Logic 🔴: Test-first
   ├── Interface Layer 🟡: Recommended test-first
   ├── UI Layer 🟢: Tests can be added after implementation
   └── Infrastructure ⚪: Verified via integration tests
           │
           ▼
4. Completion Check
   ├── Basic Check (Always Executed)
   │   ├── All acceptance criteria are satisfied
   │   ├── Tests pass
   │   └── Self-check of review points
   │
   └── Adversarial Verification (🔴 Auto-triggered / Manual trigger via --review for other layers)
       ├── 🔍 Code Quality Review (from /code-quality perspective)
       ├── 🧪 Test Completeness Review (from /testing-guide perspective)
       └── 📋 Comprehensive Review Report
           │
           ▼
4.5 Update Self-description (Run /code-self-describe --update)
           │
           ▼
5. Submit Code (Follow /commit-convention)
           │
           ▼
6. Update Traceability (Run /devdocs-sync --trace)

代码追溯标注规范

Code Traceability Annotation Specification

实现文档↔代码的双向追溯，AI 在生成代码时自动添加标注。
Achieve two-way traceability between documents and code; AI automatically adds annotations when generating code.

标注类型

Annotation Types

标注用途位置
@requirement F-XXX
关联功能点接口/类/模块
@satisfies AC-XXX
满足的验收标准接口/方法
@verifies AC-XXX
验证的验收标准测试用例
@testcase UT/IT/E2E-XXX
测试编号测试用例
AnnotationPurposeLocation
@requirement F-XXX
Associate with feature pointsInterface/Class/Module
@satisfies AC-XXX
Meets acceptance criteriaInterface/Method
@verifies AC-XXX
Verifies acceptance criteriaTest Case
@testcase UT/IT/E2E-XXX
Test IDTest Case

标注示例

Annotation Example

typescript
/**
 * 创建用户
 * @requirement F-001 - 用户注册
 * @satisfies AC-001 - 邮箱格式校验
 * @satisfies AC-002 - 密码强度校验
 */
export async function createUser(dto: CreateUserDTO): Promise<User> {
  // 实现代码
}

/**
 * @verifies AC-001 - 邮箱格式校验
 * @testcase UT-001
 */
test('createUser 应该拒绝无效邮箱格式', () => {
  // 测试代码
});
typescript
/**
 * Create User
 * @requirement F-001 - User Registration
 * @satisfies AC-001 - Email Format Validation
 * @satisfies AC-002 - Password Strength Validation
 */
export async function createUser(dto: CreateUserDTO): Promise<User> {
  // Implementation code
}

/**
 * @verifies AC-001 - Email Format Validation
 * @testcase UT-001
 */
test('createUser should reject invalid email formats', () => {
  // Test code
});

标注规则

Annotation Rules

层级标注位置强制性
公共接口Service/API 入口方法必须
测试文件每个测试用例必须
内部实现复杂逻辑可选
LevelAnnotation LocationMandatory
Public InterfaceService/API entry methodRequired
Test FilesEach test caseRequired
Internal ImplementationComplex logicOptional
See skeleton-examples.md for details

自顶向下开发模式

Top-Down Development Mode

先定义骨架，后填充细节。确保追溯链在代码生成时就建立。
Define the skeleton first, then fill in the details. Ensure the traceability chain is established during code generation.

开发流程

Development Process

Step 1: 生成接口骨架
        ├── 方法签名（来自 02-system-design.md）
        ├── 添加 @requirement/@satisfies 标注
        └── 方法体: throw new Error('Not implemented')
                │
                ▼
Step 2: 生成测试骨架
        ├── 测试结构（来自 03-test-cases.md）
        ├── 添加 @verifies/@testcase 标注
        └── 测试体: test.skip() 或 test.todo()
                │
                ▼
Step 3: 实现接口细节（遵循 /code-quality）
                │
                ▼
Step 4: 完善测试（遵循 /testing-guide）
                │
                ▼
Step 5: 运行 /devdocs-sync --trace 更新追溯矩阵
Step 1: Generate Interface Skeleton
        ├── Method signature (from 02-system-design.md)
        ├── Add @requirement/@satisfies annotations
        └── Method body: throw new Error('Not implemented')
                │
                ▼
Step 2: Generate Test Skeleton
        ├── Test structure (from 03-test-cases.md)
        ├── Add @verifies/@testcase annotations
        └── Test body: test.skip() or test.todo()
                │
                ▼
Step 3: Implement Interface Details (Follow /code-quality)
                │
                ▼
Step 4: Improve Tests (Follow /testing-guide)
                │
                ▼
Step 5: Run /devdocs-sync --trace to update traceability matrix

骨架生成约束

Skeleton Generation Constraints

  • 接口骨架必须包含完整签名（参数、返回值、泛型）
  • 接口骨架必须添加追溯标注
  • 未实现方法必须抛出 Error 并注明任务编号
  • 测试骨架必须使用 skip/todo 标记
  • 测试骨架必须添加 @verifies 和 @testcase 标注
详见 skeleton-examples.md
  • Interface skeleton must include complete signature (parameters, return value, generics)
  • Interface skeleton must add traceability annotations
  • Unimplemented methods must throw an Error and indicate the task ID
  • Test skeleton must use skip/todo markers
  • Test skeleton must add @verifies and @testcase annotations

分层 TDD 模式

Layered TDD Mode

根据任务类型决定测试优先级：
层级TDD 模式说明
核心逻辑 (Service/Domain)🔴 强制测试先行
接口层 (Controller/API)🟡 推荐建议测试先行
UI 层 (Component/View)🟢 可选可实现后补
基础设施 (DB/Config)⚪ 不适用集成测试验证
Determine test priority based on task type:
LayerTDD ModeDescription
Core Logic (Service/Domain)🔴 MandatoryTest-first
Interface Layer (Controller/API)🟡 RecommendedRecommended to use test-first
UI Layer (Component/View)🟢 OptionalTests can be added after implementation
Infrastructure (DB/Config)⚪ Not ApplicableVerified via integration tests

TDD 循环

TDD Cycle

┌─────┐    ┌─────┐    ┌─────┐
│ 红  │ → │ 绿  │ → │重构 │ ──┐
│写测试│    │写实现│    │优化 │   │
│(失败)│    │(通过)│    │代码 │   │
└─────┘    └─────┘    └─────┘   │
    ↑                           │
    └───────────────────────────┘
详细执行流程见 execution-flow.md
┌─────┐    ┌─────┐    ┌─────┐
│ Red │ → │ Green│ → │Refactor│ ──┐
│Write Test│    │Write Code│    │Optimize│   │
│(Fails)│    │(Passes)│    │Code │   │
└─────┘    └─────┘    └─────┘   │
    ↑                           │
    └───────────────────────────┘
See execution-flow.md for detailed execution process

Skill 协作

Skill Collaboration

阶段协作 Skill说明
写业务代码
/code-quality
MTE 原则、依赖注入、避免过度设计
写测试代码
/testing-guide
断言质量、变异测试、覆盖率
UI 实现
/ui-orchestrator
无障碍、动画、布局约束
完成验证
/code-quality
+ 
/testing-guide
对抗式验证：多视角审查
完成检查
/code-self-describe
更新模块自描述（--update）
代码提交
/git-safety
使用 git mv/rm 处理文件
提交信息
/commit-convention
遵循项目提交规范
任务完成
/devdocs-sync
后续：更新追溯矩阵（--trace）
PhaseCollaborating SkillDescription
Writing business code
/code-quality
MTE principles, dependency injection, avoid over-engineering
Writing test code
/testing-guide
Assertion quality, mutation testing, coverage
UI implementation
/ui-orchestrator
Accessibility, animations, layout constraints
Completion verification
/code-quality
+ 
/testing-guide
Adversarial verification: multi-perspective review
Completion check
/code-self-describe
Update module self-description (--update)
Code submission
/git-safety
Use git mv/rm for file operations
Commit message
/commit-convention
Follow project commit conventions
Task completion
/devdocs-sync
Follow-up: Update traceability matrix (--trace)

约束

Constraints

骨架生成约束

Skeleton Generation Constraints

  • 接口骨架必须包含完整签名
  • 接口骨架必须添加追溯标注
  • 未实现方法必须抛出 Error
  • 测试骨架必须使用 skip/todo 标记
  • 测试骨架必须添加 @verifies 和 @testcase 标注
  • Interface skeleton must include complete signature
  • Interface skeleton must add traceability annotations
  • Unimplemented methods must throw an Error
  • Test skeleton must use skip/todo markers
  • Test skeleton must add @verifies and @testcase annotations

分层 TDD 约束

Layered TDD Constraints

  • 核心逻辑任务必须标记 🔴 强制 TDD
  • 核心逻辑任务必须先写测试，后写实现
  • 核心逻辑任务禁止在测试通过前提交
  • 接口层任务标记 🟡 推荐 TDD
  • UI 层任务标记 🟢 可选 TDD
  • 基础设施任务标记 ⚪ 不适用 TDD
  • TDD 任务必须包含红-绿-重构三步骤
  • Core logic tasks must be marked 🔴 Mandatory TDD
  • Core logic tasks must write tests first, then implementation
  • Core logic tasks cannot be submitted before tests pass
  • Interface layer tasks are marked 🟡 Recommended TDD
  • UI layer tasks are marked 🟢 Optional TDD
  • Infrastructure tasks are marked ⚪ Not Applicable TDD
  • TDD tasks must include red-green-refactor three steps

完成检查约束

Completion Check Constraints

  • 验收标准 (AC-XXX) 全部满足
  • 关联测试全部通过
  • Review 要点自查完成
  • 代码追溯标注完整
  • 代码分支覆盖分析完成（可选，使用 
    /testing-guide
    分支分析）
  • All acceptance criteria (AC-XXX) are satisfied
  • All associated tests pass
  • Self-check of review points is completed
  • Code traceability annotations are complete
  • Code branch coverage analysis is completed (Optional, use /testing-guide branch analysis)

对抗式验证（可选）

Adversarial Verification (Optional)

以不同角色视角审查代码，模拟 "开发 → 审查 → 测试" 的多人协作模式。 核心逻辑任务（🔴）自动触发，其他层级通过 
--review
手动触发。
Review code from different role perspectives, simulating the multi-person collaboration mode of "Development → Review → Testing". Core logic tasks (🔴) trigger automatically; other layers are triggered manually via 
--review
.

触发条件

Trigger Conditions

层级判定：任务层级标记（🔴🟡🟢⚪）来自 
04-dev-tasks.md
中的任务定义，由 
/devdocs-dev-tasks
在任务拆分时根据任务分层规则分配。
任务层级默认行为手动控制
🔴 核心逻辑自动触发
--skip-review
跳过
🟡 接口层不触发
--review
启用
🟢 UI 层不触发
--review
启用
⚪ 基础设施不触发
--review
启用
Layer Determination: Task layer markers (🔴🟡🟢⚪) come from task definitions in 
04-dev-tasks.md
, assigned by 
/devdocs-dev-tasks
during task splitting according to task layering rules.
Task LayerDefault BehaviorManual Control
🔴 Core LogicAutomatically triggered
--skip-review
to skip
🟡 Interface LayerNot triggered
--review
to enable
🟢 UI LayerNot triggered
--review
to enable
⚪ InfrastructureNot triggered
--review
to enable

验证流程

Verification Process

基础完成检查（始终执行）
        │
        ├── AC 全部满足 ✅
        ├── 测试全部通过 ✅
        ├── 代码标注完整 ✅
        │
        ▼ （对抗式验证触发时）
Phase 1: 代码质量审查 🔍
        ├── 切换到 /code-quality 视角
        ├── MTE 原则检查（函数长度/参数/嵌套/职责）
        ├── 依赖方向检查
        ├── 安全检查
        └── 输出: 问题列表（Blocker/Suggestion）
        │
        ▼
Phase 2: 测试完备性审查 🧪
        ├── 切换到 /testing-guide 视角
        ├── 断言质量检查（禁止弱断言）
        ├── 覆盖率检查（行/分支 ≥80%）
        ├── 需求追溯检查（AC 全覆盖）
        ├── [可选] 代码分支覆盖分析
        └── 输出: 问题列表（Blocker/Suggestion）
        │
        ▼
Phase 3: 综合审查报告 📋
        ├── 汇总所有问题
        ├── 🚫 Blocker → 必须修复后重新验证
        └── 💡 Suggestion → 询问用户是否修复
Basic Completion Check (Always Executed)
        │
        ├── All AC satisfied ✅
        ├── All tests pass ✅
        ├── Code annotations complete ✅
        │
        ▼ (When adversarial verification is triggered)
Phase 1: Code Quality Review 🔍
        ├── Switch to /code-quality perspective
        ├── MTE principle check (function length/parameters/nesting/responsibilities)
        ├── Dependency direction check
        ├── Security check
        └── Output: Issue list (Blocker/Suggestion)
        │
        ▼
Phase 2: Test Completeness Review 🧪
        ├── Switch to /testing-guide perspective
        ├── Assertion quality check (forbid weak assertions)
        ├── Coverage check (line/branch ≥80%)
        ├── Requirement traceability check (full AC coverage)
        ├── [Optional] Code branch coverage analysis
        └── Output: Issue list (Blocker/Suggestion)
        │
        ▼
Phase 3: Comprehensive Review Report 📋
        ├── Summarize all issues
        ├── 🚫 Blocker → Must fix before re-verification
        └── 💡 Suggestion → Ask user if they want to fix

审查结果分级

Review Result Levels

级别标记处理
🚫 Blocker必须修复阻止提交，修复后重新验证
💡 Suggestion建议修复询问用户，可选择忽略
LevelMarkerHandling
🚫 BlockerMust fixBlocks submission; re-verify after fixing
💡 SuggestionRecommended to fixAsk user; can choose to ignore

对抗式验证约束

Adversarial Verification Constraints

  • Blocker 问题必须修复后才能提交
  • 每个 Phase 必须明确声明当前审查角色
  • 审查结果必须分级（Blocker/Suggestion）
  • 核心逻辑任务（🔴）默认触发
  • 修复 Blocker 后必须重新运行验证
详细审查清单和报告模板见 verification-flow.md
  • Blocker issues must be fixed before submission
  • Each phase must clearly state the current review role
  • Review results must be classified (Blocker/Suggestion)
  • Core logic tasks (🔴) are triggered by default
  • Must re-run verification after fixing Blocker issues
See verification-flow.md for detailed review checklist and report template

任务完成流程

Task Completion Process

TDD 任务（核心逻辑 🔴）

TDD Tasks (Core Logic 🔴)

  1. 确认测试先行：检查是否先写了测试
  2. 确认红-绿循环：测试从失败到通过
  3. 检查重构：代码是否经过优化
  4. 验证验收标准：检查所有 AC 是否满足
  5. 对抗式验证（自动触发）：
    • Phase 1: 代码质量审查（/code-quality 视角）
    • Phase 2: 测试完备性审查（/testing-guide 视角）
    • Phase 3: 综合报告，处理 Blocker
  6. 更新自描述：运行 /code-self-describe --update
  7. 询问提交：使用 AskUserQuestion 询问：
    • "任务 T-XX（TDD）已完成，测试通过，是否提交代码？"
    • 选项："提交" / "继续修改" / "跳过"
  8. 如提交：执行 git add 和 commit，消息包含任务编号
  9. 更新状态：将任务标记为已完成
  1. Confirm test-first approach: Check if tests were written first
  2. Confirm red-green cycle: Tests go from failed to passed
  3. Check refactoring: Whether code has been optimized
  4. Verify acceptance criteria: Check if all AC are satisfied
  5. Adversarial Verification (Auto-triggered):
    • Phase 1: Code Quality Review (from /code-quality perspective)
    • Phase 2: Test Completeness Review (from /testing-guide perspective)
    • Phase 3: Comprehensive report, handle Blockers
  6. Update self-description: Run /code-self-describe --update
  7. Ask for submission: Use AskUserQuestion to ask:
    • "Task T-XX (TDD) is completed, tests passed. Do you want to submit the code?"
    • Options: "Submit" / "Continue modifying" / "Skip"
  8. If submit: Execute git add and commit, with task ID included in the message
  9. Update status: Mark the task as completed

非 TDD 任务（接口/UI/基础设施）

Non-TDD Tasks (Interface/UI/Infrastructure)

  1. 执行测试：运行任务定义的测试方法
  2. 验证验收标准：检查所有验收标准是否满足
  3. 对抗式验证（如 --review 触发）：同上 Phase 1-3
  4. 自查 Review 要点：检查代码审查要点
  5. 询问提交：使用 AskUserQuestion 询问
  6. 如提交：执行 git add 和 commit
  7. 更新状态：将任务标记为已完成
  1. Execute tests: Run the testing methods defined in the task
  2. Verify acceptance criteria: Check if all acceptance criteria are satisfied
  3. Adversarial Verification (If triggered via --review): Same as Phase 1-3 above
  4. Self-check review points: Check code review points
  5. Ask for submission: Use AskUserQuestion to ask
  6. If submit: Execute git add and commit
  7. Update status: Mark the task as completed

提交信息格式

Commit Message Format

遵循 
/commit-convention
规范，格式如下：
<type>(T-XX): <任务名称>

- <完成内容1>
- <完成内容2>

关联: F-XXX, AC-XXX
测试: UT-XXX, IT-XXX 通过
type 类型：feat | fix | refactor | test | docs | chore
Follow the 
/commit-convention
specification, with the following format:
<type>(T-XX): <Task Name>

- <Completed Item 1>
- <Completed Item 2>

Related: F-XXX, AC-XXX
Tests: UT-XXX, IT-XXX Passed
Type Values: feat | fix | refactor | test | docs | chore

参考资料

References

  • skeleton-examples.md - 接口/测试骨架示例
  • execution-flow.md - 任务执行流程详解
  • verification-flow.md - 对抗式验证流程详解
  • skeleton-examples.md - Interface/test skeleton examples
  • execution-flow.md - Detailed task execution process
  • verification-flow.md - Detailed adversarial verification process