---
source: ../../../adoption/DAILY-WORKFLOW-GUIDE.md
source_version: 1.1.0
translation_version: 1.1.0
last_synced: 2026-02-10
status: current
---

# 日常开发工作流程指南

**版本**: 1.1.0
**最后更新**: 2026-02-10

> **语言**: [English](../../../adoption/DAILY-WORKFLOW-GUIDE.md) | [繁體中文](../../zh-TW/adoption/DAILY-WORKFLOW-GUIDE.md) | 简体中文

本指南说明在执行 `uds init` 后，如何在日常开发工作流程中使用 Universal Development Standards。

---

## 目录

- [Phase 0：专案现况评估](#phase-0专案现况评估)
- [核心原则：渐进式采用](#核心原则渐进式采用)
- [根据任务类型选择工作流程](#根据任务类型选择工作流程)
- [Greenfield 与 Brownfield 专案](#greenfield-与-brownfield-专案)
- [旧有代码采用策略](#旧有代码采用策略)
- [场景式工作流程](#场景式工作流程)
- [可用命令快速参考](#可用命令快速参考)
- [质量检查点](#质量检查点)
- [何时撰写完整规格](#何时撰写完整规格)
- [最佳实践总结](#最佳实践总结)
- [相关标准](#相关标准)
- [版本历史](#版本历史)
- [授权](#授权)

---

## Phase 0：专案现况评估

> **使用时机**：首次接触既有代码库，或在不熟悉的模块进行重大变更之前。

在 Brownfield 专案进行代码变更之前，先执行 `/discover` 评估现况：

```
1. /discover [area]     → 评估专案健康度、架构、风险
2. /reverse spec        → 反向工程现有代码为规格（如有需要）
3. /sdd                 → 撰写新功能规格
4. 实作                  → 使用 /tdd 或 /bdd 在测试保护下实作
```

### 评估维度

| 维度 | 检查项目 |
|------|----------|
| **架构** | 模块结构、依赖图、入口点 |
| **依赖性** | 过时套件、已知漏洞、授权风险 |
| **测试覆盖** | 现有测试、覆盖率缺口、测试质量 |
| **安全性** | `npm audit` 结果、硬编码密钥、暴露端点 |
| **技术债** | TODO 标记、代码重复、复杂度热点 |

### 输出

Discovery Report 提供：
- 整体健康度分数（1-10）
- 各维度分数与关键发现
- **结论**：GO / NO-GO / CONDITIONAL
- 优先级排序的建议（HIGH / MED / LOW）

> **下一步**：评估完成后，如需理解现有代码请使用 `/reverse`，然后用 `/sdd` 设计新功能。

---

## 核心原则：渐进式采用

### 常见误解 vs 实际做法

```
┌─────────────────────────────────────────────────────────────────┐
│                    ❌ 误解 vs ✅ 实际做法                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ❌ 误解：                                                       │
│  「必须先为所有旧代码写完规格和测试，才能开始任何新开发」        │
│                                                                 │
│  ✅ 实际做法：                                                   │
│  「只在『触碰』现有代码时，才渐进式地添加测试和文档」           │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### 童子军原则 (Boy Scout Rule)

> 「离开时比来时干净一点」

- 反向工程整个系统是不切实际且价值有限的
- 专注于**增量改善**，而非**一次到位**
- 每次触碰代码时，添加一点保护（测试、文档）

---

## 根据任务类型选择工作流程

### 决策树

```
┌─────────────────────────────────────────────────────────────────┐
│                    任务类型 → 工作流程选择                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  第一次接触这个代码库？                                          │
│  │                                                              │
│  ├─ 是 → 先执行 /discover（Phase 0 评估）                       │
│  │                                                              │
│  └─ 否（熟悉代码库）                                            │
│                                                                 │
│  这是全新功能吗？                                                │
│  │                                                              │
│  ├─ 是（Greenfield）                                            │
│  │   └─ 使用完整流程：ATDD → SDD → BDD → TDD                   │
│  │                                                              │
│  └─ 否（Brownfield/Legacy）                                     │
│      │                                                          │
│      ├─ 修改范围大吗？（架构级、跨模块）                         │
│      │   │                                                      │
│      │   ├─ 是 → Golden Master + SDD                           │
│      │   │       （需要规格和完整测试保护）                      │
│      │   │                                                      │
│      │   └─ 否 → 只改单一模块/函数                              │
│      │       │                                                  │
│      │       ├─ 有现有测试吗？                                  │
│      │       │   │                                              │
│      │       │   ├─ 有 → 直接 TDD 循环                          │
│      │       │   │                                              │
│      │       │   └─ 没有 → 先写特征测试                         │
│      │       │                                                  │
│      │       └─ 是 Bug 修复吗？                                 │
│      │           │                                              │
│      │           ├─ 是 → 写失败测试 → 修复                       │
│      │           │                                              │
│      │           └─ 否 → TDD 添加新行为                         │
│      │                                                          │
│      └─ 是纯重构（不改变行为）吗？                              │
│          │                                                      │
│          ├─ 是 → 确保测试覆盖 → 重构 → 测试通过                 │
│          │                                                      │
│          └─ 否 → 混合：保护现有 + TDD 新功能                    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

---

## Greenfield 与 Brownfield 专案

### 定义

| 专案类型 | 描述 | 范例 |
|----------|------|------|
| **Greenfield** | 新专案或功能，没有现有代码 | 新微服务、新模块 |
| **Brownfield** | 现有代码库，有旧有代码 | 维护、为现有系统添加功能 |

### 工作流程比较

| 面向 | Greenfield | Brownfield |
|------|------------|------------|
| **规格** | 撰写完整规格 (SDD) | 只有重大变更才需要 |
| **测试** | 从头开始 TDD | 先写特征测试 |
| **文档** | 边做边建立 | 增量添加 |
| **方法论** | 完整 ATDD → SDD → BDD → TDD | 根据范围简化 |

---

## 旧有代码采用策略

### 策略 1：修改现有代码（Bug 修复/小改动）

```
┌────────────────────────────────────────────────────────────────┐
│           旧有代码修改（Golden Master 策略）                   │
├────────────────────────────────────────────────────────────────┤
│                                                                │
│  1️⃣  理解现有行为（不写规格，写测试）                           │
│      ├─ 阅读代码，理解当前行为                               │
│      ├─ 撰写「特征测试」(Characterization Test)                │
│      │   捕捉现有行为（不管对错）                              │
│      └─ 这个测试是你的「安全网」                               │
│                                                                │
│  2️⃣  修改代码                                                │
│      ├─ 在测试保护下进行修改                                   │
│      ├─ 如果测试失败，你知道改坏了什么                         │
│      └─ Bug 修复：先让测试失败，再修复                         │
│                                                                │
│  3️⃣  提交（不需要完整 Spec）                                   │
│      └─ Commit message 描述变更即可                            │
│                                                                │
│  ⚠️  重点：不需要 SPEC 文档，不需要完整 BDD 场景                │
│                                                                │
└────────────────────────────────────────────────────────────────┘
```

**范例：修复验证 Bug**

```typescript
// 1. 写特征测试，捕捉现有行为
test('characterization: login validates email format', () => {
  // 观察现有代码怎么做，然后记录下来
  const result = validateEmail('invalid');
  expect(result).toBe(false); // 记录现有行为
});

// 2. 写一个会失败的测试描述 Bug
test('should reject email without domain', () => {
  const result = validateEmail('user@');
  expect(result).toBe(false); // 目前可能是 true（Bug）
});

// 3. 修复 Bug，让测试通过
// 4. 提交
```

### 策略 2：为现有功能添加新行为

```
┌────────────────────────────────────────────────────────────────┐
│              功能扩展（混合策略）                                │
├────────────────────────────────────────────────────────────────┤
│                                                                │
│  1️⃣  保护现有行为                                              │
│      └─ 为将要修改的区域写特征测试                             │
│                                                                │
│  2️⃣  定义新行为（简化版 TDD/BDD）                              │
│      ├─ 写新功能的测试（TDD）                                  │
│      ├─ 或写 Given-When-Then 场景（BDD）                       │
│      └─ 不需要完整的 Spec Workshop                             │
│                                                                │
│  3️⃣  实作新功能                                                │
│      └─ 在测试保护下实作                                       │
│                                                                │
│  4️⃣  重构（可选）                                              │
│      └─ 如果有时间，改善触碰到的旧代码                        │
│                                                                │
└────────────────────────────────────────────────────────────────┘
```

### 策略 3：重大重构/架构改动

```
┌────────────────────────────────────────────────────────────────┐
│              重大变更（需要 Spec）                               │
├────────────────────────────────────────────────────────────────┤
│                                                                │
│  ⚠️  只有这种情况才需要较完整的流程                             │
│                                                                │
│  0️⃣  评估现况（Discovery + 反向工程）                          │
│      ├─ /discover 评估专案健康度与风险                          │
│      ├─ /reverse spec 反向工程现有代码                          │
│      └─ 输出：Discovery Report + 现有规格                      │
│                                                                │
│  1️⃣  撰写变更规格（SDD）                                       │
│      ├─ 描述为什么要重构                                       │
│      ├─ 定义影响范围                                           │
│      └─ 验收条件：系统行为不变                                 │
│                                                                │
│  2️⃣  建立 Golden Master 测试                                   │
│      ├─ 记录系统当前的所有输出                                 │
│      ├─ 使用 Snapshot Testing / Approval Testing               │
│      └─ 这是你的「正确答案」                                    │
│                                                                │
│  3️⃣  进行重构                                                  │
│      ├─ 每一步都确保 Golden Master 测试通过                    │
│      └─ 如果测试失败 → 立即回退                                │
│                                                                │
│  4️⃣  逐步将 Golden Master 转换为正式测试                       │
│      └─ 随时间改善测试质量                                     │
│                                                                │
└────────────────────────────────────────────────────────────────┘
```

---

## 场景式工作流程

### 场景 A：新功能开发（完整流程）

适用于需要利害关系人验收的重要新功能：

```
1️⃣  ATDD 阶段：定义「完成」标准
    ├─ 举办 Specification Workshop
    ├─ PO、开发者、QA 共同定义验收条件
    └─ 明确定义「范围外」项目
    💡 命令：/atdd

2️⃣  SDD 阶段：讨论与撰写技术规格
    ├─ 讨论：捕捉灰色地带、锁定范围、建立 read_first 清单
    ├─ 根据 AC 撰写技术设计文档
    ├─ 技术审查并获得批准
    └─ 输出：SPEC-XXX 文档
    💡 命令：/sdd discuss → /sdd create

3️⃣  BDD 阶段：撰写行为规格
    ├─ Discovery：从 AC 识别场景
    ├─ Formulation：撰写 Gherkin Given-When-Then 场景
    └─ 输出：Feature 文件
    💡 命令：/bdd

4️⃣  TDD 阶段：实作
    ├─ 🔴 RED：撰写失败测试
    ├─ 🟢 GREEN：最小化实作
    ├─ 🔵 REFACTOR：清理代码
    └─ 重复直到所有 BDD 场景通过
    💡 命令：/tdd

5️⃣  验证与提交
    ├─ 展示给 PO，获得正式验收
    ├─ 提交代码
    └─ 归档规格文档
    💡 命令：/commit
```

### 场景 B：Bug 修复（简化 TDD 流程）

```
1. 撰写重现 Bug 的失败测试
2. 修复 Bug 使测试通过
3. 重构（如有需要）
4. 提交并关联 Issue

💡 命令：
- /tdd（进入 TDD 模式）
- /commit（自动生成规范的 commit message）
```

### 场景 C：小改动/快速修复

```
1. 如果触碰没有测试的现有代码：
   └─ 先写特征测试
2. 进行修改
3. 验证测试通过
4. 提交

💡 不需要特别的方法论
```

### 场景 D：代码审查/PR

```
1. 使用系统性代码审查清单
2. 使用适当的评论前缀：
   - ❗ BLOCKING：必须在合并前修复
   - ⚠️ IMPORTANT：应该修复
   - 💡 SUGGESTION：建议改进
   - ❓ QUESTION：需要澄清

💡 命令：/review
```

---

## 可用命令快速参考

| 命令 | 用途 | 使用时机 |
|------|------|----------|
| `/discover` | 评估专案健康度与风险 | 首次接触代码库、重大变更前 |
| `/reverse` | 反向工程代码为规格/BDD/TDD | 理解现有代码 |
| `/tdd` | 启动 TDD 工作流程 | 写代码时 |
| `/bdd` | 启动 BDD 工作流程 | 设计行为规格时 |
| `/sdd` | 启动 SDD 工作流程 | 需要技术规格时 |
| `/atdd` | 启动 ATDD 工作流程 | 需要正式验收的功能 |
| `/refactor` | 启动重构工作流程 | 改善代码结构 |
| `/methodology` | 查看/切换当前方法论 | 管理开发流程 |
| `/commit` | 生成规范的 commit message | 提交代码 |
| `/review` | 启动代码审查 | 审查 PR |
| `/requirement` | 撰写需求文档 | 定义 User Story |
| `/checkin` | 提交前质量验证 | 提交代码前 |
| `/changelog` | 生成变更日志条目 | 准备发布期间 |
| `/coverage` | 分析测试覆盖率 | 评估测试质量 |
| `/docs` | 管理文档 | 撰写/更新文档 |
| `/release` | 引导发布流程 | 准备发布 |

---

## 质量检查点

### 提交前（透过 Git Hooks 自动执行）

```
✅ 所有测试通过
✅ 无 linting 错误
✅ 无泄漏的敏感信息
```

### 建立 PR 前

```
✅ 符合 Check-in Standards
✅ Commit message 符合 Conventional Commits
✅ 测试覆盖率未下降
```

### 代码审查时

```
✅ 代码通过 10 类审查清单
✅ 如有 Spec，实作符合规格
✅ 无范围蔓延
```

---

## 何时撰写完整规格

### 值得撰写 Spec 的情况

| 场景 | 原因 |
|------|------|
| ✅ 跨团队新功能 | 多方利害关系人需要对齐 |
| ✅ 需要 PO/利害关系人签核的变更 | 需要正式验收 |
| ✅ 架构级重构 | 高风险，需要文档化 |
| ✅ 外部 API 设计 | 合约定义 |
| ✅ 法规/合规变更 | 需要稽核轨迹 |

### 不需要撰写 Spec 的情况

| 场景 | 原因 |
|------|------|
| ❌ 小 Bug 修复 | 低复杂度，测试足够 |
| ❌ 代码清理/重构 | 无行为变更 |
| ❌ 内部工具改进 | 低仪式需求 |
| ❌ 效能优化 | 除非影响行为 |
| ❌ 依赖升级 | 例行维护 |

---

## 最佳实践总结

### 旧专案采用优先顺序

| 优先级 | 项目 | 原因 |
|--------|------|------|
| 🔴 高 | Commit Message 规范 | 零成本，立即受益 |
| 🔴 高 | Check-in Standards | 防止问题进入代码库 |
| 🟡 中 | TDD（仅新代码） | 新代码有测试保护 |
| 🟡 中 | 特征测试（触碰的旧代码） | 增量添加安全网 |
| 🟢 低 | 完整 BDD/SDD | 只用于重大新功能 |
| 🟢 低 | 反向工程旧 Spec | 通常不值得 |

### 应该做与不应该做

```
┌─────────────────────────────────────────────────────────────────┐
│                    UDS 日常开发最佳实践                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ✅ 应该做：                                                     │
│  ├─ 根据任务类型选择方法论                                      │
│  ├─ 使用 /命令 启动工作流程                                     │
│  ├─ 在实作前定义「完成」标准                                    │
│  ├─ 每次提交都通过质量检查                                      │
│  └─ 让 AI 追踪你的当前阶段                                      │
│                                                                 │
│  ❌ 不应该做：                                                   │
│  ├─ 跳过测试直接实作                                            │
│  ├─ 在没有规格的情况下开发重大功能                              │
│  ├─ 忽略方法论系统的阶段提醒                                    │
│  ├─ 提交未通过测试的代码                                      │
│  └─ 在开发过程中任意扩展范围                                    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### 你不需要做的事

```
┌─────────────────────────────────────────────────────────────────┐
│                    UDS 旧专案采用策略                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ❌ 不需要：                                                     │
│  ├─ 为所有旧代码撰写 Spec                                     │
│  ├─ 为所有旧代码撰写测试                                      │
│  └─ 在开始工作前进行反向工程                                    │
│                                                                 │
│  ✅ 需要：                                                       │
│  ├─ 修改旧代码时，为触碰的部分添加测试                        │
│  ├─ 新功能使用 TDD/BDD                                          │
│  ├─ 只有重大变更才撰写 Spec                                     │
│  └─ 持续增量改善                                                │
│                                                                 │
│  📈 随时间推移：                                                 │
│  测试覆盖率会自然增长，因为你总是                               │
│  「触碰一点，保护一点」                                         │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

---

## 相关标准

- [采用指南](ADOPTION-GUIDE.md) - 如何安装 UDS
- [专案现况评估](../../../skills/project-discovery/SKILL.md) - Phase 0 专案评估
- [反向工程标准](../../../core/reverse-engineering-standards.md) - 反向工程工作流程
- [重构标准](../../../core/refactoring-standards.md) - 重构工作流程
- [测试驱动开发](../../../core/test-driven-development.md) - TDD 标准（包含 Golden Master Testing）
- [行为驱动开发](../../../core/behavior-driven-development.md) - BDD 工作流程
- [验收测试驱动开发](../../../core/acceptance-test-driven-development.md) - ATDD 工作流程
- [规格驱动开发](../../../core/spec-driven-development.md) - SDD 工作流程
- [提交规范](../../../core/checkin-standards.md) - 代码提交要求
- [代码审查清单](../../../core/code-review-checklist.md) - 审查流程

---

## 版本历史

| 版本 | 日期 | 变更 |
|------|------|------|
| 1.1.0 | 2026-02-10 | 新增 Phase 0 专案评估、/discover + /reverse + /refactor 命令 |
| 1.0.0 | 2026-01-19 | 初版日常工作流程指南 |

---

## 授权

本指南采用 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授权发布。

**来源**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)
