麦瓣健康 - 开发工作手册

版本: v1.5
最后更新: 2025-10-29
适用范围: 用户端APP + 技师端APP + 管理后台Web + 后端服务

📋 目录

🎯 开发工作手册的目的 ← 为什么需要这份手册？
🤖 AI大模型如何使用这份手册？ ← AI工作边界
🚀 快速开始 ← 新人必读

1. 项目文件结构指南
2. 文档管理指南
3. 开发流程指南
4. 代码质量指南
5. 测试指南
6. Git工作流指南
7. GitHub同步指南
8. 架构设计指南
9. 任务管理指南
10. 团队协作指南
11. 质量门禁
    • 11.1 提交前检查
    • 11.2 PR合并前检查
    • 11.3 Epic分解前检查（强制）
    • 11.4 发布前检查
12. 附录

🎯 开发工作手册的目的

为什么需要这份手册？

在AI辅助开发的时代，开发工作手册不仅是团队协作的基础，更是指导AI大模型高效工作的关键。本手册旨在解决以下核心问题：

1. 统一规范，提升效率 📏

问题：

• 不同开发人员编码风格不一致
• 文件命名、目录结构各行其是
• 代码质量参差不齐，难以维护

手册解决：

• ✅ 统一文件命名规则（kebab-case）
• ✅ 统一代码结构（DDD + Clean Architecture）
• ✅ 统一提交流程（Issue #xxx: type: description）
• ✅ 统一质量标准（Linter零错误、测试≥80%）

价值：

• 减少代码审查争议
• 降低新人学习成本
• 提高代码可维护性
• 加快开发速度

2. 需求先行，边界清晰 🎯

问题：

• 需求不明确就开始编码，返工频繁
• AI大模型没有明确指引，生成代码不符合预期
• 任务边界模糊，功能蔓延失控

手册解决：

• ✅ PRD先行：所有功能必须先有产品需求文档
• ✅ Epic分解：技术方案明确架构和实现路径
• ✅ Task拆解：每个任务都有清晰的验收标准和范围边界
• ✅ 8步开发流程：从代码审阅到验证，步步清晰

AI大模型工作边界：

明确输入 → AI理解需求 → 精准输出

PRD (What)          →  Epic (How)        →  Task (Detail)
产品需求              技术方案              具体实现

↓                    ↓                     ↓

为AI提供：             为AI提供：            为AI提供：
- 用户故事           - 架构决策             - 验收标准
- 功能范围           - 技术选型             - 文件影响
- 验收标准           - 依赖关系             - 实现步骤

↓                    ↓                     ↓

AI输出：              AI输出：              AI输出：
- 技术实现方案       - 任务分解             - 可运行代码
- 架构设计图         - 工时估算             - 完整测试

价值：

• AI生成代码符合项目标准
• 减少需求理解偏差
• 避免功能蔓延（Scope Creep）
• 提高首次开发成功率

3. 团队协作，一致高效 🤝

问题：

• 任务分配混乱，不知道谁在做什么
• 进度不透明，项目延期难以预警
• 协作成本高，频繁的会议和沟通

手册解决：

• ✅ GitHub Issue管理：所有任务可视化，状态实时更新
• ✅ 依赖关系明确：depends_on、parallel、conflicts_with清晰定义
• ✅ 进度透明同步：每日同步进度到GitHub评论
• ✅ 标准化流程：从PRD到上线，5步标准流程

协作场景覆盖：

场景1：初始开发
PRD → Epic → Tasks → Sync → Development
↓
所有任务清晰，依赖关系明确

场景2：需求变更
Epic Edit → Decompose → Sync → Development
↓
智能识别变更，保护已完成工作

场景3：并行开发
查看任务frontmatter: parallel: true
↓
多人同时开发不冲突

场景4：代码审查
查看GitHub Issue评论 + PR
↓
完整上下文，高效审查

价值：

• 减少会议时间（进度透明）
• 避免重复工作（任务清晰）
• 降低协作成本（流程标准）
• 提高交付质量（规范统一）

4. 质量保证，持续改进 🔍

强制质量门禁：

• ✅ Linter零警告零错误（自动检查）
• ✅ 测试覆盖率≥80%（强制要求）
• ✅ Code Review必须通过（至少1人）
• ✅ 文件头部注释（新文件必须）

持续改进机制：

• 📊 代码质量可追踪
• 📈 测试覆盖率可视化
• 📝 问题反馈快速响应
• 🔄 规范持续迭代优化

🤖 AI大模型如何使用这份手册？

AI作为开发助手的工作模式

本手册专门设计为AI友好，让Claude、GPT等大模型能够：

1. 理解需求（PRD阶段）

AI读取：.claude/prds/{feature_name}.md
理解：用户故事、功能需求、验收标准
输出：技术实现方案（Epic）

2. 规划实现（Epic阶段）

AI读取：PRD + 项目架构
理解：技术栈、设计模式、依赖关系
输出：5-10个具体任务分解

3. 执行开发（Task阶段）

AI读取：Task文件 + 现有代码
执行：8步标准开发流程
  1. 读取任务详情
  2. 代码审阅（先读后写）
  3. 质量检查
  4. 决策判断
  5. 设置跟踪
  6. 编码实现
  7. 验证结果
  8. 同步GitHub
输出：高质量代码 + 完整测试

4. 保证质量（验证阶段）

AI检查：
  - Linter状态（零错误）
  - 测试覆盖率（≥80%）
  - 文件头部注释（完整）
  - 冗余代码（已清理）
输出：符合规范的可交付代码

AI工作边界的明确定义

最佳实践：人机协作

人类擅长：              AI擅长：
- 产品决策            - 代码生成
- 架构选择            - 测试编写
- 优先级判断          - 规范检查
- 业务逻辑设计        - 重复性工作
- 用户体验优化        - 文档生成

↓                     ↓
      协作最优解
      
人类：定义需求和边界
AI：  执行标准化开发
人类：审查和确认
AI：  优化和完善

🚀 快速开始

新人入门5步走

# 第1步：了解项目结构
# 查看 .claude/prds/ 和 .claude/epics/ 目录

# 第2步：熟悉核心命令（按顺序）
/pm:prd-new {feature_name}        # 创建PRD
/pm:prd-parse {feature_name}      # 解析为Epic
/pm:epic-decompose {epic_name}    # 分解为Tasks
/pm:epic-decompose-validation {epic_name}  # ⭐ 验证所有任务质量（强制要求）
/pm:epic-sync {epic_name}         # 同步到GitHub
/pm:issue-start {issue_number}    # 开始任务开发

# 第3步：了解开发流程
# 阅读 3.3 Issue开发详细流程（8步标准流程）

# 第4步：熟悉编码规范
# 重点：Linter零错误、新文件头部注释、无冗余代码

# 第5步：实践
# 从一个小任务开始，完整走一遍流程

核心原则速记

• ✅ 先读后写：修改前先读取现有代码
• ✅ Linter零错误：提交前必须通过Linter检查
• ✅ 测试覆盖≥80%：每个功能都要有测试
• ✅ 文件头部注释：新文件必须添加功能说明
• ✅ 增量提交：频繁提交，每次提交独立可测试
• ✅ 中文输出：代码审阅、进度报告都用中文
• ⭐ 任务验证：Epic分解后必须验证所有任务质量（≥90分）

需求变更时怎么办？

如果Epic已经创建并同步，需要新增或修改需求：

# 1. 编辑Epic添加新需求
/pm:epic-edit {epic_name}

