Speckit 文档

# 团队协作最佳实践

# 引言

SDD 的成功不仅依赖于高质量的规范，还需要有效的团队协作。本章将介绍如何在团队中实施 SDD，建立协作流程。

# 团队角色

# 1. 规范编写者（Spec Writer）

职责：

  • 编写和维护规范
  • 确保规范的完整性和准确性
  • 响应规范相关的反馈

技能要求：

  • 理解业务需求
  • 熟悉 API 设计
  • 良好的文档编写能力

# 2. 规范评审者（Spec Reviewer）

职责：

  • 评审规范的完整性和正确性
  • 提供改进建议
  • 批准规范

技能要求：

  • 技术深度
  • 架构理解
  • 业务理解

# 3. 实现开发者（Implementer）

职责：

  • 基于规范实现功能
  • 确保实现符合规范
  • 报告规范问题

技能要求：

  • 编程能力
  • 理解规范
  • 测试能力

# 4. 测试人员（Tester）

职责：

  • 基于规范编写测试
  • 验证实现符合规范
  • 报告不符合项

技能要求：

  • 测试能力
  • 理解规范
  • 自动化测试

# 协作流程

# 阶段 1：规范编写

需求分析 → 规范编写 → 自审 → 提交评审
1

参与者：

  • 产品经理：提供需求
  • 规范编写者：编写规范
  • 架构师：提供技术指导

输出：

  • 规范草案
  • 需求澄清

# 阶段 2：规范评审

规范评审 → 反馈收集 → 规范修改 → 再次评审 → 批准
1

参与者：

  • 规范编写者：修改规范
  • 规范评审者：评审规范
  • 实现开发者：提供实现视角反馈
  • 测试人员：提供测试视角反馈

输出：

  • 批准的规范
  • 评审记录

# 阶段 3：并行开发

规范批准 → 后端开发 + 前端开发 + Mock 服务
1

参与者：

  • 后端开发者：实现 API
  • 前端开发者：基于 Mock 开发
  • 测试人员：编写测试用例

输出：

  • 后端实现
  • 前端实现
  • Mock 服务
  • 测试用例

# 阶段 4：集成测试

实现完成 → 集成测试 → 问题修复 → 验收
1

参与者：

  • 所有开发者：修复问题
  • 测试人员：执行测试
  • 产品经理：验收

输出：

  • 通过测试的实现
  • 测试报告

# 沟通机制

# 1. 规范评审会议

目的：评审规范，收集反馈

频率：每个规范至少一次

参与者：

  • 规范编写者
  • 规范评审者
  • 相关开发者
  • 测试人员

议程：

  1. 规范介绍（10分钟）
  2. 逐项评审（30分钟）
  3. 问题讨论（20分钟）
  4. 行动项确认（10分钟）

# 2. 规范变更通知

目的：通知团队规范变更

触发条件：

  • 规范版本更新
  • 规范内容变更
  • 规范废弃

通知方式：

  • 邮件通知
  • 团队聊天工具
  • 规范管理系统

内容：

  • 变更摘要
  • 变更原因
  • 影响范围
  • 迁移指南

# 3. 规范问题反馈

目的：收集规范相关问题

反馈渠道：

  • 规范管理系统
  • 团队聊天工具
  • 定期回顾会议

处理流程：

问题反馈 → 问题分析 → 规范更新 → 通知团队
1

# 工具和平台

# 1. 规范管理

# GitHub

使用 GitHub 管理规范：

  • 规范仓库：单独的规范仓库
  • Pull Request：规范变更通过 PR
  • Issues：规范问题跟踪
  • Wiki：规范文档

# 规范管理系统

使用专业工具：

  • Stoplight - API 设计和规范管理
  • Redocly - 规范管理和文档
  • SwaggerHub - API 设计和协作

# 2. 协作工具

# 文档协作

  • Confluence - 团队文档协作
  • Notion - 知识管理
  • Google Docs - 实时协作

