gaoqiongxie 来源: 自建（基于国内开发团队禅道+Jira+Wiki/Confluence/语雀的真实工作流）
发布时间: 2026-05-28
理念: "同一个需求，不要在三个工具里写三遍。写一次，同步三处。"
🔧 Dev Toolkit Integrator — 禅道·Jira·Wiki 三工具集成操作指南
开发迭代中，禅道管任务、Jira 管需求、Wiki 管文档——这个 Skill 教你让它们说同一种语言。
🎯 核心设计：一次录入，三处复用
信息源头 同步目标
─────────────────────────────────
Jira Epic/Story → 禅道需求/任务
禅道 Bug → Jira Issue + Wiki 故障分析
Wiki 技术方案 → 禅道任务描述 + Jira 描述
代码 Commit → 禅道任务关联 + Jira 状态更新
统一信息单元（UIU: Unified Information Unit）：
每个需求/任务/缺陷，都包含以下字段：
uiu:
id: "PROJ-001" # Jira Issue Key / 禅道编号
title: "订单退款功能" # 统一标题
type: "需求/Bug/任务" # 类型
owner: "张三" # 负责人
priority: "P0/P1/P2" # 优先级
status: "待开发/开发中/测试中/已上线" # 统一状态映射
description: "..." # 统一描述（Markdown）
acceptance: "..." # 验收标准（Gherkin）
related_docs: # 关联文档
- "Wiki: 技术方案/订单退款"
- "禅道: 任务 #1234"
- "Jira: PROJ-001"
🏗️ 三工具分工与映射
| 维度 | 禅道 (ZenTao) | Jira | Wiki (Confluence/语雀/飞书) |
|---|---|---|---|
| 核心定位 | 国产项目管理+测试管理 | 敏捷需求+迭代跟踪 | 知识沉淀+文档协作 |
| 需求管理 | 产品-需求模块 | Epic → Story → Sub-task | 需求文档 PRD |
| 任务拆分 | 任务模块（开发/测试） | Sprint Board 任务卡 | 技术方案/拆分工时 |
| 缺陷跟踪 | Bug 模块（最常用） | Bug Issue Type | 故障复盘/根因分析 |
| 测试管理 | 用例+测试单+报表 | Zephyr/Xray 插件 | 测试报告/验收文档 |
| 迭代管理 | 产品-迭代 | Sprint + Board | 迭代计划/ retro |
| 报表统计 | 内置报表（燃尽图等） | Dashboard + JQL | 周报/月报/总结 |
状态映射表（关键！）
| 统一状态 | 禅道 | Jira | 说明 |
|---|---|---|---|
| 待规划 | 草稿 | Backlog | 需求池，未排期 |
| 待开发 | 激活/进行中 | To Do | 已分配，未开始 |
| 开发中 | 进行中 | In Progress | 正在编码 |
| 待测试 | 已解决 | Ready for Test | 开发完成，提测 |
| 测试中 | 测试中 | In Testing | QA 测试中 |
| 已验收 | 已关闭 | Done | 测试通过 |
| 已上线 | 已关闭（加标签） | Closed | 生产验证通过 |
| 已驳回 | 已关闭（加原因） | Rejected | 需求变更/不做了 |
🔄 场景一：需求从 Jira 到禅道到 Wiki（正向流转）
场景：产品同学在 Jira 提了 Story，需要拆任务、写方案、同步禅道。
Step 1: Jira 侧 — 需求澄清
# Jira Story 模板
## 标题
[模块] 一句话描述需求
## 描述
作为 [角色]，我希望 [功能]，以便 [价值]
## 验收标准（Gherkin）
Given [前提]
When [操作]
Then [结果]
## 优先级
P0 - 阻塞上线 / P1 - 迭代必须 / P2 - 有则更好
## 关联
- Wiki 需求文档: [链接]
- 设计稿: [链接]
- Epic: [PROJ-xxx]
Step 2: Wiki 侧 — 写技术方案
# 技术方案：订单退款功能
## 需求来源
- Jira: PROJ-001
- 禅道需求: #1234
- 产品负责人: 李四
## 现状分析
[当前系统状态]
## 方案设计
[架构图/流程图]
## 接口变更
| 接口 | 变更类型 | 说明 |
|------|---------|------|
| POST /api/order/refund | 新增 | 创建退款 |
## 数据库变更
| 表 | 变更 | 脚本 |
|----|------|------|
| refund_record | 新增表 | V20260528__add_refund_record.sql |
## 任务拆分（同步禅道）
| 禅道任务 | 负责人 | 工时 | 依赖 |
|----------|--------|------|------|
| #5678 退款接口开发 | 张三 | 8h | 无 |
| #5679 退款单测 | 张三 | 4h | #5678 |
| #5680 集成测试 | 王五 | 4h | #5679 |
## 风险与回滚
[风险点 + 回滚方案]
## 审批
- [ ] 技术负责人
- [ ] 测试负责人
Step 3: 禅道侧 — 拆任务+建迭代
禅道操作清单：
□ 产品 → 需求 → 关联 Jira Story（标题复制，描述贴 Wiki 链接）
□ 项目 → 迭代 → 建 Sprint（名称与 Jira Sprint 一致）
□ 项目 → 任务 → 按 Wiki 方案拆分任务
├── 类型：开发/测试/设计/文档
├── 关联需求：#1234
├── 预估工时：按 Wiki 方案填
└── 负责人：指定到人
□ 项目 → 任务 → 设置任务依赖关系
信息同步检查表
## 需求同步检查表
| 检查项 | 禅道 | Jira | Wiki | 状态 |
|--------|------|------|------|------|
| 标题一致 | #1234 | PROJ-001 | 订单退款功能 | ☐ |
| 描述链接互相关联 | 含 Wiki 链接 | 含 Wiki 链接 | 含 Jira+禅道编号 | ☐ |
| 负责人一致 | 张三 | 张三 | 张三 | ☐ |
| 优先级一致 | P1 | High | P1 | ☐ |
| 状态映射正确 | 进行中 | In Progress | - | ☐ |
🔄 场景二：Bug 从发现到关闭（全链路）
场景：测试发现 Bug，提禅道，同步 Jira，修复后写 Wiki 根因分析。
Step 1: 禅道侧 — 提 Bug（信息最全）
# 禅道 Bug 模板
## 标题
[模块] 一句话描述 Bug
## 重现步骤
1. 登录系统，进入订单管理
2. 选择订单 #20240528001
3. 点击"退款"按钮
4. 输入金额 99999
5. 点击确认
## 实际结果
系统报错 500，无友好提示
## 期望结果
提示"退款金额不能超过订单实付金额"
## 环境
- 分支: feat/refund-v2
- 版本: v2.3.1-beta
- 浏览器: Chrome 120
- 数据库: MySQL 8.0
## 截图/日志
[附件]
## 关联
- 禅道任务: #5678
- Jira: PROJ-001
- 发现人: 测试-王五
- 负责人: 开发-张三
Step 2: Jira 侧 — 同步 Bug Issue
# Jira Bug Issue
## 标题
[Bug] 退款金额校验缺失导致 500 错误
## 描述
[复制禅道描述]
## 标签
bug, backend, refund, P1
## 关联
- Blocks: PROJ-001
- Related: 禅道 Bug #4567
Step 3: 修复后 — Wiki 写根因分析
# 故障复盘：退款金额越界导致 500
## 基本信息
| 项 | 值 |
|----|----|
| 禅道 Bug | #4567 |
| Jira | BUG-089 |
| 发现时间 | 2026-05-28 |
| 修复时间 | 2026-05-28 |
| 影响范围 | 退款功能 |
| 是否线上 | ☐ 是 ☑ 否（测试环境发现） |
## 根因分析
1. **直接原因**: Service 层缺少金额上限校验
2. **技术原因**: 入参校验只做了 @NotNull，没做 @Max
3. **流程原因**: Code Review 时未识别此边界条件
## 修复方案
- Commit: `fix: 添加退款金额上限校验`
- 文件: OrderService.java
- 方案: 校验 amount <= actualPayAmount
## 预防措施
- [ ] 补充同类接口的金额校验检查
- [ ] Code Review 检查清单增加"金额边界"
- [ ] 集成测试用例补充越界场景
## 经验教训
[教训]
Step 4: 禅道+Jira 状态同步
禅道: Bug #4567 → 已解决 → 已关闭（验证通过）
Jira: BUG-089 → In Progress → Resolved → Closed
🔄 场景三：迭代规划（三工具联动）
场景：新 Sprint 开始，需要在三个平台同步建迭代、排任务。
三工具同步操作
# Sprint 2026S13 迭代规划
## 基本信息（三平台一致）
- 名称: 2026S13（5.27-6.9）
- 目标: 完成退款功能 + 账户安全升级
- 人数: 5人（3开发 + 1测试 + 1产品）
- 工时: 10天 × 5人 × 6h = 300h
## Jira 侧
□ 创建 Sprint 2026S13
□ 从 Backlog 拉 Story 到 Sprint
□ 设置 Sprint 目标
□ 启动 Sprint
## 禅道侧
□ 产品 → 迭代 → 建迭代 2026S13
□ 关联需求到迭代
□ 项目 → 任务 → 按人分配
□ 设置任务起止时间
## Wiki 侧
□ 创建"2026S13 迭代计划"页面
□ 包含：目标/人员/Story列表/风险/里程碑
□ retro 模板预创建
🔄 场景四：版本发布（三工具收尾）
发布前检查清单
# 版本发布检查清单 v2.4.0
## 禅道侧
□ 所有 Bug 已关闭
□ 所有任务已关闭
□ 测试单通过率 100%
□ 迭代状态：已完成
## Jira 侧
□ Sprint 已关闭
□ 所有 Story Done
□ Release 已创建
□ 版本号：v2.4.0
## Wiki 侧
□ 发布说明已编写
□ 变更日志已更新
□ 操作手册已更新
□ 回滚方案已确认
## 代码侧
□ main 分支已打 tag v2.4.0
□ CHANGELOG.md 已更新
□ 数据库迁移脚本已确认
Wiki 发布说明模板
# v2.4.0 发布说明
## 发布概要
- 版本号: v2.4.0
- 发布时间: 2026-06-10
- 禅道迭代: 2026S13
- Jira Release: v2.4.0
## 新增功能
| 功能 | 禅道需求 | Jira | 负责人 |
|------|---------|------|--------|
| 订单退款 | #1234 | PROJ-001 | 张三 |
## 修复缺陷
| Bug | 禅道 | Jira | 严重级别 |
|-----|------|------|---------|
| 退款越界 500 | #4567 | BUG-089 | P1 |
## 技术变更
- 数据库: 新增 refund_record 表
- 接口: 新增 POST /api/order/refund
- 配置: 无变更
## 回滚方案
如有异常，回滚至 v2.3.2，执行回滚脚本 rollback_v2.4.0.sql
## 验证方式
1. 登录测试环境
2. 执行退款流程
3. 检查监控告警
📝 常用操作速查
禅道速查
| 操作 | 路径 | 快捷键/技巧 |
|---|---|---|
| 提 Bug | 测试 → Bug → 提Bug | 批量创建用"批量添加" |
| 建任务 | 项目 → 任务 → 建任务 | 用"批量添加"拆任务 |
| 更新状态 | 任务详情 → 开始/完成/关闭 | 看板视图拖拽 |
| 关联需求 | 任务 → 相关需求 → 关联 | 自动带需求描述 |
| 生成报表 | 项目 → 统计 → 燃尽图 | 导出 Excel |
Jira 速查
| 操作 | 路径 | JQL 示例 |
|---|---|---|
| 查我的任务 | 搜索 → 高级 | assignee = currentUser() AND status != Closed |
| Sprint 规划 | Backlog → 拖拽 | - |
| 状态流转 | 看板拖拽 / 详情页按钮 | - |
| 批量操作 | 搜索结果 → 批量操作 | 最多 100 条 |
| 生成报表 | 项目 → 报告 | 燃尽图、速度图、累积流 |
Wiki 速查
| 操作 | 路径 | 模板 |
|---|---|---|
| 写技术方案 | 空间 → 创建 → 页面 | 见本 Skill 技术方案模板 |
| 写迭代计划 | 空间 → 创建 → 页面 | 见迭代规划模板 |
| 故障复盘 | 空间 → 创建 → 页面 | 见 Bug 复盘模板 |
| 发布说明 | 空间 → 创建 → 页面 | 见发布说明模板 |
| 同步更新 | 编辑 → 更新关联链接 | 确保三工具链接互相关联 |
💡 自动化建议（进阶）
用 Git Commit 触发状态更新
# Commit message 规范
feat(PROJ-001): 添加退款金额校验
- 校验 amount <= actualPayAmount
- 关联禅道任务 #5678
- Closes BUG-089
配合 CI 脚本：
- 解析 Commit 中的 Jira Key → 自动更新 Jira 状态为 "In Progress"
- 解析 Commit 中的禅道任务号 → 自动更新禅道任务为 "进行中"
- 解析 "Closes" → 自动更新关联 Bug 为 "已解决"
用 PR 模板强制信息完整
# PR 模板
## 关联
- Jira: [ ]
- 禅道任务: [ ]
- 禅道 Bug: [ ]
- Wiki 技术方案: [ ]
## 变更
[描述]
## 测试
- [ ] 单元测试通过
- [ ] 集成测试通过
🚀 快速入口
"创建禅道任务" → 禅道任务模板 + 关联需求/Bug
"写Wiki文档" → 技术方案/迭代计划/复盘/发布说明模板
"Jira状态更新" → 状态映射 + 批量操作
"需求怎么流转" → Jira→Wiki→禅道正向流转
"Bug提单" → 禅道Bug模板 + Jira同步 + Wiki根因分析
"迭代规划" → 三工具同步建Sprint
"发布版本" → 发布检查清单 + Wiki发布说明
"同步三个平台" → 信息同步检查表
🆚 与现有 Skill 的关系
| Skill | 关系 | 协作场景 |
|---|---|---|
| backend-change-flow | 前置 | 开发变更前，用本 Skill 在禅道/Jira 创建任务，再用 backend-change-flow 开发 |
| solo-parallel-dev | 互补 | 并行开发多个 feature 时，用本 Skill 管理各 feature 在三工具中的任务 |
| create-pr | 后置 | 代码完成后，PR 中关联禅道/Jira/Wiki，形成完整链路 |
| quality-gate | 后置 | 提交前检查是否关联了三工具的对应 Issue |
| openspec-sdd | 前置 | 需求澄清后，用本 Skill 把 Gherkin 验收标准同步到 Jira + 禅道 + Wiki |
最佳实践链：
openspec-sdd（需求澄清）
→ dev-toolkit-integrator（同步到禅道/Jira/Wiki）
→ backend-change-flow（编码开发）
→ quality-gate（提交检查）
→ create-pr（生成 PR，关联三工具）
→ dev-toolkit-integrator（更新状态/写复盘/发版本）
"工具是手段，不是目的。三工具集成的终极目标，是让信息只写一次，让状态一眼可见，让复盘有据可查。"