# 2. 重新分解（智能识别KEEP/UPDATE/CREATE）
/pm:epic-decompose {epic_name}

# 3. 同步新任务或开始工作
/pm:epic-sync {epic_name}        # 有新任务时
/pm:issue-start {issue_number}   # 直接开始已更新任务

详细流程见 3.4 需求变更和新增模块流程

1. 项目文件结构指南

1.1 标准目录结构

maiban/
├── .claude/                          # CCPM项目管理目录
│   ├── prds/                         # 产品需求文档
│   │   └── {feature_name}.md         # PRD文件
│   ├── epics/                        # Epic和任务管理
│   │   └── {epic_name}/              # Epic目录
│   │       ├── epic.md               # Epic主文档
│   │       ├── {issue_number}-{title-slug}.md  # 任务文件
│   │       ├── github-mapping.md     # GitHub映射关系
│   │       └── issues/               # Issue工作目录
│   │           └── {issue_number}/   # Issue工作空间
│   │               ├── analysis.md   # 技术分析文档
│   │               ├── progress.md   # 进度跟踪
│   │               └── tests/        # 测试文件
│   ├── commands/                     # 自定义命令
│   │   └── pm/                       # 项目管理命令
│   └── rules/                        # 项目规则
├── docs/                             # 项目文档
│   ├── 项目管理/                     # 管理文档
│   ├── 功能清单/                     # 功能清单
│   └── 架构设计/                     # 架构文档
├── backend/                          # 后端代码
├── frontend/                         # 前端代码
│   ├── user-app/                     # 用户端APP
│   ├── technician-app/               # 技师端APP
│   └── admin-web/                    # 管理后台
└── tests/                            # 测试代码

1.2 文件命名指南

PRD文件

• 格式: {feature_name}.md
• 示例: user-authentication.md, order-management.md
• 规则:
  • 使用小写字母
  • 单词间用连字符分隔
  • 描述清晰的功能名称

Epic文件

• 主文档: epic.md（固定名称）
• 位置: .claude/epics/{epic_name}/epic.md

任务文件

• 格式: {issue_number}-{title-slug}.md
• 示例: 235-verify-core-architecture.md
• 规则:
  • 以GitHub Issue编号开头
  • 标题转为小写slug格式
  • 最大长度100字符

测试文件

• 格式: {feature_name}_test.{ext}
• 示例: user_authentication_test.dart, api_test.js
• 位置: .claude/epics/{epic_name}/issues/{issue_number}/tests/

2. 文档管理指南

2.1 Frontmatter指南

所有管理文档必须包含YAML frontmatter，位于文档顶部。

PRD Frontmatter

---
name: {feature_name}
description: {简短描述}
status: draft | ready | approved | archived
created: {ISO 8601 datetime}
updated: {ISO 8601 datetime}
owner: {负责人}
priority: P0 | P1 | P2
---

Epic Frontmatter

---
name: {epic_name}
status: backlog | in-progress | completed | cancelled
created: {ISO 8601 datetime}
updated: {ISO 8601 datetime}
progress: {0-100}%
prd: .claude/prds/{feature_name}.md
github: {GitHub Issue URL}
last_sync: {ISO 8601 datetime}
---

Task Frontmatter

---
name: {Task Title}
title: {Task Title}  # 同name，用于准确性
status: open | in-progress | completed | cancelled | blocked
created: {ISO 8601 datetime}
updated: {ISO 8601 datetime}
github: {GitHub Issue URL}
depends_on: [{issue_number1}, {issue_number2}]
parallel: true | false
conflicts_with: [{issue_number}]
---

时间戳指南

• 格式: ISO 8601 UTC格式
• 获取命令: date -u +"%Y-%m-%dT%H:%M:%SZ"
• 示例: 2025-10-28T10:30:00Z
• 规则:
  • 所有时间必须使用UTC时区
  • 必须包含秒级精度
  • 使用Z后缀表示UTC

2.2 文档内容结构

PRD必须包含的章节

# PRD: {Feature Name}

## 1. 功能概述
- 功能描述
- 用户价值
- 业务目标

## 2. 用户故事
- As a [用户角色]
- I want [功能需求]
- So that [业务价值]

## 3. 功能需求
- 详细功能点列表
- 优先级标注（P0/P1/P2）

## 4. 非功能需求
- 性能要求
- 安全要求
- 可用性要求

## 5. 验收标准
- 可测试的验收条件
- 成功指标

## 6. 约束条件
- 技术约束
- 业务约束
- 时间约束

## 7. 依赖关系
- 上游依赖
- 下游影响

Epic必须包含的章节

# Epic: {Epic Name}

## Overview
- 技术实现概述

## Architecture Decisions
- 关键技术决策
- 技术选型
- 设计模式

## System Architecture

可视化系统架构（使用mermaid流程图）：

```mermaid
graph TB
    subgraph "用户层"
        User[用户]
        Admin[管理员]
    end
    
    subgraph "应用层"
        WebApp[Web应用]
        MobileApp[移动应用]
    end
    
    subgraph "服务层"
        API[API网关]
        Service[业务服务]
    end
    
    subgraph "数据层"
        DB[(数据库)]
        Cache[(缓存)]
    end
    
    subgraph "外部系统"
        External[第三方服务]
    end
    
    User -->|使用| MobileApp
    Admin -->|管理| WebApp
    WebApp -->|REST API| API
    MobileApp -->|REST API| API
    API -->|路由| Service
    Service -->|查询/存储| DB
    Service -->|缓存| Cache
    Service -->|调用| External
    
    style API fill:#7ed321,color:#fff
    style Service fill:#7ed321,color:#fff
    style DB fill:#50e3c2
    style Cache fill:#50e3c2

架构说明：

• 根据实际需求调整架构层次和组件
• 标注关键的技术栈和通信协议
• 说明各层职责和交互方式

Technical Approach

Frontend Components

Backend Services

Infrastructure

Implementation Strategy

• 开发阶段
• 风险缓解
• 测试策略

Task Breakdown Preview

Phase 1: Foundation & Setup

• [ ] 001 - Task description

Phase 2: Core Implementation

• [ ] 002 - Task description

Dependencies

• 外部依赖
• 内部依赖

Success Criteria (Technical)

• 性能基准
• 质量门禁
• 验收标准

Estimated Effort

• 总体时间估算
• 资源需求
• 关键路径

#### Task必须包含的章节
```markdown
# Task: {Task Title}

## Description
{一句话描述}

**功能交付 (WHAT)**:
- Deliverable 1
- Deliverable 2

**范围边界**:
- **IN SCOPE**: {包含的内容}
- **OUT OF SCOPE**: {不包含的内容}

**用户价值 (WHY)**:
{为什么重要}

## Acceptance Criteria
- [ ] 可测量的标准1
- [ ] 可测量的标准2

## Technical Details
**实现方案**:
1. Step 1
2. Step 2

**文件影响**:
- `file1.dart` - 变更描述

**技术考虑**:
- 关键考虑点

## Architecture Diagram