# 沟通工具

  • Slack - 团队沟通
  • Microsoft Teams - 企业协作
  • 钉钉 - 团队沟通

# 3. 开发工具

# Mock 服务

  • Mockoon - 本地 Mock 服务
  • WireMock - 企业级 Mock 服务
  • JSON Server - 快速 Mock API

# 测试工具

  • Postman - API 测试
  • Insomnia - API 客户端
  • Dredd - 规范验证测试

# 最佳实践

# 1. 建立规范模板

创建标准模板，保持一致性：

# 规范模板
Specification: [Name]
Version: [Version]
Author: [Author]
Date: [Date]
Status: Draft

# 标准结构
Description: ...
Request: ...
Response: ...
Edge Cases: ...
Business Rules: ...
Security: ...
Performance: ...
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# 2. 规范版本管理

使用语义化版本：

v1.0.0 - 初始版本
v1.1.0 - 新增功能（向后兼容）
v2.0.0 - 重大变更（不兼容）
1
2
3

版本变更规则：

  • 主版本号：不兼容的变更
  • 次版本号：向后兼容的新功能
  • 修订号：向后兼容的问题修复

# 3. 规范评审检查清单

建立评审检查清单：

  • [ ] 规范结构完整
  • [ ] 功能描述清晰
  • [ ] 请求定义完整
  • [ ] 响应定义完整
  • [ ] 边界条件考虑
  • [ ] 业务规则明确
  • [ ] 安全要求定义
  • [ ] 性能要求明确
  • [ ] 示例提供
  • [ ] 格式一致

# 4. 规范变更管理

建立变更流程：

  1. 变更申请 - 提交变更请求
  2. 影响分析 - 分析变更影响
  3. 团队通知 - 通知相关团队
  4. 变更实施 - 实施变更
  5. 验证确认 - 验证变更效果

# 5. 规范文档化

保持规范文档化：

  • 规范索引 - 所有规范的索引
  • 规范状态 - 规范的状态跟踪
  • 变更历史 - 规范的变更历史
  • 使用指南 - 规范使用指南

# 常见问题

# 1. 规范变更频繁

问题：规范频繁变更，影响开发

解决方案：

  • 加强规范评审，减少后期变更
  • 建立变更流程，控制变更频率
  • 使用版本管理，保持向后兼容

# 2. 规范与实际不符

问题：实现与规范不一致

解决方案：

  • 建立规范验证机制
  • 定期检查实现符合性
  • 及时更新规范

# 3. 团队参与度低

问题：团队成员不积极参与规范评审

解决方案：

  • 明确规范评审的重要性
  • 建立评审激励机制
  • 简化评审流程

# 4. 规范质量不一致

问题：不同人编写的规范质量差异大

解决方案：

  • 建立规范模板
  • 提供规范编写培训
  • 建立规范评审机制

# 成功案例

# 案例 1：前后端协作

背景：前后端分离项目，需要协作开发

实践：

  1. 后端先编写 API 规范
  2. 规范评审通过后，前端基于 Mock 开发
  3. 后端实现 API
  4. 集成测试

效果：

  • 开发时间缩短 30%
  • 接口问题减少 50%
  • 团队协作效率提升

# 案例 2：微服务项目

背景：多个微服务，需要定义服务间接口

实践：

  1. 统一规范格式（OpenAPI）
  2. 规范集中管理
  3. 规范版本化
  4. 基于规范的集成测试

效果：

  • 服务间接口清晰
  • 集成问题减少
  • 维护成本降低

# 总结

团队协作是 SDD 成功的关键：

  1. 明确角色 - 定义清晰的团队角色
  2. 建立流程 - 建立规范的协作流程
  3. 使用工具 - 选择合适的工具和平台
  4. 持续改进 - 根据实际情况持续优化

在下一节中，我们将学习实现开发的最佳实践。

最后更新: 11/11/2025, 10:55:08 AM

← 实现开发最佳实践 →