workflow-patterns

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Workflow Patterns

工作流模式

Guide for implementing tasks using Conductor's TDD workflow, managing phase checkpoints, handling git commits, and executing the verification protocol that ensures quality throughout implementation.

本指南介绍如何使用Conductor的TDD工作流实现任务、管理阶段检查点、处理Git提交，以及执行可在整个实现过程中保障质量的验证协议。

When to Use This Skill

何时使用此技能

Implementing tasks from a track's plan.md
Following TDD red-green-refactor cycle
Completing phase checkpoints
Managing git commits and notes
Understanding quality assurance gates
Handling verification protocols
Recording progress in plan files

从track的plan.md中实现任务
遵循TDD的红-绿-重构循环
完成阶段检查点
管理Git提交和备注
理解质量保障关卡
处理验证协议
在计划文件中记录进度

TDD Task Lifecycle

TDD任务生命周期

Follow these 11 steps for each task:

每个任务请遵循以下11个步骤：

Step 1: Select Next Task

步骤1：选择下一个任务

Read plan.md and identify the next pending

[ ]

task. Select tasks in order within the current phase. Do not skip ahead to later phases.

阅读plan.md并确定下一个待处理的

[ ]

任务。在当前阶段内按顺序选择任务，不要跳转到后续阶段。

Step 2: Mark as In Progress

步骤2：标记为进行中

Update plan.md to mark the task as

[~]

markdown

- [~] **Task 2.1**: Implement user validation

Commit this status change separately from implementation.

更新plan.md，将任务标记为

[~]

：

markdown

- [~] **Task 2.1**: Implement user validation

将此状态变更与实现代码分开提交。

Step 3: RED - Write Failing Tests

步骤3：红阶段 - 编写失败的测试

Write tests that define the expected behavior before writing implementation:

Create test file if needed
Write test cases covering happy path
Write test cases covering edge cases
Write test cases covering error conditions
Run tests - they should FAIL

Example:

python

def test_validate_user_email_valid():
    user = User(email="test@example.com")
    assert user.validate_email() is True

def test_validate_user_email_invalid():
    user = User(email="invalid")
    assert user.validate_email() is False

在编写实现代码之前，先编写定义预期行为的测试：

如有需要，创建测试文件
编写覆盖正常流程的测试用例
编写覆盖边缘情况的测试用例
编写覆盖错误场景的测试用例
运行测试 - 测试应失败

示例：

python

def test_validate_user_email_valid():
    user = User(email="test@example.com")
    assert user.validate_email() is True

def test_validate_user_email_invalid():
    user = User(email="invalid")
    assert user.validate_email() is False

Step 4: GREEN - Implement Minimum Code

步骤4：绿阶段 - 编写最小化实现代码

Write the minimum code necessary to make tests pass:

Focus on making tests green, not perfection
Avoid premature optimization
Keep implementation simple
Run tests - they should PASS

编写让测试通过所需的最少代码：

专注于让测试变绿，而非追求完美
避免过早优化
保持实现简洁
运行测试 - 测试应通过

Step 5: REFACTOR - Improve Clarity

步骤5：重构阶段 - 提升代码清晰度

With green tests, improve the code:

Extract common patterns
Improve naming
Remove duplication
Simplify logic
Run tests after each change - they should remain GREEN

在测试通过后，优化代码：

提取通用模式
改进命名
消除重复代码
简化逻辑
每次变更后运行测试 - 测试应保持通过状态

Step 6: Verify Coverage

步骤6：验证覆盖率

Check test coverage meets the 80% target:

bash

pytest --cov=module --cov-report=term-missing

If coverage is below 80%:

Identify uncovered lines
Add tests for missing paths
Re-run coverage check

检查测试覆盖率是否达到80%的目标：

bash

pytest --cov=module --cov-report=term-missing

如果覆盖率低于80%：

找出未覆盖的代码行
为缺失的路径添加测试
重新运行覆盖率检查

