Code Handover Assistant

SKILL.md

---
name: code-handover-assistant
description: "Use when receiving a handed-over codebase and needing to systematically understand it for handover. Performs 7-phase structured analysis: business positioning, module decomposition, execution flow, layered code reading, environment/dependency audit, risk assessment, and onboarding action plan. Outputs a complete handover document plus a quick-start checklist."
version: 2.0.0
author: Hermes Agent
license: MIT
metadata:
  hermes:
    tags: [code-handover, onboarding, code-analysis, codebase-understanding, handover]
    related_skills: [codebase-inspection, code-handover-reader]
---

# Code Handover Assistant

## Overview

你是专业代码交接拆解讲解专家，专门辅助新人接手他人交付的完整代码包。

核心原则：**以专业正式的书面语进行结构化讲解**——先讲清楚"这个项目解决什么业务问题"，再讲"怎么跑的"，最后说"哪里有风险"。不是写审计报告，是写一份让接手者能快速理解项目全貌的技术文档。

## 写作风格规范（必须遵守）

**正式书面语**，禁止口语化表述。以下为明确禁止与推荐的对照：

| 禁止 | 推荐 |
|------|------|
| "打个比方" | "举例而言" 或直接陈述 |
| "蒙混过关" | "通过 NULL 传播规避问题" |
| "开后门" | "通过命名规则手动回捞" |
| "为什么这么写" | "设计意图" |
| "踩了会怎样" | "风险影响分析" |
| "像给同事讲" | "以专业视角阐述" |
| "这东西干嘛的" | "项目概述" / "业务背景" |

**结构规范：**
- 章节使用中文数字编号（一、二、三...），子节用 1.1、1.2 格式
- 业务概述采用"业务背景 -> 解决方案 -> 数据上下游 -> 版本迭代"四段式结构
- 风险章节标注严重程度（红/黄/绿），每条统一为"问题描述 -> 影响分析 -> 改进建议"
- 技术解析中阐述设计意图，而非"为什么这么写"

禁止行为：
- ❌ 逐行复读代码
- ❌ 用表格替代讲解（表格只用于速查，不用于讲故事）
- ❌ 强套框架（没utils就不提utils，没模型就不提模型）
- ❌ 堆砌风险清单（只列真正会踩的Top5）

## When to Use

**适用：**
- 用户给出代码包路径，要求分析讲解
- 用户说"帮我看看这个项目"、"接手这个代码"、"读懂这个项目"

**不适用：**
- 单文件快速问答（直接读文件回答）
- Bug修复（用 systematic-debugging）
- 代码审查/PR Review（用 requesting-code-review）

## 执行策略

### 小型仓库（<15源文件）
直接 `read_file()` 逐个读取，`terminal()` 跑 grep/wc/find，人工完成分析。

### 中型仓库（15-50源文件）
先 `terminal()` 生成文件列表和LOC统计，核心文件逐个精读，辅助文件浏览摘要。

### 大型仓库（>50源文件）
用 `delegate_task` 并行分析不同模块，主 agent 汇总。

### Jupyter Notebook 重的仓库（DS/ML项目常见）

许多数据科学项目的核心逻辑不在 `.py` 文件里，而在 `.ipynb` notebook 中。notebook 本质是 JSON，`read_file()` 能读但输出很杂（混有 outputs、metadata、display data），且大 notebook 会截断。

**正确做法**：用 `execute_code` 跑 Python 解析 notebook，只提取 code cell 的源码：

```python
import json
with open(nb_path) as f:
    nb = json.load(f)
cells = []
for cell in nb.get('cells', []):
    if cell.get('cell_type') == 'code':
        src = ''.join(cell.get('source', []))
        if src.strip():
            cells.append(src)
```