```mermaid
graph LR
    subgraph "功能模块"
        A[组件A<br/>职责说明] --> B[组件B<br/>职责说明]
        B --> C[组件C<br/>职责说明]
    end
    
    D[外部依赖] --> A
    C --> E[(数据存储)]
    
    style A fill:#4a90e2,color:#fff
    style B fill:#4a90e2,color:#fff
    style C fill:#4a90e2,color:#fff
    style D fill:#f5a623
    style E fill:#50e3c2

架构说明：

• 根据任务复杂度选择合适的架构层级
• 随着实现过程更新架构图
• 记录关键的架构决策和技术选型

Dependencies

• [ ] 依赖1
• [ ] 依赖2

Effort Estimate

• Size: XS/S/M/L/XL
• Hours: {估算范围}

Definition of Done

• [ ] 代码实现并提交
• [ ] 单元测试通过（覆盖率≥80%）
• [ ] 集成测试通过
• [ ] 文档已更新
• [ ] Code Review通过

---

## 3. 开发流程指南

### 3.1 从PRD到实现的完整流程

PRD创建 → PRD解析(Epic) → Epic分解(Tasks) → 任务验证 ⭐ → Epic同步(GitHub) ↓ ↓ ↓ ↓ ↓ draft epic.md tasks.md validation Issues创建 ↓ ↓ ↓ ↓ ↓ approved 架构设计 任务文件 质量检查 子Issue关联 ↓ ↓ ↓ ↓ ↓ 分解任务 依赖关系 所有任务≥90分 Epic Issue ↓ ↓ ↓ ↓ 开始任务 → Issue Start → 编码实现 ↓ ↓ ↓ 进度同步 ← Issue Sync ← 提交代码 ↓ ↓ ↓ 任务完成 Issue Close 合并PR

**⭐ 强制验证环节**：
- 必须在 Epic 分解后执行 `/pm:epic-decompose-validation`
- 验证通过标准：所有任务≥90分，0个关键问题
- 验证失败：立即修复，不得继续同步

### 3.2 命令使用流程

#### 阶段1: 创建PRD（产品需求文档）
```bash
# 1. 创建PRD
/pm:prd-new {feature_name}

# 编辑PRD（可选）
/pm:prd-edit {feature_name}

# 查看PRD状态（可选）
/pm:prd-status {feature_name}

说明：

• 第一步是创建产品需求文档
• 明确功能需求、用户故事、验收标准
• PRD必须经过审批后才能进入下一步

阶段2: 解析PRD为Epic（技术实现方案）

# 2. 解析PRD为Epic
/pm:prd-parse {feature_name}

# 编辑Epic（可选）
/pm:epic-edit {epic_name}

# 查看Epic（可选）
/pm:epic-show {epic_name}

说明：

• 技术负责人将PRD转换为技术实现方案
• 包含架构设计、技术选型、任务预览
• Epic中会定义5-10个任务的概要

阶段3: 分解Epic为Tasks（具体任务）

# 3. 分解Epic为Tasks
/pm:epic-decompose {epic_name}

# 3.1. ⭐ 验证所有任务质量（强制要求）
# 重要：必须验证所有任务是否完整、自包含、可执行
/pm:epic-decompose-validation {epic_name}

# 查看Epic状态（可选）
/pm:epic-status {epic_name}

说明：

• 将Epic中的任务预览转换为独立的任务文件
• 必须执行验证：确保所有任务都完整且可执行
• 验证通过标准：所有任务得分≥90分，无关键问题
• 任务文件命名：001.md, 002.md, 003.md（同步前）

⭐ 强制验证规则：

• 验证失败（<60分）的任务：必须修复后才能继续
• 验证警告（60-89分）的任务：建议修复后再同步
• 只有所有任务通过验证（≥90分）才能进行同步

阶段4: 同步到GitHub（创建Issues）

# 4. 同步Epic和Tasks到GitHub
/pm:epic-sync {epic_name}

说明：

• 首次同步：创建Epic Issue和所有Task Sub-Issues
• 重要：任务文件会自动重命名
  • 001.md → 235-task-title-slug.md
  • 002.md → 236-another-task-slug.md
• 更新frontmatter中的github字段
• 创建github-mapping.md记录映射关系

防重复检查：

• 如果Epic已同步，会提示避免重复创建
• 可以选择查看现有Epic或仅更新任务

阶段5: 开始任务开发

# 5. 开始任务（使用GitHub Issue编号）
/pm:issue-start {issue_number}

# 同步进度到GitHub
/pm:issue-sync {issue_number}

# 查看任务状态
/pm:issue-status {issue_number}

# 关闭任务
/pm:issue-close {issue_number}

说明：

• 使用GitHub Issue编号（如：235）而不是任务编号（如：001）
• 执行8步标准开发流程
• 定期同步进度到GitHub Issue评论

3.3 Issue开发详细流程

执行 /pm:issue-start {issue_number} 时，必须按以下步骤执行：

Step 1: 读取分析和任务详情

• 读取任务文件：.claude/epics/{epic_name}/{issue_number}-*.md
• 理解验收标准
• 审查用户需求
• 识别受影响的模块和文件

Step 2: 代码审阅 - 验证功能需求

必须先读取相关代码文件，不能假设！

• 定位分析中提到的文件
• 实际读取代码了解当前实现
• 检查功能是否正确实现
• 审查业务逻辑和数据流
• 检查错误处理和边界情况
• 审查相关测试文件

代码审阅检查清单：

• 当前代码是否实现了所需功能？
• 是否存在逻辑错误或bug？
• 错误处理是否充分？
• 边界情况是否覆盖？
• 实现是否匹配设计？
• 是否存在代码异味或反模式？
• 编码标准检查：
  • 是否符合项目编码标准？
  • 新文件是否有头部功能说明注释？
  • 是否存在冗余代码（未使用的导入、变量、死代码）？

输出审阅结果：

🔍 代码审阅结果 - Issue #{issue_number}:
- 功能存在: {是/否/部分实现}
- 代码质量: {良好/需改进/有缺陷}
- 发现的主要问题:
  * {问题1}
  * {问题2}
- 当前实现情况: {描述}
- 所需操作: {新实现/增强/修复/重构}

Step 3: 验证代码质量

• 运行Linter检查
• 检查测试覆盖率
• 审查命名规范
• 识别需要遵循的编码模式
• 强制检查：
  • Linter零警告零错误
  • 新文件头部功能说明注释
  • 无冗余代码

输出质量检查：

✅ Code Quality Check for Issue #{issue_number}:
- Linter status: {Clean/X errors}
- Test coverage: {X%}
- Applicable rules: {规则列表}
- Architecture: {架构模式}
- 编码标准符合度: {完全符合/需改进}

Step 4: 决定实现方案

决策标准：

• 功能已存在且正常 → 更新任务状态为"no-change-needed"
• 需要小修复 → 执行针对性修复
• 需要新功能 → 执行完整实现
• 需要大重构 → 标记为需审查

输出决策：

💡 Implementation Decision for Issue #{issue_number}:
- Decision: {Proceed/No-change/Review-needed}
- Reason: {简要说明}
- Scope: {变更范围}
- Estimated files: {文件数量}

Step 5: 设置进度跟踪

• 创建目录：.claude/epics/{epic_name}/issues/{issue_number}/
• 创建进度文件：progress.md
• 更新GitHub Issue分配和标签

Step 6: 执行编码工作（如果步骤4决定需要）

实现原则：

1. 先读后写：创建新文件前先读取现有文件
2. 复用代码：检查现有函数和常量
3. 遵循架构：维护DDD层分离（domain → data → presentation）
4. 测试驱动：与实现同时编写测试
5. 增量提交：频繁提交，清晰消息：Issue #{issue_number}: {具体变更}
6. 更新进度：在progress.md中记录每个主要步骤

编码标准要求（强制执行）：