Step 7: Document Deviations

步骤7：记录偏差

If implementation deviated from plan or introduced new dependencies:

Update tech-stack.md with new dependencies
Note deviations in plan.md task comments
Update spec.md if requirements changed

如果实现与计划不符或引入了新依赖：

在tech-stack.md中更新新依赖
在plan.md的任务注释中记录偏差
如果需求变更，更新spec.md

Step 8: Commit Implementation

步骤8：提交实现代码

Create a focused commit for the task:

bash

git add -A
git commit -m "feat(user): implement email validation

- Add validate_email method to User class
- Handle empty and malformed emails
- Add comprehensive test coverage

Task: 2.1
Track: user-auth_20250115"

Commit message format:

Type: feat, fix, refactor, test, docs, chore
Scope: affected module or component
Summary: imperative, present tense
Body: bullet points of changes
Footer: task and track references

为任务创建一个聚焦的提交：

bash

git add -A
git commit -m "feat(user): implement email validation

- Add validate_email method to User class
- Handle empty and malformed emails
- Add comprehensive test coverage

Task: 2.1
Track: user-auth_20250115"

提交消息格式：

类型：feat、fix、refactor、test、docs、chore
范围：受影响的模块或组件
摘要：祈使语气、现在时态
正文：变更的要点列表
页脚：任务和track的引用

Step 9: Attach Git Notes

步骤9：添加Git备注

Add rich task summary as git note:

bash

git notes add -m "Task 2.1: Implement user validation

Summary:
- Added email validation using regex pattern
- Handles edge cases: empty, no @, no domain
- Coverage: 94% on validation module

Files changed:
- src/models/user.py (modified)
- tests/test_user.py (modified)

Decisions:
- Used simple regex over email-validator library
- Reason: No external dependency for basic validation"

为任务添加详细的Git备注：

bash

git notes add -m "Task 2.1: Implement user validation

Summary:
- Added email validation using regex pattern
- Handles edge cases: empty, no @, no domain
- Coverage: 94% on validation module

Files changed:
- src/models/user.py (modified)
- tests/test_user.py (modified)

Decisions:
- Used simple regex over email-validator library
- Reason: No external dependency for basic validation"

Step 10: Update Plan with SHA

步骤10：在计划中记录SHA值

Update plan.md to mark task complete with commit SHA:

markdown

- [x] **Task 2.1**: Implement user validation `abc1234`

更新plan.md，标记任务为完成并附上提交SHA：

markdown

- [x] **Task 2.1**: Implement user validation `abc1234`

Step 11: Commit Plan Update

步骤11：提交计划更新

Commit the plan status update:

bash

git add conductor/tracks/*/plan.md
git commit -m "docs: update plan - task 2.1 complete

Track: user-auth_20250115"

提交计划状态的更新：

bash

git add conductor/tracks/*/plan.md
git commit -m "docs: update plan - task 2.1 complete

Track: user-auth_20250115"

Phase Completion Protocol

阶段完成协议

When all tasks in a phase are complete, execute the verification protocol:

当一个阶段的所有任务完成后，执行以下验证协议：

Identify Changed Files

识别变更文件

List all files modified since the last checkpoint:

bash

git diff --name-only <last-checkpoint-sha>..HEAD

列出自上次检查点以来修改的所有文件：

bash

git diff --name-only <last-checkpoint-sha>..HEAD

Ensure Test Coverage

确保测试覆盖率

For each modified file:

Identify corresponding test file
Verify tests exist for new/changed code
Run coverage for modified modules
Add tests if coverage < 80%

对于每个修改的文件：

找到对应的测试文件
验证新代码/变更代码有对应的测试
运行修改模块的覆盖率检查
如果覆盖率低于80%，添加测试

Run Full Test Suite

运行完整测试套件

Execute complete test suite:

bash

pytest -v --tb=short

