---
name: implementing-from-task
description: 测试中, 用户明确指定执行 implementing-from-task 时候才执行, 其余情况一律不执行
---

# 从任务工单实现功能

## 触发条件

识别用户输入包含以下要素：
- **任务工单链接**：
  - 项目管理系统：`https://your-project-system.example.com/story/detail/{数字ID}`
  - Jira：`https://your-company.atlassian.net/browse/PROJ-xxxxx`
- **PRD 链接**：`https://your-docs.example.com/wiki/xxx` 或 `https://your-docs.example.com/doc/xxx`
- **动作词**（可选）：实现、修复、重构、优化、新增、开发、fix

示例输入：
```
实现 https://your-project-system.example.com/story/detail/123456 https://your-docs.example.com/wiki/DOC001
```
```
https://your-company.atlassian.net/browse/PROJ-12345 https://your-docs.example.com/doc/DOC002
```
```
修复 PROJ-12345 https://your-docs.example.com/wiki/DOC003
```

## ⚠️ 强制检查点

**必须严格按顺序执行，禁止跳过任何步骤！**

```
┌─────────────────────────────────────────────────────────┐
│  阶段零：PRD 分析与服务定位（必须先理解再执行）              │
│  ├── 0.1. 前后端职责划分                                 │
│  ├── 0.2. 服务定位（使用 service-discovery）              │
│  ├── 0.3. 影响范围分析                                   │
│  └── 0.4. 输出初步分析 → ⏸️ 确认理解正确                  │
├─────────────────────────────────────────────────────────┤
│  阶段一：准备（必须完成后才能进入阶段二）                    │
│  ├── 1. 解析任务 ID                                      │
│  ├── 2. 创建分支                                         │
│  └── 3. 获取 PRD 详细内容                                │
├─────────────────────────────────────────────────────────┤
│  阶段二：规划（必须输出文档并等待确认）🔴 强制确认点          │
│  ├── 4. 生成 spec.md   → 包含影响范围分析                │
│  ├── 5. 生成 plan.md   → 包含服务查找依据                │
│  ├── 6. 生成 tasks.md  → 标注前后端依赖                  │
│  └── ⏸️  输出完整摘要，等待用户明确回复"确认"             │
├─────────────────────────────────────────────────────────┤
│  阶段三：实现（用户确认后才能开始）                         │
│  ├── 7. 分析依赖、决定执行方式                            │
│  ├── 8. 实现代码                                         │
│  └── 9. 提交并创建 MR                                    │
└─────────────────────────────────────────────────────────┘
```

**违反检查点的后果**：
- 跳过阶段零 → 可能修改错误服务，导致大范围返工
- 跳过文档生成 → 需求理解偏差，返工成本高
- 不等待确认 → 可能实现错误的功能，浪费资源

## 工作流程

### 阶段零：PRD 分析与服务定位 🔴 必须先执行

**目标**：在创建分支和编写代码前，先理解需求并定位正确的服务。

#### 0.1 前后端职责划分

使用 [前后端分解指南](frontend-backend-decomposition-guide.md) 识别：

**纯前端任务**（后端无需关注）：
- UI 布局调整、样式优化
- 前端状态管理、路由配置
- 前端表单验证（非业务规则）

**纯后端任务**（本技能重点）：
- API 接口开发、业务逻辑实现
- 数据库 schema 变更、数据迁移
- 后端性能优化、缓存策略

**协同任务**（需前后端配合）：
- 新增字段（proto 定义 + 前端展示）
- 权限控制（后端鉴权 + 前端按钮控制）
- 数据验证（后端规则 + 前端提示）

**输出示例**：
```markdown
## PRD 分析结果

### 纯前端（后端无需关注）
- 评价列表页面新增筛选器 UI
- 动态详情页样式调整

### 纯后端（本次实现重点）
- 评价内容支持自定义表情存储和渲染
- 新增表情收藏接口

### 协同任务
- 评价 proto 新增 custom_emoji 字段（后端定义 + 前端使用）
```

#### 0.2 服务定位

参考项目文档定位涉及的服务（如果项目提供）：
- **项目架构文档**：项目根目录的 README.md，通常记录 Mono Repo 结构和服务划分
- **服务索引**：服务索引文档（如 service-index.md），用于映射功能域到具体服务
- **服务发现工具**：项目可能提供的服务发现工具或文档，帮助快速定位功能所属服务

**定位方法**：

1. **关键词匹配**：
   - PRD 提到业务关键词（如 "订单"、"商品"、"用户"）→ 查找项目中对应的服务
   - 示例：PRD 提到 "评论" → 查找 `comment-service` 或 `content-service`