• 符合编码标准：所有代码必须通过Linter检查，零警告零错误
• 新文件头部注释：每个新建文件顶部必须添加功能说明注释

  /// 用户认证服务 - 处理用户登录、注册和token管理
  

  /** 订单管理API - 处理订单创建、查询和状态更新 */
  

  # 数据库迁移脚本 - 创建用户表和索引
  
• 排除冗余代码：提交前检查并移除
  • 未使用的导入语句
  • 未使用的变量、方法、类
  • 注释掉的死代码
  • 重复的代码片段

编码工作流程：

1. Domain层（如适用）：

   • 定义/更新模型和实体
   • 创建/更新Repository接口
   • 实现业务逻辑

2. Data层：

   • 创建DTO和数据模型
   • 实现数据源（API、本地存储）
   • 实现Repository具体类
   • 添加DTO ↔ Domain映射器

3. Presentation层：

   • 创建/更新状态管理（Riverpod/Bloc）
   • 实现UI组件和页面
   • 添加导航路由
   • 处理用户交互和状态更新

4. 编写全面测试：

   • 创建测试目录：.claude/epics/{epic_name}/issues/{issue_number}/tests/
   • 单元测试（模型和业务逻辑）
   • Widget测试（UI组件）
   • 集成测试（功能流程）
   • 确保覆盖率≥80%

提交规范：

# 每次重要变更后提交
git add .
git commit -m "Issue #{issue_number}: {描述具体变更}"

# 更新进度文件
echo "- [$(date -u +"%Y-%m-%dT%H:%M:%SZ")] {完成的工作}" >> progress.md

Step 7: 验证实现结果

运行测试：

flutter test              # Dart/Flutter
npm test                  # Node.js
pytest                    # Python
go test ./...             # Go

检查Linter：

flutter analyze           # Dart/Flutter
npm run lint              # Node.js
pylint .                  # Python
golangci-lint run         # Go

编码标准最终验证（必须项）：

• 运行格式化工具：

  flutter format .         # Dart/Flutter
  npm run format           # JavaScript/TS
  black .                  # Python
  go fmt ./...             # Go
  
• Linter零错误：确认无任何警告或错误
• 文件头部注释：检查所有新文件
• 冗余代码清理：确认无未使用导入、死代码
• 代码复用：确认无重复代码

输出验证结果：

## Verification Results
- Tests: {Passed/Failed - X/Y tests}
- Linter: {Clean/X errors}
- Functionality: {Working/Issues found}

## 编码标准验证
- 代码格式化: {已完成/需修复}
- Linter状态: {零错误零警告/X个问题}
- 文件头部注释: {已添加/缺失}
- 冗余代码: {已清理/仍存在}
- 代码复用: {良好/需改进}

Step 8: 同步GitHub Issue

全部检查通过时：

gh issue comment {issue_number} --body "✅ Implementation complete

**Changes made:**
- {关键变更列表}

**Tests:**
- {测试结果}

**Verification:**
- All acceptance criteria met
- All tests passing
- Linter clean (零警告零错误)

**编码标准符合度：**
- ✅ 代码已格式化
- ✅ 通过Linter检查（零警告零错误）
- ✅ 新文件已添加头部功能说明注释
- ✅ 无冗余代码
- ✅ 代码已复用现有函数

Ready for review."

# 标记为准备审查
gh issue edit {issue_number} --add-label "ready-for-review" --remove-label "in-progress"

3.4 需求变更和新增模块流程

当Epic已经存在并已同步到GitHub，需要新增需求或修改现有需求时，使用以下流程：

场景：需求变更或新增模块

典型场景：

• 产品新增了一个功能模块
• 现有功能需要增强或修改
• 发现遗漏的功能点
• 优先级调整，需要补充P0功能

完整工作流程（3步）

Step 1: 编辑Epic内容

# 1. 编辑Epic，添加或修改需求
/pm:epic-edit {epic_name}

编辑内容：

• 在 ## Technical Approach 章节添加新的功能点
• 在 ## Task Breakdown Preview 章节添加新任务
• 更新架构设计（如需要）
• 调整依赖关系

示例：

## Task Breakdown Preview

### Phase 1: Foundation & Setup
- [x] 001 - Database schema design  (已完成)
- [x] 002 - Core data models        (已完成)

### Phase 2: Core Implementation
- [ ] 003 - API endpoint implementation  (现有任务)
- [ ] 004 - User authentication         (🆕 新增需求)
- [ ] 005 - Permission management       (🆕 新增需求)

### Phase 3: Frontend & UI
- [ ] 006 - UI components (需要更新)

重要说明：

• 使用 [x] 标记已完成的任务
• 使用 [ ] 标记新增或未完成的任务
• 可以添加🆕标识帮助识别新增内容

Step 2: 重新分解Epic

# 2. 重新分解Epic（智能识别变更）
/pm:epic-decompose {epic_name}

# 2.1. ⭐ 验证更新后的任务（强制要求）
# 验证所有任务（包括新增、修改、未变的任务）
/pm:epic-decompose-validation {epic_name}

系统会自动识别：

• ✅ KEEP：内容未变化的任务（保持不动）
• 🔄 UPDATE：内容有变化的任务（增量更新）
• 🆕 CREATE：Epic中新增的任务（创建新文件）
• ⚠️ ORPHAN：文件存在但Epic中已删除的任务（警告但不删除）

⭐ 重要：重新分解后必须重新验证所有任务，确保新增和修改的任务都符合质量标准

输出示例：

📋 Task 235: ✅ KEEP (content matches)
📋 Task 236: ✅ KEEP (content matches, completed)
📋 Task 237: 🔄 UPDATE (added 2 acceptance criteria)
📋 Task 004: 🆕 CREATE (new from epic - User authentication)
📋 Task 005: 🆕 CREATE (new from epic - Permission management)

Summary:
- ✅ KEEP: 2 (不变)
- 🔄 UPDATE: 1 (更新)
- 🆕 CREATE: 2 (新增)
- Total: 5 tasks

Proceed with update? (yes/no/manual)

同步到GitHub选项：

⚠️ 检测到已更新的任务需要同步到GitHub:
  - Task 237: UI components (updated)
  
是否立即同步到GitHub?
  [y] 是 - 同步所有已更新的任务
  [n] 否 - 稍后手动同步
  [s] 选择 - 逐个选择要同步的任务

新增任务的处理：

• 新增任务文件命名为：004.md, 005.md（尚未同步）
• 需要先完成Step 3同步到GitHub后，才会重命名为 {issue_number}-{title}.md

Step 3: 同步新任务到GitHub（可选）

# 3a. 如果有新增任务，需要同步到GitHub创建Issue
/pm:epic-sync {epic_name}

注意：

• epic-sync 会检测到Epic已同步，只会创建新增的任务
• 新任务会作为sub-issue创建并关联到Epic
• 任务文件会自动重命名（004.md → 248-user-authentication.md）

或者选择不创建新Issue，直接开始工作：

# 3b. 直接开始任务（针对已更新的任务）
/pm:issue-start {existing_issue_number}

工作流程图示

需求变更/新增
    ↓
Step 1: /pm:epic-edit
    - 编辑Epic内容
    - 添加新任务 [ ] 004 - New Feature
    - 更新现有任务内容
    ↓
Step 2: /pm:epic-decompose
    - 自动识别：KEEP/UPDATE/CREATE
    - 创建新任务文件：004.md, 005.md
    - 更新已变化的任务文件：237-xxx.md
    - 提示是否同步已更新任务到GitHub
    ↓
Step 3: 根据提示选择
    ↓
