---
name: task-handoff-checklist
description: Generates structured handoff reports after completing development tasks. Scans changes across 8 dimensions (navigation, documentation, rules, workflows, testing, risks, code quality, follow-ups) to enable zero-question acceptance. Trigger words: "交接", "验收", "handoff", "/handoff".
---

# Task Handoff Checklist — 任务交接清单

AI 完成开发后，自动扫描变更，生成结构化交接报告。验收者不用追问就知道：改了哪里、测什么、沉淀了什么、有什么坑。

## 目录

- [核心理念](#核心理念)
- [执行流程](#执行流程)
- [交接报告模板](#交接报告模板)
- [报告质量规则](#报告质量规则)
- [上下游技能](#上下游技能)

## 核心理念

1. **零追问验收**：报告拿到即可核对，不需反复追问
2. **强制全面扫描**：8 个维度逐项扫描，有就报，没有明确说"无"
3. **串联已有技能**：交接清单是入口，告诉你接下来该用哪些技能
4. **沉淀驱动**：每次交接都是知识沉淀的检查点

## 执行流程

```
交接进度：
- [ ] Phase 1: 扫描变更范围
- [ ] Phase 2: 逐维度生成交接报告（8 个维度全覆盖）
- [ ] Phase 3: 串联后续技能建议
```

### Phase 1: 扫描变更范围

```bash
# 获取变更文件和统计
git diff --name-only main...HEAD 2>/dev/null || git diff --name-only HEAD~10
git diff --stat main...HEAD 2>/dev/null || git diff --stat HEAD~10
```

按目录分类：`prd-api/`(后端) `prd-admin/`(前端) `prd-desktop/`(桌面) `doc/`(文档) `.claude/`(技能/规则)

### Phase 2: 逐维度生成报告

按 8 个维度逐项扫描。每个维度的详细扫描命令 → 见 [reference/scan-commands.md](reference/scan-commands.md)

## 交接报告模板

```markdown
# 任务交接清单

> **任务描述**: {一句话概括}
> **变更范围**: {N} 个文件 | +{ins} / -{del} 行
> **涉及端**: {后端 / 管理后台 / 桌面端 / 文档}

---

## 一、导航与入口变更

| 维度 | 状态 | 详情 |
|------|------|------|
| 管理后台路由 | ✅ 新增 / 🔄 修改 / ➖ 无变化 | {路由路径，如 `/review-agent`} |
| **百宝箱注册** | ✅ 已注册 / ⚠️ 未注册 / ➖ 无需 | {`toolboxStore.ts` BUILTIN_TOOLS 中的 id} |
| 左侧导航 | ✅ 新增 / 🔄 修改 / ➖ 未加 | {`AdminMenuCatalog.cs` 中的条目 + 分组} |
| 首页快捷入口 | ✅ 新增 / ➖ 未加 | {`QUICK_AGENTS` 或 `LandingPage.tsx` AgentShowcase} |
| API 端点 | ✅ 新增 / 🔄 修改 / ➖ 无变化 | {端点列表} |
| 桌面端入口 | ✅ 新增 / 🔄 修改 / ➖ 无变化 | {入口位置} |

**位置声明**（新 Agent / 新页面必填，两行格式）：

```
【位置】百宝箱 / 左侧导航"XX"菜单 / 首页快捷入口
【路径】登录后首页 → 1) 点击 → 2) 点击 → 3) 到达
```

详见 `.claude/rules/navigation-registry.md`。

---

## 二、文档沉淀

| 检查项 | 状态 | 说明 |
|--------|------|------|
| SRS | ✅ 已更新 / ⚠️ 需更新 / ➖ 无需 | {内容} |
| PRD | ✅ 已更新 / ⚠️ 需更新 / ➖ 无需 | {内容} |
| 数据字典 | ✅ 已更新 / ⚠️ 需更新 / ➖ 无需 | {新增集合/字段} |
| 设计文档 | ✅ 已创建 / ⚠️ 需创建 / ➖ 无需 | {文档名} |
| CLAUDE.md 快照 | ✅ 已更新 / ⚠️ 需更新 / ➖ 无需 | {功能注册表/集合清单} |

**待补文档清单**（如有）: - [ ] ...

---

## 三、规则与约定

| 检查项 | 状态 | 说明 |
|--------|------|------|
| 新增 appKey | ✅ / ➖ | {名称} |
| 新增 AppCallerCode | ✅ / ➖ | {格式和用途} |
| 新增架构模式 | ✅ / ➖ | {是否需写 rule.*.md} |
| 修改已有规则 | ✅ / ➖ | {影响范围} |
| 新增 MongoDB 集合 | ✅ / ➖ | {集合名，需同步数据字典} |
| 新增权限点 | ✅ / ➖ | {权限名} |

---

## 四、流程变更

| 检查项 | 状态 | 影响范围 |
|--------|------|----------|
| Breaking Change | ✅ / ➖ | {受影响端} |
| 数据模型变更 | ✅ / ➖ | {字段变更} |
| 状态机变更 | ✅ / ➖ | {转换变更} |
| 前后端交互变更 | ✅ / ➖ | {如轮询→SSE} |
| 权限变更 | ✅ / ➖ | {权限要求变化} |
| 配置项变更 | ✅ / ➖ | {新增环境变量} |

**迁移注意事项**（如有 Breaking Change）: ...

---

## 五、测试计划

### 测试矩阵

| 类型 | 需要？ | 状态 | 说明 |
|------|--------|------|------|
| 单元测试 | ✅/➖ | ✅ 完成 / ⚠️ 未完成 | {测试文件} |
| 冒烟测试 | ✅/➖ | ✅ 完成 / ⚠️ 未完成 | {端点} |
| 页面测试 | ✅/➖ | ⚠️ 需人工 | {页面} |
| 回归测试 | ✅/➖ | ⚠️ 需人工 | {受影响功能} |

### 预览验收地址（需人工验收时必填）

当测试矩阵中存在"⚠️ 需人工"的项目时，**只跑这一条命令**拿预览域名，**禁止**自己 slugify / 手写 `tr '/' '-'`：

```bash
python3 .claude/skills/cds/cli/cdscli.py --human preview-url
```

它会自动从 `/api/branches` 拿后端真实 `previewSlug`（v3 SSOT，与 `cds/src/services/preview-slug.ts:computePreviewSlug` 同源）。没 CDS 凭据时自动回退本地推算，永不漂。

> **预览地址**: <cdscli 输出原文>
>
> **验收路径**:
> 1. 打开 <cdscli 输出原文>{页面路径}
> 2. {具体操作步骤}
> 3. {期望结果}

### 推荐顺序

第 1 步: ... → 第 2 步: ... → 第 3 步: ...

### 技能串联

- [ ] `/smoke {模块}` → 冒烟测试
- [ ] `/verify` → 多角度验证
- [ ] `/preview` → 生成预览验收地址
- [ ] `fix unused imports` → 清理导入

---

## 六、注意事项与风险

- **已知限制**: {限制 + 临时方案}
- **潜在风险**: {条件 + 影响 + 规避}
- **依赖项**: {外部/内部依赖}
- **回滚方案**: {出问题如何回滚}

---

## 七、代码质量自检

| 检查项 | 状态 |
|--------|------|
| 编译通过 (`dotnet build`) | ✅ / ❌ |
| 前端构建 (`pnpm build`) | ✅ / ❌ / ➖ 无前端变更 |
| TypeScript (`pnpm tsc`) | ✅ / ❌ / ➖ |
| 无未使用导入 | ✅ / ⚠️ |

**架构合规**: Controller 身份隔离 / ILlmGateway / 前端无业务映射 / 服务器权威性

---

## 八、后续事项

| 事项 | 优先级 | 说明 |
|------|--------|------|
| {事项} | P0/P1/P2 | {描述} |

---

**交接时间**: {日期} | **交接人**: AI Assistant
```

## 报告质量规则

### 必须

1. **8 维度全覆盖**：即使全是"无变化"也要标出
2. **位置声明必填**：新 Agent / 新页面必须包含【位置】+【路径】两行，且百宝箱是最低配置
3. **测试顺序明确**：给出先后顺序和具体步骤
4. **页面测试可操作**：打开哪个页面→点什么→期望看到什么
5. **文档欠债列出**：应更新但未更新的明确标注待办
6. **风险诚实**：已知限制必须如实说明

### 禁止

1. **空话**：不能写"测试一下就行"，要写"用 `/smoke defect-agent` 测试"
2. **只给路由不给位置**：禁止"访问 `/new-agent` 即可"这种交付，必须说明在百宝箱/导航/首页的哪里
3. **遗漏 Breaking Change**：API 变更/字段重命名/行为改变必须标出
4. **跳过质量检查**：编译和类型检查必须实际运行
5. **模糊后续事项**：每项必须有优先级和可操作描述

## 上下游技能

```
代码完成 → /handoff（本技能）
              │
              ├─ 测试建议 → /smoke {模块}
              ├─ 质量问题 → fix unused imports
              ├─ 深入验证 → /verify
              └─ 周末收尾 → /weekly
```

完整示例 → 见 [reference/example.md](reference/example.md)