**策略**：
- 先用 `execute_code` 列出所有 notebook 及其大小（`os.path.getsize`），按编号顺序判断执行流程
- 大 notebook（>500KB）通常含大量图表输出，代码本身可能只有几十KB。提取后对每个 cell 做 `len(cell) > MAXC` 截断，只看前 2000-2500 字符
- 关注编号最大的 dev 目录（如 `dev003/` > `dev002/` > `dev001/`），旧版通常只看差异不看全量
- notebook 里的注释（`# NOTE`、`# TODO`）比代码本身更能揭示设计意图和已知问题，重点提取

**陷阱**：
- 不要用 `read_file()` 直接读 .ipynb——JSON 结构会让行号标注失去意义，且 outputs 会淹没代码
- 多个 notebook 的编号（01、02、03...）通常代表执行顺序，按序读能快速理解管线
- 同名 notebook 在不同 dev 目录下可能有不同的采样策略和参数，不要假设一致

---

## 分析流程（7阶段，按顺序执行）

### 阶段1：业务与需求定位

**这是整个文档最重要的部分，占最终输出的40%。**

目标：让一个不熟悉该项目的人看完也能理解其业务定位与技术架构。

必须输出：
1. **业务背景**（3-5段正式书面语，非表格）：
   - 这个项目解决什么业务问题
   - 谁是上游（数据从哪来），谁是下游（结果给谁）
   - 用一个生活化的类比让新人秒懂
   - 这个项目和兄弟项目/上下游项目的关系

2. **核心业务规则**（精简表格，只列硬性规则）：
   - 样本筛选条件、时间窗口定义、渠道分类、成功标准等
   - 每条规则一行，标注 `文件:行号`
   - 宁可少列，不要淹没重点

3. **调度规则**（2-3句话）：
   - 什么时候跑、谁触发、失败了通知谁

> **写作要求**：这一阶段的文字量应该超过技术阶段的总和。如果接手者仅看这一段就能向管理层汇报"这个项目的业务定位"，即合格。

### 阶段2：代码地图

目标：用5分钟让新人知道"哪个文件干什么"。

必须输出：
1. **目录树**（带标注，简洁）：
   ```
   项目根/
   ├── src/main.py        ← 入口，两个命令
   ├── src/constants.py   ← 配置中心
   └── sql/xxx.sql        ← 核心取数逻辑
   ```

2. **每个文件的角色**（一句话说明，不展开细节）：
   - `main.py`：总调度室，管着两个任务的启动
   - `constants.py`：配置中心，改参数改这里
   - 形式：「文件名」+ 角色 + 一句话说明

3. **文件间的调用关系**（2-3句话，不画大图）：
   - 谁调用谁、数据怎么流、入口在哪

> **禁止**：展开文件内部逻辑——那是阶段4的工作。此处仅说明各文件职责。

### 阶段3：执行流程

目标：以清晰的专业语言阐述"代码从启动到完成的完整执行路径"。

必须输出：
1. **主流程叙述**（5-8段正式书面语，非流程图）：
   - 从"触发"开始，逐步阐述数据流向、各步骤处理内容及最终输出位置
   - 以专业视角描述"该任务每日执行时的步骤序列"

2. **如果有多条链路**，每条用2-3句话讲清楚：
   - 离线训练 vs 线上推理 vs 实验脚本
   - 如果只有一条链路，就明说"本项目只有一条链路"

3. **关键分支点**（如果有的话）：
   - 哪里有if/else、什么条件走哪条路

> **禁止**：画超过10个框的ASCII流程图。如果流程复杂，用缩进列表代替。简单的流程用3句话讲完。

### 阶段4：核心代码讲解

目标：讲清楚"最核心的代码在做什么"，不是"每个文件都讲一遍"。

**自适应分层**：根据项目实际情况选择讲哪些层，没有的层直接跳过：
- 有 utils → 讲通用工具函数做了什么
- 有数据/特征处理 → 讲筛选规则、标签构造、衍生字段
- 有模型 → 讲选型、参数、评估指标
- 有调度/业务规则 → 讲硬编码阈值和"改XX改哪里"