┌───────────────┴────────────────┐
│                                │
有新增任务                    只有更新任务
↓                                ↓
/pm:epic-sync                   /pm:issue-start {issue_number}
- 创建新Issue                   - 直接开始已更新任务
- 重命名文件                    - 执行8步开发流程
  004.md → 248-xxx.md
↓
/pm:issue-start {new_issue_number}
- 开始新任务开发

实际操作示例

场景：为"用户认证"Epic新增"权限管理"功能

# Step 1: 编辑Epic
/pm:epic-edit user-auth

# （交互式编辑，添加新任务）
# 在Task Breakdown Preview中添加：
# - [ ] 004 - 实现RBAC权限管理系统

# Step 2: 重新分解
/pm:epic-decompose user-auth

# 输出：
# 📋 Task 235: ✅ KEEP (已完成，不变)
# 📋 Task 236: ✅ KEEP (已完成，不变)
# 📋 Task 237: ✅ KEEP (内容未变)
# 📋 Task 004: 🆕 CREATE (新增 - RBAC权限管理)
# 
# 创建新文件：.claude/epics/user-auth/004.md

# Step 3a: 同步到GitHub（创建新Issue）
/pm:epic-sync user-auth

# 输出：
# ✅ 检测到1个新任务，创建为Issue #248
# 文件重命名：004.md → 248-implement-rbac-permissions.md

# Step 3b: 开始新任务
/pm:issue-start 248

# 执行完整的8步开发流程...

关键注意事项

✅ DO：

• 在epic-edit时清楚标记新增内容（可用🆕标识）
• 保持已完成任务的 [x] 标记
• 重新分解前确认Epic内容正确
• 新增任务后及时同步到GitHub

❌ DON'T：

• 不要手动修改任务文件编号
• 不要删除已同步的任务文件
• 不要在Epic中删除已完成的任务
• 不要跳过epic-decompose直接修改任务文件

增量更新的智能识别：

# 系统会对比：
- title              # 标题是否变化
- description        # 描述是否变化
- acceptance_criteria # 验收标准是否新增
- technical_details  # 技术细节是否更新
- dependencies       # 依赖关系是否调整
- effort            # 工时估算是否修正

# 只有实际内容变化才会UPDATE，避免不必要的更新

已完成任务的保护：

• status: completed 的任务内容不会被UPDATE
• 即使Epic中内容变化，已完成任务保持KEEP状态
• 这避免了错误覆盖已完成的工作

4. 代码质量指南

4.1 通用编码指南

命名指南

• 文件名: 小写+连字符（kebab-case）

  • ✅ user-authentication.dart
  • ❌ UserAuthentication.dart
  • ❌ user_authentication.dart

• 类名: 大驼峰（PascalCase）

  • ✅ UserAuthenticationService
  • ❌ userAuthenticationService

• 函数/方法名: 小驼峰（camelCase）

  • ✅ getUserProfile()
  • ❌ GetUserProfile()

• 常量: 大写+下划线（UPPER_SNAKE_CASE）

  • ✅ MAX_RETRY_COUNT
  • ❌ maxRetryCount

文件头部注释指南（强制）

所有新建文件必须在顶部添加功能说明注释：

/// Dart/Flutter示例
/// 
/// 用户认证服务
/// 
/// 职责：处理用户登录、注册、token管理和会话持久化
/// 主要功能：
/// - 手机号+验证码登录
/// - 微信/支付宝第三方登录
/// - JWT Token自动刷新
/// - 登录状态持久化

/**
 * JavaScript/TypeScript示例
 * 
 * 订单管理API服务
 * 
 * 职责：处理订单的创建、查询、更新和删除操作
 * 主要功能：
 * - 订单创建和价格计算
 * - 订单状态流转管理
 * - 订单查询和筛选
 * - 订单取消和退款
 */

# Python示例
#
# 数据库迁移脚本 - V001_create_users_table
#
# 职责：创建用户表及相关索引
# 主要变更：
# - 创建users表（包含基础字段和认证字段）
# - 创建索引（phone_number, email, created_at）
# - 添加外键约束（role_id -> roles表）

冗余代码检查（强制）

提交前必须清理：

// ❌ 未使用的导入
import 'package:unused_package/unused.dart';  // 删除

// ❌ 未使用的变量
final unusedVariable = 'test';  // 删除

// ❌ 注释掉的死代码
// void oldFunction() {
//   // old implementation
// }  // 删除整个注释块

// ❌ 重复的代码
void calculatePrice1() {
  final price = basePrice * quantity;
  return price;
}
void calculatePrice2() {
  final price = basePrice * quantity;  // 重复！合并为一个函数
  return price;
}

Linter配置示例（Flutter）：

# analysis_options.yaml
linter:
  rules:
    - unused_import          # 检测未使用的导入
    - unused_local_variable  # 检测未使用的变量
    - dead_code             # 检测死代码

4.2 代码审查清单

提交前自查

• [ ] 代码通过Linter检查（零警告零错误）
• [ ] 新文件已添加头部功能说明注释
• [ ] 无未使用的导入语句
• [ ] 无未使用的变量或方法
• [ ] 无注释掉的死代码
• [ ] 无重复的代码片段
• [ ] 所有函数和类都有文档注释
• [ ] 复杂逻辑有行内注释说明
• [ ] 错误处理完善
• [ ] 日志输出合理

Code Review清单

• [ ] 代码逻辑正确
• [ ] 符合架构设计
• [ ] 命名清晰准确
• [ ] 无明显性能问题
• [ ] 无安全漏洞
• [ ] 测试覆盖充分
• [ ] 文档完整准确

4.3 架构指南

Flutter应用架构（DDD + Clean Architecture）

lib/
├── core/                 # 核心基础设施
│   ├── errors/          # 错误定义
│   ├── usecases/        # Use Case基类
│   └── utils/           # 工具类
├── features/            # 功能模块
│   └── {feature_name}/  # 具体功能
│       ├── domain/      # 领域层（业务逻辑）
│       │   ├── entities/        # 实体
│       │   ├── repositories/    # Repository接口
│       │   └── usecases/        # Use Cases
│       ├── data/        # 数据层
│       │   ├── models/          # DTO模型
│       │   ├── datasources/     # 数据源
│       │   └── repositories/    # Repository实现
│       └── presentation/  # 表现层
│           ├── providers/       # Riverpod Providers
│           ├── pages/           # 页面
│           └── widgets/         # 组件
└── main.dart

层级依赖规则：

• Presentation → Domain ← Data
• Domain层不依赖其他层
• Data层实现Domain层定义的接口
• Presentation层通过Domain层使用Data层

后端微服务架构（Spring Boot）

backend/
├── user-service/        # 用户服务
│   ├── src/main/java/com/maiban/user/
│   │   ├── controller/  # REST控制器
│   │   ├── service/     # 业务逻辑
│   │   ├── repository/  # 数据访问
│   │   ├── model/       # 领域模型
│   │   └── dto/         # 数据传输对象
│   └── src/test/        # 测试代码
├── order-service/       # 订单服务
└── common/              # 共享组件

4.4 性能指南

• API响应时间: 95%请求<1秒
• 页面加载: 首屏<3秒
• 内存使用: 避免内存泄漏
• 数据库查询:
  • 使用索引优化查询
  • N+1查询必须优化
  • 批量操作使用批处理

4.5 安全指南