2. **功能域匹配**：
   - 根据项目的服务划分规则，将需求映射到功能域
   - 示例：
     - 内容相关功能 → 内容服务
     - 用户相关功能 → 用户服务
     - 支付相关功能 → 支付服务

3. **Proto 文件验证**：
   ```bash
   # 搜索相关 proto 定义
   find proto/ -name "*.proto" -exec grep -l "YourFeature\|YourEntity" {} \;
   ```

**输出示例**：
```markdown
## 服务定位结果

### 涉及服务
1. **service-a** (`app/service-a/` 或 `services/service-a/`)
   - 原因：管理 XXX 功能
   - 现有代码：`internal/repo/{feature}/{handler}.go`
   - Proto: `proto/taptap/{service}/{feature}/v1/*.proto`

2. **service-b** (`app/service-b/`)
   - 原因：负责 YYY 功能的数据处理
   - 现有代码：`internal/service/{feature}.go`
   - Proto: `proto/taptap/{service}/{feature}/v1/*.proto`

### 查找依据
- 关键词 "XXX" → 服务索引文档指向 `service-a`
- 关键词 "YYY" → 服务索引文档指向 `service-b`
- Proto 文件验证：`proto/taptap/{service}/` 确认包含相关定义
```

#### 0.3 影响范围分析

评估变更影响：
- **Proto 变更**：是否影响其他服务（通过 proto 依赖检查）
- **数据库变更**：是否需要数据迁移
- **配置变更**：Apollo 配置、K8s 资源配置
- **依赖服务**：是否需要其他服务配合

#### 0.4 输出初步分析并等待确认 ⏸️

**必须输出以下内容给用户确认**：

```markdown
## 📋 PRD 初步分析

### 后端需关注的功能
- [ ] 功能 1：描述
- [ ] 功能 2：描述

### 涉及服务
- **服务 A**：原因说明
- **服务 B**：原因说明

### 影响范围
- Proto 变更：是/否，影响范围
- 数据库变更：是/否，涉及表
- 配置变更：是/否，涉及配置项

---
⏸️ **请确认以上分析是否正确？**
- 回复 "确认" 继续后续流程
- 回复调整意见，我将重新分析
```

### 阶段一：准备

#### 1. 解析任务 ID

从输入中提取任务 ID：
- **项目管理系统任务链接** → 解析出最后的数字 ID（如 123456）
- **Jira 任务链接** → 从 URL 路径中提取任务 ID（如 `https://your-company.atlassian.net/browse/PROJ-12345` → `PROJ-12345`）
- **任务 ID** → 直接使用（PROJ-xxx、TASK-xxx 等，根据项目约定）
- **动作词** → 映射分支前缀和 commit type（参阅 [action-mapping.md](action-mapping.md)）
  - 无动作词时默认为 `feat`

#### 2. 创建工作分支

分支命名：`{prefix}-{任务ID前缀}-{任务ID}-{short-summary}`

```bash
git checkout -b feat-PROJ-12345-user-profile
```

#### 3. 获取 PRD 详细内容

读取用户提供的 PRD 链接内容：
- 结合阶段零的分析结果
- 提取后端技术需求细节
- 识别 API 接口定义
- 提取数据模型变更要求
- 收集业务逻辑实现要求

### 阶段二：规划 🔴 强制确认点

#### 4. 生成 Spec 文档

创建 `specs/TAP-{任务ID}/` 目录，生成以下文档：

**spec.md**（参阅 [spec-template.md](spec-template.md)）：
- 功能规范
- **新增**：影响范围分析章节（来自阶段零）
  - 前后端职责划分结果
  - 涉及服务及选择依据
  - Proto/数据库/配置变更影响

**plan.md**（参阅 [plan-template.md](plan-template.md)）：
- 实现计划
- **新增**：服务查找依据说明
  - 如何从 service-index.md 定位服务
  - Proto 文件验证结果
  - 现有代码复用情况

**tasks.md**（参阅 [tasks-template.md](tasks-template.md)）：
- 任务清单
- **新增**：前后端依赖标注
  - 纯后端任务
  - 需前端配合的任务
  - 阻塞关系说明

#### 5. 输出完整摘要并等待确认 ⏸️

**必须输出以下完整内容给用户，禁止省略**：

```markdown
## 📋 Spec 文档已生成

### spec.md 核心内容

#### 功能概述
{从 PRD 提炼的核心功能描述}

#### 涉及服务及依据
- **服务 A** (`app/xxx/`)
  - 选择原因：{参考 service-index.md 的匹配逻辑}
  - 现有代码：{相关文件路径}
  - Proto 定义：{proto 文件路径}

#### 影响范围分析
- **Proto 变更**：{是/否，影响哪些服务}
- **数据库变更**：{是/否，涉及哪些表}
- **配置变更**：{是/否，Apollo/K8s 配置项}

#### 核心需求
- [ ] 需求 1：描述
- [ ] 需求 2：描述

### plan.md 核心内容

#### 实现步骤
1. {步骤 1 描述}
2. {步骤 2 描述}

#### 技术方案
- {关键技术选型和理由}

#### 风险点
- {潜在风险和应对措施}

### tasks.md 核心内容

#### 任务概览
- 总任务数：{X}
- 可并行：{是/否}
- 预计工时：{Y} 小时

#### 任务列表（前 3 项）
1. [ ] 任务 1 - {描述} | 类型: {纯后端/协同} | 依赖: {无/任务X}
2. [ ] 任务 2 - {描述} | 类型: {纯后端/协同} | 依赖: {无/任务X}
3. [ ] 任务 3 - {描述} | 类型: {纯后端/协同} | 依赖: {无/任务X}

---
⏸️ **请仔细review以上内容，确认以下问题**：

1. 服务定位是否正确？（参考项目 README.md 和 service-index.md）
2. 功能理解是否准确？（参考 PRD 原文）
3. 影响范围分析是否完整？（Proto/数据库/配置变更）
4. 实现方案是否合理？（技术选型、风险评估）

**请明确回复**：
- 回复 **"确认"** 或 **"继续"** 或 **"开始实现"** → 进入阶段三（实现代码）
- 回复 **调整意见**（如 "服务 X 应改为服务 Y"）→ 我将修改文档并重新输出摘要
- 回复 **"取消"** → 终止流程
```

**⚠️ 关键要求**：
- **禁止在用户明确回复"确认"类词汇前开始实现代码**
- **禁止简化摘要输出**，必须包含上述所有章节
- **禁止自行假设用户已确认**，必须等待实际回复

#### 6. 处理用户反馈

根据用户回复采取行动：

| 用户回复 | 操作 |
|---------|------|
| "确认" / "继续" / "开始实现" / "OK" | 进入阶段三 |
| 具体修改意见（如 "服务改为 X"） | 更新对应文档，重新输出摘要，再次等待确认 |
| "取消" / "停止" | 终止流程，清理分支 |
| 询问细节（如 "为什么选择服务 X"） | 详细解释后，继续等待确认 |

### 阶段三：实现

#### 7. 分析任务依赖

自动检测任务间依赖关系：
- 分析 import/调用关系
- 识别共享文件（proto、go.mod、model 等）

#### 8. 决定执行方式 🔴 强制规则

根据依赖分析**必须**按以下方式执行：

| 条件 | 执行方式 | 说明 |
|------|---------|------|
| 存在依赖 | 串行执行 | 按依赖顺序，单 agent |
| **完全独立 且 >= 2 个任务** | **必须并行** | 使用 git worktree，参阅 [merging-parallel-work](../merging-parallel-work/SKILL.md) |

**⚠️ 禁止**：独立任务 >= 2 时串行执行（浪费时间，违反效率原则）

#### 9. 实现代码

按任务清单逐个实现：
- 修改代码
- 运行测试
- 修复问题
- 更新 tasks.md 中的任务状态

#### 10. 自动提交

实现完成后：
- 生成符合规范的提交信息（参阅 git-flow Skill）
- 推送分支
- 使用 `git push -o merge_request.create` 自动创建 MR

**Commit Message 格式**：

```
feat(service-name): 实现 XXX 功能的并发处理 #PROJ-12345

## 变更内容
- 在 {config-file}.go 配置中新增并发数配置项
- 修改 {handler}/{feature}.go，使用 errgroup 实现并发处理
- 添加相关单元测试

## 技术方案
- 使用 Go 标准库 errgroup.Group 控制并发
- 并发数可通过配置动态调整，默认值 10
- 确保循环变量捕获，避免闭包问题

## 相关文档
- specs/PROJ-12345/spec.md
- specs/PROJ-12345/plan.md
```

**Description 内容要求**：
- `## 变更内容`：列出修改的文件和具体改动
- `## 技术方案`：简述实现方式和关键决策
- `## 相关文档`：链接到 specs 目录下的文档

## 输出

完成后输出：
- MR/PR 链接
- 任务工单链接
- 变更摘要
- specs/{任务ID}/ 文档链接