task-handoff-checklist

任务交接清单

版本：v1.0.0 | 状态：已落地 | 触发：/handoff、"交接"、"验收"、"handoff"

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

目录

• 核心理念
• 执行流程
• 交接报告模板
• 报告质量规则
• 上下游技能

核心理念

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

执行流程

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

Phase 1: 扫描变更范围

# 获取变更文件和统计
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

交接报告模板

# 任务交接清单

> **任务描述**: {一句话概括}
> **变更范围**: {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)