• 数据加密: 敏感数据AES加密存储
• 传输加密: HTTPS + TLS 1.3
• 认证鉴权: JWT Token + RBAC权限
• 输入验证: 所有用户输入必须验证
• SQL注入防护: 使用参数化查询
• XSS防护: 输出转义
• CSRF防护: 使用CSRF Token

5. 测试指南

5.1 测试类型和覆盖率要求

5.2 测试文件组织

.claude/epics/{epic_name}/issues/{issue_number}/tests/
├── unit/                          # 单元测试
│   ├── models/
│   │   └── user_model_test.dart
│   └── services/
│       └── auth_service_test.dart
├── widget/                        # Widget测试
│   └── login_page_test.dart
└── integration/                   # 集成测试
    └── login_flow_test.dart

5.3 测试命名指南

// 单元测试命名格式：{class_name}_test.dart
// 示例：user_authentication_service_test.dart

void main() {
  group('UserAuthenticationService', () {
    test('should return user when login with valid credentials', () {
      // Arrange
      final service = UserAuthenticationService();
      final credentials = Credentials(phone: '13800138000', code: '123456');
      
      // Act
      final result = await service.login(credentials);
      
      // Assert
      expect(result.isSuccess, true);
      expect(result.user.phone, '13800138000');
    });
    
    test('should throw AuthException when login with invalid credentials', () {
      // Arrange & Act & Assert
      expect(
        () => service.login(invalidCredentials),
        throwsA(isA<AuthException>()),
      );
    });
  });
}

5.4 测试最佳实践

1. 测试真实实现，不过度mock

   // ❌ 不好：过度mock
   when(mockService.getData()).thenReturn(fakeData);
   
   // ✅ 好：测试真实实现
   final service = RealService(testDatabase);
   final data = await service.getData();
   

2. 使用有意义的测试数据

   // ❌ 不好：无意义数据
   final user = User(id: '123', name: 'test');
   
   // ✅ 好：有意义数据
   final user = User(id: 'user-001', name: '张三', phone: '13800138000');
   

3. 测试边界情况

   test('should handle empty list', () { });
   test('should handle null value', () { });
   test('should handle maximum length input', () { });
   

4. 详细的日志输出

   test('complex business logic', () {
     print('Testing with input: $input');
     final result = complexFunction(input);
     print('Got result: $result');
     expect(result, expectedValue);
   });
   

6. Git工作流指南

6.1 分支策略

main (生产环境)
  ↑
develop (开发环境)
  ↑
feature/{epic_name}-{issue_number} (功能开发)

6.2 分支命名指南

• 功能分支: feature/{epic_name}-{issue_number}

  • 示例: feature/user-auth-235

• 修复分支: fix/{issue_number}-{brief-description}

  • 示例: fix/246-login-crash

• 热修复分支: hotfix/{issue_number}-{brief-description}

  • 示例: hotfix/250-payment-error

6.3 提交消息指南

格式

Issue #{issue_number}: {type}: {简短描述}

{详细说明（可选）}

{关联信息（可选）}

Type类型

• feat: 新功能
• fix: Bug修复
• refactor: 重构
• docs: 文档更新
• test: 测试代码
• chore: 构建/工具变更
• style: 代码格式调整

示例

Issue #235: feat: 实现用户手机号登录功能

- 添加手机号验证逻辑
- 集成短信验证码服务
- 实现JWT Token生成

Closes #235

6.4 提交频率

• 增量提交: 每完成一个小功能点就提交
• 最小提交: 每次提交应该是独立可测试的
• 频繁提交: 至少每天提交一次
• 避免大提交: 单次提交修改行数<500行

6.5 合并策略

Pull Request要求

• 必须关联GitHub Issue
• 必须通过CI检查
• 必须至少1人Code Review通过
• 必须测试通过
• 必须更新相关文档

PR标题格式

Issue #{issue_number}: {简短描述}

PR描述模板

## 关联Issue
Closes #{issue_number}

## 变更说明
- 主要变更1
- 主要变更2

## 测试情况
- [ ] 单元测试通过
- [ ] 集成测试通过
- [ ] 手动测试通过

## 截图/录屏
（如有UI变更）

## Checklist
- [ ] 代码通过Linter检查
- [ ] 新文件已添加头部注释
- [ ] 无冗余代码
- [ ] 测试覆盖率≥80%
- [ ] 文档已更新

7. GitHub同步指南

7.1 同步时机

7.2 Epic同步流程（重要）

⚠️ 首次同步检查（防止重复）：

# 执行 /pm:epic-sync {epic_name} 时会自动检查
# 如果epic.md已有github字段，说明已同步过

# 选项：
# 1. 查看现有Epic: gh issue view {epic_number}
# 2. 更新Epic内容: /pm:epic-update {epic_name}
# 3. 仅同步任务: /pm:tasks-sync {epic_name}

同步后的文件变化：

同步前：
.claude/epics/{epic_name}/
├── epic.md
├── 001.md
├── 002.md
└── 003.md

同步后（文件会被重命名）：
.claude/epics/{epic_name}/
├── epic.md  (frontmatter更新: github, updated, last_sync)
├── 235-verify-core-architecture.md  (原001.md)
├── 236-implement-api-endpoints.md    (原002.md)
├── 237-create-ui-components.md       (原003.md)
└── github-mapping.md  (新增映射文件)

重要规则：

1. 任务文件重命名: 001.md → {issue_number}-{title-slug}.md
2. 依赖关系更新: depends_on: [001, 002] → depends_on: [235, 236]
3. Frontmatter更新: 添加github字段和updated时间戳
4. 映射文件创建: 生成github-mapping.md记录对应关系

7.3 Issue同步内容指南

进度更新评论格式：

## 🔄 Progress Update - {current_date}

### ✅ Completed Work
- 完成用户登录页面UI实现
- 集成手机号验证码发送API
- 实现登录状态持久化

### 🔄 In Progress
- 正在实现第三方登录（微信/支付宝）

### 📝 Technical Notes
- 使用Riverpod进行状态管理
- JWT Token存储在SecureStorage
- 登录失败最多重试3次

### 📊 Acceptance Criteria Status
- ✅ 手机号+验证码登录功能
- ✅ 登录状态持久化
- 🔄 第三方授权登录（进行中）
- □ 自动登录功能（待开始）

### 🚀 Next Steps
- 完成微信登录集成
- 添加登录错误提示
- 编写集成测试

### ⚠️ Blockers
无

### 💻 Recent Commits
- `abc1234` - Issue #235: feat: 实现手机号登录UI
- `def5678` - Issue #235: feat: 集成验证码API

---
*Progress: 60% | Synced from local updates at 2025-10-28T10:30:00Z*

7.4 任务完成同步

完成评论格式：

## ✅ Task Completed - {current_date}

### 🎯 All Acceptance Criteria Met
- ✅ 手机号+验证码登录功能
- ✅ 第三方授权登录（微信/支付宝）
- ✅ 登录状态持久化
- ✅ 自动登录功能

### 📦 Deliverables
- 登录页面UI（含表单验证）
- 用户认证服务（含Token管理）
- 第三方登录集成（微信SDK/支付宝SDK）
- 单元测试和Widget测试

### 🧪 Testing
- Unit tests: ✅ Passing (覆盖率: 85%)
- Widget tests: ✅ Passing (覆盖率: 78%)
- Integration tests: ✅ Passing
- Manual testing: ✅ Complete

### 📚 Documentation
- Code documentation: ✅ 所有公共API已添加文档注释
- README updates: ✅ 更新了认证模块说明

