禅道任务模板
版本：v1.0 | 2026-03-09
适用：ClawZone 真人 + AI Agent 混合工作流
一、设计原则
禅道是任务分发层，不是方案承载层。
禅道（派单）→ docs.clawzone.ai（方案事实）→ GitLab（交付执行）
- 禅道负责：谁做、做什么、状态、优先级、截止时间
- docs 负责：怎么做、AC、数据库设计、API 定义
- GitLab 负责：代码、MR、CI/CD、部署
核心约束：任务卡必须引用 docs 链接，AI 读文档执行，真人看禅道协作。
二、任务卡必填字段
每个禅道任务必须包含以下字段，缺一不可：
| 字段 | 说明 | 示例 |
|---|---|---|
| 标题 | 动词开头，一句话说清楚 | 实现用户注册接口（POST /v1/auth/register） |
| 背景 | 为什么做，1-3 句话 | 当前系统无用户注册功能，需支持邮箱注册 |
| 目标 | 预期效果，可量化 | 用户可通过邮箱注册并获取 JWT Token |
| 范围 | 本次做什么 | 后端接口 + 数据库 Migration |
| 不做什么 | 明确排除项 | 不含前端页面、不含第三方 OAuth |
| 输入资料 | docs / GitLab 链接（必须） | https://docs.clawzone.ai/projects/xxx/plan |
| 验收标准 | AC 编号列表，指向 docs 中的完整 AC | AC-001, AC-002, AC-003 |
| 输出物 | 交付什么 | MR 链接 + 测试环境可访问 |
| 责任人 | 执行者（真人或 Agent 名） | kzzs / @张三 |
| 复核人 | 谁验收 | e50u / Tom |
| 优先级 | P0-P3 | P1 |
| 截止时间 | 明确日期 | 2026-03-15 |
三、状态流转
待规划 → 待复核 → 待执行 → 开发中 → 测试中 → 待 e50u 验收 → 待最终验收 → 待上线 → 已完成
↘ 已退回（附退回原因）
| 状态 | 触发条件 | 下一步动作 |
|---|---|---|
| 待规划 | 新建任务 | 补齐必填字段 + docs 链接 |
| 待复核 | 字段齐全，方案已写入 docs | DoD Gate 三方复核 |
| 待执行 | 复核通过 | kzzs 分发给执行者 |
| 开发中 | 执行者开始工作 | 按 plan.md 编码，提 MR |
| 测试中 | MR 合并，CI 通过，部署到测试环境 | 自动通知 QA |
| 待 e50u 验收 | 测试环境就绪 | e50u 逐条验证 AC |
| 待最终验收 | e50u 验收通过 | Tom 最终确认 |
| 待上线 | Tom 确认通过 | 部署生产（独立流程） |
| 已完成 | 上线完毕 | 关闭任务，记录 changelog |
| 已退回 | 任何阶段发现问题 | 附退回原因，退回到对应阶段 |
四、AI Agent 读取规范
AI Agent 不直接读禅道页面，而是通过以下方式获取任务信息：
4.1 kzzs 分发格式
kzzs 从禅道读取任务后，转化为结构化消息分发给执行 Agent：
## 任务：[禅道任务标题]
**禅道编号：** ZT-XXX
**优先级：** P1
**截止时间：** 2026-03-15
### 背景
[从禅道任务卡复制]
### 目标
[从禅道任务卡复制]
### 输入资料
- plan.md: https://docs.clawzone.ai/projects/xxx/plan
- backend-spec: https://docs.clawzone.ai/spec/backend-spec
### 验收标准
执行前请先 web_fetch plan.md，定位以下 AC：
- AC-001: [标题]
- AC-002: [标题]
- AC-003: [标题]
### 约束
- [不做什么]
- [技术约束]
### 输出要求
- MR 链接
- 测试通过截图/日志
- 完成后回报 kzzs
4.2 禅道 API 集成（未来）
禅道提供 REST API，后续可实现自动同步：
GET /api/v1/tasks→ 获取待执行任务列表PUT /api/v1/tasks/:id→ 更新任务状态- kzzs 定时拉取 → 自动分发 → 自动回写状态
当前阶段：手动操作禅道 + kzzs 结构化分发。
五、任务卡填写示例
示例：实现用户注册接口
| 字段 | 内容 |
|---|---|
| 标题 | 实现用户注册接口（POST /v1/auth/register） |
| 背景 | 当前系统无用户体系，需要先实现基础注册功能，作为后续所有业务的前置依赖 |
| 目标 | 用户可通过邮箱 + 密码注册，注册成功返回 JWT Token |
| 范围 | 后端接口开发 + users 表 Migration + 单元测试 |
| 不做什么 | 不含登录接口（下个任务）、不含前端页面、不含手机号注册 |
| 输入资料 | https://docs.clawzone.ai/projects/user-system/plan |
| 验收标准 | AC-001（正常注册）、AC-002（参数校验）、AC-003（邮箱唯一性） |
| 输出物 | MR 链接 + test.clawzone.ai 可访问 |
| 责任人 | dev-agent-01 |
| 复核人 | e50u |
| 优先级 | P0 |
| 截止时间 | 2026-03-15 |
六、与现有流程的衔接
| SDLC Phase | 禅道状态 | docs 动作 | GitLab 动作 |
|---|---|---|---|
| Phase 1 Shaping | 待规划 → 待复核 | 编写 plan.md | — |
| Phase 2 DoD Gate | 待复核 → 待执行 | plan.md 定稿 | — |
| Phase 3 开发 | 开发中 | — | feat 分支 + MR |
| Phase 4 CI | 开发中 | — | CI 自动跑 |
| Phase 5 部署 | 测试中 | — | 自动 deploy |
| Phase 6 QA | 待 e50u 验收 | 验收报告 | — |
| Phase 7 交付 | 待最终验收 → 已完成 | 更新 status.md | tag release |