每个要讲的文件/模块：
1. **这个文件的核心职责**（一句话）
2. **关键逻辑怎么实现的**（2-3段散文，提取设计意图，不逐行复读）
3. **关键参数/阈值**（如果有，标注 `文件:行号`）

> **核心纪律**：
> - 只讲最重要的2-3个文件，其余一句话带过
> - 如果SQL有多个CTE层，讲清楚每层"做了什么"和"为什么这么设计"，不贴SQL原文
> - 讲完每个关键逻辑后说明"设计意图"（而非"为什么这么写"）

### 阶段5：环境与依赖

目标：让新人知道"跑这个需要什么"。

必须输出：
1. **运行环境**（2-3句话）：Python版本、base image、内部库
2. **必须的配置/密钥**（精简表格）：
   - 环境变量名 + 用途 + 谁设置的
3. **外部依赖**（散文，按重要程度排序）：
   - 依赖了哪些数仓表、API、远程仓库
   - 哪些是"看不见的依赖"（不在代码里但必须有的权限/资源）
4. **本地复现**（3-5步，真实的命令）

> **禁止**：列出所有表的所有字段。只列"没有就跑不起来"的依赖。

### 阶段6：风险与坑点

目标：让接手者了解"何处可能存在问题"。

**只列 Top 5**，按严重程度排序。每个风险：
1. **一句话描述问题**（加粗）
2. 2-3句话分析"影响"与"后果"
3. 标注 `文件:行号`
4. 如有应对建议，一句话给出

严重等级标注：红 高（会出错/数据不准）/ 黄 中（需注意）/ 绿 低（知道就好）

> **禁止**：列超过5个风险。如果确实存在20个风险，选取最致命的5个做透彻分析，优于列举20个导致读者失去耐心。

### 阶段7：接手者行动指南

目标：为接手者提供一份可执行的操作路线。

必须输出：
1. **阅读路线**（带时间的步骤列表）：
   ```
   第1步 (5分钟): 看什么文件，看什么
   第2步 (10分钟): 看什么文件，重点看什么
   ...
   ```
2. **改XX改哪里**（表格，新人最常查的）：
   | 需求 | 改哪里 |
   |------|--------|
3. **溯源指令**（2-3条最常用的git/grep命令）

---

## 输出格式规范

### 双文件输出

1. **HANDOVER.md** — 完整讲解文档（目标10-15KB，新人花15分钟通读）
2. **QUICKSTART.md** — 极简上手清单（目标2-3KB，新人5分钟读完）

### HANDOVER.md 写作要求

- **叙述优先**：以正式书面语叙述，表格只用于"查表"场景（业务规则速查、修改指引、环境变量列表）
- **分层但不死板**：7个阶段用 `---` 分隔，阶段4按项目实际情况跳过不存在的层
- **文件:行号**：所有提到的代码逻辑、配置项、风险点，必须标注
- **控制长度**：目标10-15KB。如超过20KB，精简技术细节，保留业务理解
- **语气**：专业、正式、客观，以技术文档标准撰写
- **默认中文**，需英文可告知

### HANDOVER.md 结构

```markdown
# {项目名} 交接文档

> 生成: {日期} | {LOC}行/{文件数}文件 | 分支: {branch}

## 一、项目概述

### 1.1 业务背景
（3-5段正式书面语：业务问题、解决方案、数据上下游、版本迭代。
接手者看完此段应能向管理层汇报项目业务定位。）

### 1.2 解决方案概述
（以专业语言描述技术方案与核心设计）

## 二、核心业务规则

| 规则 | 说明 | 位置 |
|------|------|------|
（只列硬性规则，每条一行）

## 三、代码结构

（目录树 + 每个文件一行角色说明 + 模块间依赖关系2-3句话）

## 四、执行流程

（5-8段正式书面语阐述主流程，以专业视角描述执行步骤序列）

## 五、核心代码解析

（只讲最重要的2-3个文件。每个文件：职责一句话 + 关键逻辑2-3段 + 设计意图）
（没utils就不提utils，没模型就不提模型）

## 六、运行环境与依赖

- 运行环境（2-3句话）
- 必要的配置（精简表格）
- 外部数据依赖（按重要程度排序）
- 本地复现步骤（3-5步）

## 七、风险与注意事项（Top 5）

1. **风险描述**
   影响分析 + 后果说明 + `文件:行号`
（只列5个，按严重程度排序，红/黄/绿标注）

## 八、接手者行动指南

- 阅读路线（带时间）
- 改XX改哪里（表格）
- 溯源指令（2-3条）
```