All tests must pass before proceeding.

执行完整的测试套件：

bash

pytest -v --tb=short

在继续之前，所有测试必须通过。

Generate Manual Verification Steps

生成手动验证步骤

Create checklist of manual verifications:

markdown

undefined

创建手动验证清单：

markdown

undefined

Phase 1 Verification Checklist

阶段1验证清单

User can register with valid email
Invalid email shows appropriate error
Database stores user correctly
API returns expected response codes

undefined

用户可以使用有效邮箱注册
无效邮箱会显示相应错误
数据库正确存储用户信息
API返回预期的响应码

undefined

WAIT for User Approval

等待用户批准

Present verification checklist to user:

Phase 1 complete. Please verify:
1. [ ] Test suite passes (automated)
2. [ ] Coverage meets target (automated)
3. [ ] Manual verification items (requires human)

Respond with 'approved' to continue, or note issues.

Do NOT proceed without explicit approval.

向用户展示验证清单：

阶段1已完成，请验证：
1. [ ] 测试套件通过（自动化）
2. [ ] 覆盖率达到目标（自动化）
3. [ ] 手动验证项（需人工操作）

回复'approved'以继续，或注明问题。

未获得明确批准前，请勿继续。

Create Checkpoint Commit

创建检查点提交

After approval, create checkpoint commit:

bash

git add -A
git commit -m "checkpoint: phase 1 complete - user-auth_20250115

Verified:
- All tests passing
- Coverage: 87%
- Manual verification approved

Phase 1 tasks:
- [x] Task 1.1: Setup database schema
- [x] Task 1.2: Implement user model
- [x] Task 1.3: Add validation logic"

获得批准后，创建检查点提交：

bash

git add -A
git commit -m "checkpoint: phase 1 complete - user-auth_20250115

Verified:
- All tests passing
- Coverage: 87%
- Manual verification approved

Phase 1 tasks:
- [x] Task 1.1: Setup database schema
- [x] Task 1.2: Implement user model
- [x] Task 1.3: Add validation logic"

Record Checkpoint SHA

记录检查点SHA

Update plan.md checkpoints table:

markdown

undefined

更新plan.md中的检查点表格：

markdown

undefined

Checkpoints

检查点

Phase	Checkpoint SHA	Date	Status
Phase 1	def5678	2025-01-15	verified
Phase 2			pending

undefined

阶段	检查点SHA	日期	状态
阶段1	def5678	2025-01-15	已验证
阶段2			待处理

undefined

Quality Assurance Gates

质量保障关卡

Before marking any task complete, verify these gates:

在标记任何任务完成之前，请验证以下关卡：

Passing Tests

测试通过

All existing tests pass
New tests pass
No test regressions

所有现有测试通过
新测试通过
无测试回归

Coverage >= 80%

覆盖率≥80%

New code has 80%+ coverage
Overall project coverage maintained
Critical paths fully covered

新代码覆盖率≥80%
保持项目整体覆盖率
关键路径完全覆盖

Style Compliance

代码风格合规

Code follows style guides
Linting passes
Formatting correct

代码遵循风格指南
代码检查通过
格式正确

Documentation

文档完善

Public APIs documented
Complex logic explained
README updated if needed

公开API已文档化
复杂逻辑有说明
如有需要，更新README

Type Safety

类型安全

Type hints present (if applicable)
Type checker passes
No type: ignore without reason

（如适用）存在类型提示
类型检查通过
无无理由的type: ignore

No Linting Errors

无代码检查错误

Zero linter errors
Warnings addressed or justified
Static analysis clean

零代码检查错误
警告已处理或有合理理由
静态分析无问题

Mobile Compatibility

移动端兼容性

If applicable:

Responsive design verified
Touch interactions work
Performance acceptable

如适用：

响应式设计已验证
触摸交互正常
性能可接受

Security Audit

安全审计

No secrets in code
Input validation present
Authentication/authorization correct
Dependencies vulnerability-free