### 编码标准符合度
- ✅ 代码已格式化（flutter format）
- ✅ 通过Linter检查（零警告零错误）
- ✅ 新文件已添加头部功能说明注释
- ✅ 无冗余代码（无未使用导入、死代码）
- ✅ 代码已复用现有函数

This task is ready for review and can be closed.

---
*Task completed: 100% | Synced at 2025-10-28T15:45:00Z*

8. 架构设计指南

8.1 架构图指南

所有Epic和Task必须包含架构图。使用标准mermaid语法，根据复杂度选择合适的层级：

Level 1: 系统上下文层（System Context）

适用场景：

• 新的独立系统
• 重大功能特性
• 需要展示与外部系统交互

graph TB
    User[用户<br/>使用APP的用户]
    App[麦瓣健康APP<br/>提供健康服务预约]
    SMS[短信服务<br/>发送验证码]
    WeChat[微信开放平台<br/>第三方登录]
    DB[(用户数据库<br/>存储用户信息)]
    
    User -->|登录/注册| App
    App -->|发送验证码<br/>HTTP API| SMS
    App -->|OAuth授权<br/>OAuth 2.0| WeChat
    App -->|读写用户数据<br/>SQL| DB
    
    style App fill:#4a90e2,color:#fff
    style SMS fill:#f5a623
    style WeChat fill:#f5a623
    style DB fill:#50e3c2

Level 2: 容器层（Container Level）

适用场景：

• 微服务架构
• 需要展示前后端分离
• 需要展示数据库和缓存

graph TB
    User[用户]
    Tech[技师]
    
    subgraph "麦瓣健康平台"
        UserApp[用户端APP<br/>Flutter]
        TechApp[技师端APP<br/>Flutter]
        Gateway[API网关<br/>Spring Cloud Gateway]
        OrderSvc[订单服务<br/>Spring Boot]
        PaySvc[支付服务<br/>Spring Boot]
        OrderDB[(订单数据库<br/>PostgreSQL)]
        Redis[(Redis缓存)]
    end
    
    WeChatPay[微信支付]
    
    User -->|HTTPS| UserApp
    Tech -->|HTTPS| TechApp
    UserApp -->|REST/JSON| Gateway
    TechApp -->|REST/JSON| Gateway
    Gateway -->|HTTP| OrderSvc
    OrderSvc -->|gRPC| PaySvc
    OrderSvc -->|SQL| OrderDB
    OrderSvc -->|缓存| Redis
    PaySvc -->|HTTPS| WeChatPay
    
    style UserApp fill:#4a90e2,color:#fff
    style TechApp fill:#4a90e2,color:#fff
    style Gateway fill:#7ed321,color:#fff
    style OrderSvc fill:#7ed321,color:#fff
    style PaySvc fill:#7ed321,color:#fff
    style OrderDB fill:#50e3c2
    style Redis fill:#50e3c2
    style WeChatPay fill:#f5a623

Level 3: 组件层（Component Level）

适用场景：

• 单个微服务内部设计
• 需要展示模块划分
• 需要展示设计模式

graph TB
    Gateway[API网关<br/>Spring Cloud Gateway]
    
    subgraph "订单服务 Order Service"
        Controller[OrderController<br/>REST控制器<br/>处理HTTP请求]
        UseCase[OrderUseCase<br/>业务逻辑<br/>订单处理流程]
        Calculator[PriceCalculator<br/>价格计算组件]
        RepoInterface[OrderRepository<br/>接口<br/>数据访问接口]
        RepoImpl[OrderRepositoryImpl<br/>实现<br/>数据访问实现]
    end
    
    OrderDB[(订单数据库<br/>PostgreSQL)]
    PaymentSvc[支付服务<br/>Spring Boot]
    
    Gateway -->|HTTP| Controller
    Controller --> UseCase
    UseCase --> Calculator
    UseCase --> RepoInterface
    RepoInterface -.实现.-> RepoImpl
    RepoImpl -->|SQL| OrderDB
    UseCase -->|gRPC| PaymentSvc
    
    style Controller fill:#4a90e2,color:#fff
    style UseCase fill:#4a90e2,color:#fff
    style Calculator fill:#4a90e2,color:#fff
    style RepoInterface fill:#9013fe,color:#fff
    style RepoImpl fill:#7ed321,color:#fff
    style OrderDB fill:#50e3c2

8.2 架构决策记录（ADR）

对于重要的架构决策，应记录在Epic或Task中：

## Architecture Decisions

### ADR-001: 使用Riverpod进行状态管理

**Context**: 
Flutter应用需要选择状态管理方案

**Decision**:
选择Riverpod作为状态管理方案

**Rationale**:
- 编译期类型安全
- 支持依赖注入
- 测试友好
- 性能优秀
- 社区活跃

**Consequences**:
- 团队需要学习Riverpod
- 需要重构部分现有代码
- 长期维护性更好

**Alternatives Considered**:
- Provider: 功能较弱
- Bloc: 样板代码多
- GetX: 不够类型安全

9. 任务管理指南

9.1 任务优先级

9.2 任务状态流转

open (新建)
  ↓
in-progress (进行中)
  ↓
ready-for-review (待审查)
  ↓
in-review (审查中)
  ↓
completed (已完成) / blocked (阻塞)
  ↓
closed (关闭)

9.3 任务依赖管理

Frontmatter配置：

depends_on: [235, 236]    # 依赖任务（必须先完成）
parallel: true            # 可并行开发
conflicts_with: [237]     # 冲突任务（不能同时开发）

依赖规则：

• 有depends_on的任务不能在依赖完成前开始
• parallel: true的任务可以同时开发
• conflicts_with的任务不能同时分配给同一人

9.4 任务大小估算

拆分原则：

• 单个任务不超过3天（24小时）
• XL任务必须拆分
• 保持任务独立可交付

10. 团队协作指南

10.1 每日站会

时间: 每天早上10:00
时长: 15分钟

汇报内容：

1. 昨天完成了什么
2. 今天计划做什么
3. 遇到什么阻碍

使用命令：

/pm:standup  # 生成站会报告

10.2 代码审查流程

审查清单：

• [ ] 代码逻辑正确
• [ ] 符合编码标准
• [ ] 测试覆盖充分
• [ ] 文档完整
• [ ] 无明显性能问题
• [ ] 无安全漏洞

审查时效：

• P0任务：4小时内完成审查
• P1任务：1天内完成审查
• P2/P3任务：2天内完成审查

10.3 沟通指南

Issue讨论

• 技术问题在GitHub Issue中讨论
• 重要决策记录在Issue评论中
• @相关人员确保看到消息

文档更新

• PRD变更必须通知相关开发
• Epic变更需同步到所有相关任务
• 架构变更需要团队评审

问题上报

• 阻塞问题立即上报
• 技术风险提前预警
• 进度延误及时沟通

10.4 知识分享

技术分享会：

• 频率：每周一次
• 内容：新技术、最佳实践、踩坑经验
• 文档：整理为Markdown文档存档

文档维护：

• 技术方案文档化
• 常见问题FAQ化
• 最佳实践沉淀

11. 质量门禁

11.1 提交前检查（Pre-commit）

# 自动运行（建议配置git hooks）
flutter analyze               # Linter检查
flutter test                  # 运行测试
flutter format --set-exit-if-changed .  # 格式检查

11.2 PR合并前检查

必须通过：

• [ ] CI构建成功
• [ ] 所有测试通过
• [ ] Linter零警告零错误
• [ ] 代码覆盖率≥80%
• [ ] Code Review通过
• [ ] 文档已更新

