| name | task-handoff-checklist |
| version | 1.0.0 |
| description | 开发任务完成后自动扫描变更，从导航、文档、规则、工作流、测试、风险、代码质量、后续事项八个维度生成结构化交接报告，让验收者零追问即可核对。触发词："交接"、"验收"、"handoff"、"/handoff"。 |
任务交接清单
版本：v1.0.0 | 状态：已落地 | 触发：/handoff、"交接"、"验收"、"handoff"
AI 完成开发后，自动扫描变更，生成结构化交接报告。验收者不用追问就知道：改了哪里、测什么、沉淀了什么、有什么坑。
目录
核心理念
- 零追问验收：报告拿到即可核对，不需反复追问
- 强制全面扫描：8 个维度逐项扫描，有就报，没有明确说"无"
- 串联已有技能：交接清单是入口，告诉你接下来该用哪些技能
- 沉淀驱动：每次交接都是知识沉淀的检查点
执行流程
交接进度：
- [ ] 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 输出原文>
验收路径:
- 打开 <cdscli 输出原文>{页面路径}
- {具体操作步骤}
- {期望结果}
推荐顺序
第 1 步: ... → 第 2 步: ... → 第 3 步: ...
技能串联
六、注意事项与风险
- 已知限制: {限制 + 临时方案}
- 潜在风险: {条件 + 影响 + 规避}
- 依赖项: {外部/内部依赖}
- 回滚方案: {出问题如何回滚}
七、代码质量自检
| 检查项 | 状态 |
|---|
编译通过 (dotnet build) | 通过 / 未通过 |
前端构建 (pnpm build) | 通过 / 未通过 / 无前端变更 |
TypeScript (pnpm tsc) | 通过 / 未通过 / 无需 |
| 无未使用导入 | 通过 / 待处理 |
架构合规: Controller 身份隔离 / ILlmGateway / 前端无业务映射 / 服务器权威性
八、后续事项
交接时间: {日期} | 交接人: 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)