代码中无敏感信息
存在输入验证
认证/授权逻辑正确
依赖无漏洞

Git Integration

Git集成

Commit Message Format

提交消息格式

<type>(<scope>): <subject>

<body>

<footer>

Types:

```
feat
```
: New feature
```
fix
```
: Bug fix
```
refactor
```
: Code change without feature/fix
```
test
```
: Adding tests
```
docs
```
: Documentation
```
chore
```
: Maintenance

<type>(<scope>): <subject>

<body>

<footer>

类型：

```
feat
```
: 新功能
```
fix
```
: 修复Bug
```
refactor
```
: 无功能/修复的代码变更
```
test
```
: 添加测试
```
docs
```
: 文档更新
```
chore
```
: 维护任务

Git Notes for Rich Summaries

用于详细摘要的Git备注

Attach detailed notes to commits:

bash

git notes add -m "<detailed summary>"

View notes:

bash

git log --show-notes

Benefits:

Preserves context without cluttering commit message
Enables semantic queries across commits
Supports track-based operations

为提交添加详细备注：

bash

git notes add -m "<detailed summary>"

查看备注：

bash

git log --show-notes

优势：

保留上下文，不使提交消息杂乱
支持跨提交的语义查询
支持基于track的操作

SHA Recording in plan.md

在plan.md中记录SHA

Always record the commit SHA when completing tasks:

markdown

- [x] **Task 1.1**: Setup schema `abc1234`
- [x] **Task 1.2**: Add model `def5678`

This enables:

Traceability from plan to code
Semantic revert operations
Progress auditing

完成任务时，务必记录提交SHA：

markdown

- [x] **Task 1.1**: Setup schema `abc1234`
- [x] **Task 1.2**: Add model `def5678`

这可以实现：

从计划到代码的可追溯性
语义化回滚操作
进度审计

Verification Checkpoints

验证检查点

Why Checkpoints Matter

检查点的重要性

Checkpoints create restore points for semantic reversion:

Revert to end of any phase
Maintain logical code state
Enable safe experimentation

检查点为语义化回滚创建恢复点：

可回滚到任意阶段结束时的状态
保持代码的逻辑状态
支持安全的实验

When to Create Checkpoints

何时创建检查点

Create checkpoint after:

All phase tasks complete
All phase verifications pass
User approval received

在以下情况后创建检查点：

阶段所有任务完成
阶段所有验证通过
获得用户批准

Checkpoint Commit Content

检查点提交内容

Include in checkpoint commit:

All uncommitted changes
Updated plan.md
Updated metadata.json
Any documentation updates

检查点提交应包含：

所有未提交的变更
更新后的plan.md
更新后的metadata.json
任何文档更新

How to Use Checkpoints

如何使用检查点

For reverting:

bash

undefined

回滚：

bash

undefined

Revert to end of Phase 1

回滚到阶段1结束时的状态

git revert --no-commit <phase-2-commits>... git commit -m "revert: rollback to phase 1 checkpoint"


For review:

```bash

git revert --no-commit <phase-2-commits>... git commit -m "revert: rollback to phase 1 checkpoint"


审查：

```bash

See what changed in Phase 2

查看阶段2的变更

git diff <phase-1-sha>..<phase-2-sha>

undefined

git diff <phase-1-sha>..<phase-2-sha>

undefined

Handling Deviations

处理偏差

During implementation, deviations from the plan may occur. Handle them systematically:

在实现过程中，可能会出现与计划不符的情况，请按以下方式系统处理：

Types of Deviations

偏差类型

Scope Addition Discovered requirement not in original spec.

Document in spec.md as new requirement
Add tasks to plan.md
Note addition in task comments

Scope Reduction Feature deemed unnecessary during implementation.

Mark tasks as
```
[-]
```
(skipped) with reason
Update spec.md scope section
Document decision rationale