11.3 Epic分解前检查（强制）

在执行 /pm:epic-decompose 后必须执行：

• [ ] /pm:epic-decompose-validation {epic_name} 验证所有任务质量
• [ ] 所有任务得分≥90分（优秀）
• [ ] 无关键问题（Critical Issues = 0）
• [ ] 任务完整且自包含（无外部引用）
• [ ] 所有API规格、技术细节、实现方案完整

验证失败处理：

• ❌ 得分<60分：立即修复所有关键问题
• ⚠️ 得分60-89分：建议修复警告问题后再继续
• ✅ 得分≥90分：可以继续 /pm:epic-sync

验证报告示例：

Epic Validation Report: ai-android-automation-client
Overall Score: 85/100
Tasks Validated: 8
✅ Passed: 5 | ⚠️ Warnings: 2 | ❌ Failed: 1
Critical Issues: 2 | Minor Issues: 5

11.4 发布前检查

必须完成：

• [ ] 所有P0任务已关闭
• [ ] 所有集成测试通过
• [ ] 性能测试达标
• [ ] 安全扫描通过
• [ ] 发布文档完整
• [ ] 回滚方案准备

12. 附录

12.1 常用命令速查

12.2 文件路径速查

.claude/prds/{feature_name}.md                           # PRD文件
.claude/epics/{epic_name}/epic.md                        # Epic主文档
.claude/epics/{epic_name}/{issue_number}-*.md            # 任务文件
.claude/epics/{epic_name}/github-mapping.md              # GitHub映射
.claude/epics/{epic_name}/issues/{issue_number}/         # Issue工作目录
  ├── analysis.md                                        # 技术分析
  ├── progress.md                                        # 进度跟踪
  └── tests/                                             # 测试文件

12.3 状态标签速查

Epic状态：

• backlog: 待开始
• in-progress: 进行中
• completed: 已完成
• cancelled: 已取消

Task状态：

• open: 新建
• in-progress: 进行中
• ready-for-review: 待审查
• completed: 已完成
• blocked: 阻塞
• cancelled: 已取消

GitHub标签：

• epic: Epic Issue
• task: 任务Issue
• epic:{name}: 所属Epic
• P0/P1/P2/P3: 优先级
• bug: Bug修复
• feature: 新功能
• refactor: 重构

12.4 常见问题FAQ

Q1: Epic已经同步到GitHub，如何避免重复创建？

A: /pm:epic-sync 命令会自动检查。如果Epic已同步，会提示并阻止重复创建。

Q2: 任务文件从001.md变成235-xxx.md后，如何找到对应的Issue？

A: 查看 .claude/epics/{epic_name}/github-mapping.md 文件，里面记录了完整的映射关系。

Q3: 验证任务是不是只需要检查代码，不需要编码？

A: 错！所有任务都需要完整执行8步流程。即使标题包含"验证"，也要先审阅代码，判断是否需要编码。

Q4: 代码已经通过Linter，为什么还要求零警告零错误？

A: 这是强制要求。任何警告都可能隐藏潜在问题。提交前必须清理所有警告。

Q5: 新建文件忘记添加头部注释怎么办？

A: 立即补充！这是强制要求。格式参考第4.1节的示例。

Q6: 依赖关系中的任务编号是001还是GitHub Issue编号？

A:

• 同步前：使用逻辑编号（001, 002）
• 同步后：自动更新为Issue编号（235, 236）

Q7: 如何知道哪些任务可以并行开发？

A: 查看任务文件的frontmatter中的 parallel: true 字段和 depends_on 依赖关系。

Q8: 测试覆盖率达不到80%怎么办？

A: 必须补充测试！这是最低要求，不能妥协。重点测试业务逻辑和边界情况。

Q9: Issue进度应该多久同步一次到GitHub？

A:

• 最低频率：每天至少1次
• 推荐频率：每完成一个重要里程碑就同步
• 完成时：必须同步

Q10: Pull Request需要几个人审查？

A:

• P0任务：至少1人审查，4小时内完成
• P1任务：至少1人审查，1天内完成
• P2/P3任务：至少1人审查，2天内完成

Q11: Epic已同步到GitHub，如何新增需求或模块？

A: 使用3步流程：

1. /pm:epic-edit {epic_name} - 编辑Epic添加新任务
2. /pm:epic-decompose {epic_name} - 重新分解（智能识别变更）
3. /pm:epic-sync {epic_name} - 同步新任务到GitHub 详见：3.4 需求变更和新增模块流程

Q12: epic-decompose如何识别任务是新增还是更新？

A: 系统会智能对比：

• KEEP: 内容完全匹配或已完成的任务
• UPDATE: 标题、描述、验收标准等有变化
• CREATE: Epic中新增但文件不存在的任务
• ORPHAN: 文件存在但Epic中已删除（仅警告）

Q13: 更新的任务需要立即同步到GitHub吗？

A: epic-decompose会提示你选择：

• [y] 立即同步所有已更新的任务
• [n] 稍后手动同步
• [s] 逐个选择要同步的任务 已完成的任务不会被更新，保护已完成的工作。

Q14: AI大模型在开发流程中扮演什么角色？

A: AI大模型是开发助手而非决策者：

• ✅ AI可以：生成代码、编写测试、检查标准、生成文档
• ❌ AI不可以：决定产品方向、选择核心架构、确定优先级、改变需求边界
• 🤝 需要人工确认：产品需求、架构决策、任务范围、复杂业务逻辑 详见：AI大模型如何使用这份手册？

Q15: 如何确保AI生成的代码符合项目要求？

A: 通过明确的流程和强制检查：

• 清晰输入：PRD → Epic → Task，每层都有清晰边界
• 8步流程：AI必须按步骤执行（代码审阅→质量检查→实现→验证）
• 强制检查：Linter零错误、测试≥80%、文件头部注释、无冗余代码
• 人工审查：Code Review确保业务逻辑正确性

Q16: 为什么强调"需求先行"？

A: 需求先行是高质量开发的基础：

• 避免返工：需求不清晰导致的重复开发成本极高
• 指导AI：明确的需求让AI理解边界，生成正确代码
• 团队对齐：所有人基于同一份PRD工作，减少误解
• 质量保证：有明确验收标准，才能判断功能是否完成 流程：PRD（产品需求）→ Epic（技术方案）→ Task（具体实现）

Q17: /pm:epic-decompose-validation 验证失败怎么办？

A: 根据失败类型采取不同措施：

• 得分<60分（失败）：立即修复所有关键问题
  • 检查API规格是否完整
  • 补充技术细节章节
  • 移除所有外部引用（Epic.md等）
  • 修复不完整字段（TBD等）
• 得分60-89分（警告）：建议修复后再继续
  • 完善工时估算
  • 补充依赖列表
  • 优化验收标准
• 关键问题示例：
  • ❌ "API details in epic.md section X"
  • ❌ "Parameters TBD"
  • ❌ 缺少Technical Details章节

修复后重新运行验证直到所有任务≥90分。

Q18: 什么时候需要重新验证Epic？

A: 以下情况必须重新验证：

• ✅ 执行 /pm:epic-decompose 后（立即验证）
• ✅ 执行 /pm:epic-edit + 重新分解后
• ✅ 手动修改任务文件后
• ✅ 从GitHub同步任务变更后

注意：验证是强制要求，任何任务修改后都必须重新验证。

版本历史

文档维护：本文档持续更新，如有疑问或建议，请在项目管理Slack频道讨论。