Learn From Repo

---
name: learn-from-repo
description: 用于深度理解研究型代码仓库的方法论 skill。当用户想要学习一个新的 ML/AI repo、理解其实现与论文的对应关系、或为后续修改做准备时使用。结合对话式学习风格，逐组件拆解模型实现。
---

# Learn From Repo & Paper

用于深度阅读研究型 repo 的完整方法论，核心是**代码-论文双向对应**，目标是理解到"可以修改"的程度。

---

## 默认学习偏好（可按需调整）

- **对话式推进**：不要一次输出所有内容，每个组件讲完后停下来，等用户确认或提问
- **零基础假设**：不跳过前置知识，包括引用论文中涉及的前序工作
- **Paper-Code 对应**：每个模块标注对应的论文章节/公式
- **穿插方法论**：在讲具体代码时，穿插"如何读 repo"的通用技巧
- **格式偏好**：表格、ASCII 图、代码块，结构清晰
- **代码定位**：讲解每个概念时，明确标注对应的文件路径和行号（如 `model.py:48-80`），让用户能直接跳转查看
- **每节结尾**：提示"下一步可以看什么"，引导对话继续

> 如有不同偏好，在激活 skill 时告知即可（如"不用对话式，直接给完整讲解"）。

---

## Phase 0：激活前准备

在开始讲解前，先完成以下两项：

### 0a. 用 claude-paper:study 处理论文

如果用户提供了论文 PDF 或 arXiv 链接，先调用：
  /claude-paper:study <paper_url_or_path>

这会生成结构化学习材料，后续讲解可引用。

### 0b. 快速扫描 repo 骨架

```bash
# 查看文件树（2层）
find . -maxdepth 2 -not -path '*/.git/*' | sort | head -60

# 统计核心文件大小（找"重心"文件）
wc -l **/*.py 2>/dev/null | sort -rn | head -20

# 看 git log，了解开发脉络
git log --oneline -20
```

目的：30秒内找到核心文件，不要盲目遍历。

---

## Phase 1：四步阅读法（每个 Repo 通用）

```
Step 1: 看骨架（文件树）
         问：核心文件是哪个？依赖什么外部库？
         ↓
Step 2: 找入口（forward / main / __call__）
         问：数据从哪里进来，从哪里出去？
         ↓
Step 3: 识别核心数据结构
         问：数据长什么样？有哪些字段？如何在模块间传递？
         ↓
Step 4: 逐组件拆解
         问：每个模块的输入、处理、输出是什么？对应论文哪里？
```

核心原则：先看"数据流"，再看"算法"。搞清楚数据格式，代码自然就懂了。

---

## Phase 2：逐组件讲解模板

对每个核心组件，按以下结构讲解：

1. 动机（为什么需要这个组件？解决什么问题？）
   → 对应论文：Sec X.X / Figure X

2. 接口（输入输出是什么？）
   → 输入：shape, dtype, 语义
   → 输出：shape, dtype, 语义

3. 实现细节（代码逐行解读）
   → 关键行：file.py:L123-L145
   → 重要变量命名含义

4. 设计精妙处 / 易错点

5. 与其他组件的关系

讲解顺序建议（ML repo）：
  数据结构 → 序列化/预处理 → 嵌入层 → 核心注意力/算子 → 层次结构 → 整体组装

---

## Phase 3：Paper-Code 对应检查表

| 检查项 | 说明 |
|--------|------|
| 论文公式 → 代码行 | 每个关键公式能找到对应的实现 |
| 论文 Figure → 代码结构 | 架构图能映射到 __init__ 中的模块 |
| 论文 Table（消融）→ 超参 | 消融实验对应 __init__ 参数 |
| 论文贡献 → 代码创新点 | 每条 contribution 都有对应实现 |

---

## Phase 4：为"可修改"做准备

关键问题清单：
  □ 如何替换核心算子（attention / convolution）？
  □ 如何添加新的特征输入？（找 Embedding 层）
  □ 如何修改层次结构？（找 depth/stride 参数）
  □ 如何添加新的损失函数？（找 forward 输出）
  □ 数据预处理在哪里？
  □ 哪些参数是超参，哪些是结构参数？

绘制"修改地图"：
  对每个想修改的地方，记录文件路径+行号、影响的其他组件、需要同步修改的地方

---

## Phase 5：对话式 Deep Dive

每个组件讲完后提问用户：
  "这个组件还有什么不清楚的？常见深挖方向：
   A. 数学推导（为什么这样设计）
   B. 与其他方法对比
   C. 实现细节（某几行代码含义）
   D. 修改思路（如果我要改 X，应该动哪里）"

---

## 通用读代码技巧

| 技巧 | 场景 |
|------|------|
| 从 forward() 开始，顺数据流走 | 任何 nn.Module |
| 先看 __init__ 参数，了解设计空间 | 理解超参含义 |
| 用 wc -l 找"重心"文件 | 快速定位核心代码 |
| 看 import，了解依赖关系 | 判断外部依赖的作用 |
| 搜索 assert，找隐含约束 | 理解数据格式要求 |
| 搜索 # TODO，找已知缺陷 | 了解作者的遗留问题 |
| 看 git log，了解演化脉络 | 理解为什么这样设计 |
| 消融实验 Table → 找对应参数 | 从论文反推代码 |