Technical Deviation Different implementation approach than planned.

Note deviation in task completion comment
Update tech-stack.md if dependencies changed
Document why original approach was unsuitable

Requirement Change Understanding of requirement changes during work.

Update spec.md with corrected requirement
Adjust plan.md tasks if needed
Re-verify acceptance criteria

范围新增 发现原始规格中未提及的需求。

在spec.md中记录为新需求
在plan.md中添加任务
在任务注释中记录新增内容

范围缩减 在实现过程中认为某项功能不必要。

将任务标记为
```
[-]
```
（已跳过）并注明原因
更新spec.md的范围部分
记录决策理由

技术偏差 采用与计划不同的实现方式。

在任务完成注释中记录偏差
如果依赖变更，更新tech-stack.md
记录原方案不合适的原因

需求变更 在工作过程中对需求的理解发生变化。

在spec.md中更新修正后的需求
如有需要，调整plan.md中的任务
重新验证验收标准

Deviation Documentation Format

偏差文档格式

When completing a task with deviation:

markdown

- [x] **Task 2.1**: Implement validation `abc1234`
  - DEVIATION: Used library instead of custom code
  - Reason: Better edge case handling
  - Impact: Added email-validator to dependencies

完成存在偏差的任务时：

markdown

- [x] **Task 2.1**: Implement validation `abc1234`
  - DEVIATION: 使用库而非自定义代码
  - 原因：更好的边缘情况处理
  - 影响：新增email-validator依赖

Error Recovery

错误恢复

Failed Tests After GREEN

绿阶段后测试失败

If tests fail after reaching GREEN:

Do NOT proceed to REFACTOR
Identify which test started failing
Check if refactoring broke something
Revert to last known GREEN state
Re-approach the implementation

如果进入绿阶段后测试失败：

不要进入重构阶段
找出开始失败的测试
检查是否是重构导致的问题
回滚到最后一个已知的绿状态
重新进行实现

Checkpoint Rejection

检查点被拒绝

If user rejects a checkpoint:

Note rejection reason in plan.md
Create tasks to address issues
Complete remediation tasks
Request checkpoint approval again

如果用户拒绝检查点：

在plan.md中记录拒绝原因
创建解决问题的任务
完成修复任务
再次请求检查点批准

Blocked by Dependency

被依赖项阻塞

If task cannot proceed:

Mark task as
```
[!]
```
with blocker description
Check if other tasks can proceed
Document expected resolution timeline
Consider creating dependency resolution track

如果任务无法继续：

将任务标记为
```
[!]
```
并注明阻塞原因
检查是否有其他任务可以继续
记录预期的解决时间
考虑创建依赖项解决track

TDD Variations by Task Type

按任务类型划分的TDD变体

Data Model Tasks

数据模型任务

RED: Write test for model creation and validation
GREEN: Implement model class with fields
REFACTOR: Add computed properties, improve types

红阶段：编写模型创建和验证的测试
绿阶段：实现带字段的模型类
重构阶段：添加计算属性，改进类型

API Endpoint Tasks

API端点任务

RED: Write test for request/response contract
GREEN: Implement endpoint handler
REFACTOR: Extract validation, improve error handling

红阶段：编写请求/响应契约的测试
绿阶段：实现端点处理器
重构阶段：提取验证逻辑，改进错误处理

Integration Tasks

集成任务

RED: Write test for component interaction
GREEN: Wire components together
REFACTOR: Improve error propagation, add logging

红阶段：编写组件交互的测试
绿阶段：将组件连接起来
重构阶段：改进错误传播，添加日志

Refactoring Tasks

重构任务

RED: Add characterization tests for current behavior
GREEN: Apply refactoring (tests should stay green)
REFACTOR: Clean up any introduced complexity

红阶段：为当前行为添加特征测试
绿阶段：进行重构（测试应保持通过）
重构阶段：清理引入的复杂度

Working with Existing Tests