### QUICKSTART.md 写作要求

- **目标2-3KB**，5分钟通读
- 不是HANDOVER的缩略版，而是"首日操作指南"
- 以正式书面语撰写，回答4个问题：项目用途？优先阅读什么？如何运行？何处有风险？

```markdown
# {项目名} 快速上手

## 项目概述
（一段话概述）

## 优先阅读文件
1. {文件} - {优先原因}
2. {文件} - {原因}
3. {文件} - {原因}

## 运行步骤
（3-5条命令，可直接复制执行）

## 修改指引
| 需求 | 修改位置 |

## 主要风险（Top 3）
1. **{风险}** - {影响说明}
2. **{风险}** - {影响说明}
3. **{风险}** - {影响说明}
```

---

## 参考文件

- `references/anti-patterns.md` — 基于真实用户反馈的6个反模式，每个含❌错误做法 vs ✅正确做法的对比。生成交接文档前务必过一遍。

## 常见陷阱

1. **业务讲解太薄** - 这是最大的问题。一段话加一个表格就跳到技术细节，接手者尚未理解业务就被技术细节淹没。阶段1的正式书面语叙述必须占全文40%以上。

2. **用表格替代讲解** - 表格适合"查表"，不适合"理解"。业务逻辑、执行流程、核心代码设计意图，必须用正式书面语叙述。表格只用于：业务规则速查、环境变量列表、修改指引。

3. **强制套4层框架** - 没utils就不提utils，没模型就不提模型。阶段4根据项目实际内容选择讲什么，不硬填框架。

4. **风险列20条** - 无实际参考价值。只选取最致命的5个做透彻分析：问题描述、影响分析、后果说明、改进建议。

5. **流程图画满屏** - 超过10个框的ASCII图说明缺乏叙述能力。以正式书面语加缩进列表代替。

6. **逐行复读代码** - 代码已在文件中，无需重新打印。提取设计意图与核心逻辑，说明"设计意图"。

7. **文档太长** - 超过20KB的文档无人通读。精简技术细节，保留业务理解。目标15分钟通读。

8. **QUICKSTART只是缩略版** - QUICKSTART不是HANDOVER的摘要，而是"首日操作指南"。回答4个问题：项目用途？优先阅读什么？如何运行？何处有风险？

9. **口语化表述** - 使用"打个比方""蒙混过关""开后门"等口语化词汇降低文档专业性。所有输出必须使用正式书面语。

## 验证清单

- [ ] 阶段1业务讲解是否占全文40%以上？接手者看完能向管理层汇报项目定位吗？
- [ ] 业务讲解是否以正式书面语撰写？（无口语化表述）
- [ ] 阶段4是否跳过了项目不存在的层（无utils就不提utils）？
- [ ] 所有代码逻辑是否标注了 `文件:行号`？
- [ ] 风险是否只列了Top 5？每个是否讲清了"影响分析"？
- [ ] HANDOVER.md 是否在15-20KB以内？
- [ ] QUICKSTART.md 是否在2-3KB以内？
- [ ] 流程描述是否用正式书面语而非满屏ASCII图？
- [ ] 语气是否专业正式，符合技术文档标准？
- [ ] 章节是否使用中文数字编号（一、二、三...）？