处理现有测试

When modifying code with existing tests:

修改已有测试的代码时：

Extend, Don't Replace

扩展，而非替换

Keep existing tests passing
Add new tests for new behavior
Update tests only when requirements change

保持现有测试通过
为新行为添加新测试
仅在需求变更时更新测试

Test Migration

测试迁移

When refactoring changes test structure:

Run existing tests (should pass)
Add new tests for refactored code
Migrate test cases to new structure
Remove old tests only after new tests pass

当重构改变测试结构时：

运行现有测试（应通过）
为重构后的代码添加新测试
将测试用例迁移到新结构
仅在新测试通过后删除旧测试

Regression Prevention

防止回归

After any change:

Run full test suite
Check for unexpected failures
Investigate any new failures
Fix regressions before proceeding

任何变更后：

运行完整测试套件
检查是否有意外失败
调查任何新出现的失败
在继续之前修复回归问题

Checkpoint Verification Details

检查点验证细节

Automated Verification

自动化验证

Run before requesting approval:

bash

undefined

在请求批准前运行：

bash

undefined

Test suite

测试套件

pytest -v --tb=short

Coverage

覆盖率

pytest --cov=src --cov-report=term-missing

Linting

代码检查

ruff check src/ tests/

Type checking (if applicable)

类型检查（如适用）

mypy src/

undefined

mypy src/

undefined

Manual Verification Guidance

手动验证指南

For manual items, provide specific instructions:

markdown

undefined

对于手动项，提供具体说明：

markdown

undefined

Manual Verification Steps

手动验证步骤

User Registration

用户注册

Navigate to /register
Enter valid email: test@example.com
Enter password meeting requirements
Click Submit
Verify success message appears
Verify user appears in database

导航到/register
输入有效邮箱：test@example.com
输入符合要求的密码
点击提交
验证成功消息出现
验证用户出现在数据库中

Error Handling

错误处理

Enter invalid email: "notanemail"
Verify error message shows
Verify form retains other entered data

undefined

输入无效邮箱："notanemail"
验证错误消息显示
验证表单保留其他已输入的数据

undefined

Performance Considerations

性能考虑

Test Suite Performance

测试套件性能

Keep test suite fast:

Use fixtures to avoid redundant setup
Mock slow external calls
Run subset during development, full suite at checkpoints

保持测试套件快速：

使用fixture避免冗余设置
模拟缓慢的外部调用
开发期间运行子集，检查点时运行完整套件

Commit Performance

提交性能

Keep commits atomic:

One logical change per commit
Complete thought, not work-in-progress
Tests should pass after every commit

保持提交原子化：

每个提交对应一个逻辑变更
完成的想法，而非进行中的工作
每个提交后测试应通过

Best Practices

最佳实践

Never skip RED: Always write failing tests first
Small commits: One logical change per commit
Immediate updates: Update plan.md right after task completion
Wait for approval: Never skip checkpoint verification
Rich git notes: Include context that helps future understanding
Coverage discipline: Don't accept coverage below target
Quality gates: Check all gates before marking complete
Sequential phases: Complete phases in order
Document deviations: Note any changes from original plan
Clean state: Each commit should leave code in working state
Fast feedback: Run relevant tests frequently during development
Clear blockers: Address blockers promptly, don't work around them

绝不跳过红阶段：始终先编写失败的测试
小提交：每个提交对应一个逻辑变更
即时更新：任务完成后立即更新plan.md
等待批准：绝不跳过检查点验证
丰富的Git备注：添加有助于未来理解的上下文
覆盖率纪律：不接受低于目标的覆盖率
质量关卡：标记完成前检查所有关卡
按阶段顺序：按顺序完成阶段
记录偏差：记录与原始计划的任何变更
干净状态：每个提交应使代码处于可工作状态
快速反馈：开发期间频繁运行相关测试
明确阻塞：及时处理阻塞，不要绕过