---
name: code-walkthrough
version: 1.0.0
last_updated: 2026-04-08
repository: https://github.com/312362115/claude
description: >
  代码导读技能：帮助快速理解不熟悉的项目或模块，建立心智模型。
  从全局架构到核心流程再到关键设计决策，分层递进地梳理代码。
  不是简单地读文件列目录，而是提炼出"这段代码在做什么、为什么这么做、和其他部分怎么连接"。
  触发词：帮我梳理一下、这块代码怎么运作的、导读、接手项目、看看这个模块、代码走读、walkthrough。
  触发场景：接手新项目、进入不熟悉的模块、重构前理解现状、Code Review 需要理解上下文。
  即使用户没有说"导读"，只要意图是"理解一段不熟悉的代码"，都应触发此技能。
---

# 代码导读（Code Walkthrough）

> 读代码和读书一样——先看目录了解结构，再看核心章节理解逻辑，最后看细节。
> 不是逐行翻译代码，而是帮读者建立"这个系统怎么运转"的心智模型。

---

## 第一步：确定导读范围和深度

```
导读请求
  │
  ├─ 整个项目？
  │   └─ 全局导读：项目架构 → 模块职责 → 核心流程 → 关键决策
  │
  ├─ 某个模块/目录？
  │   └─ 模块导读：模块职责 → 内部结构 → 核心逻辑 → 对外接口
  │
  └─ 某个具体功能/流程？
      └─ 流程导读：入口 → 数据流 → 关键分支 → 输出
```

用 `AskUserQuestion` 确认：
- **导读目标**：看什么？整个项目、某个模块、还是某个功能？
- **导读目的**：为什么要看？接手维护、准备改动、还是纯了解？
- **已有认知**：对这块代码已经了解多少？（避免输出用户已知的信息）

---

## 第二步：全局扫描

不管导读什么范围，先花 2-3 个工具调用建立全局感知：

### 2.1 项目全局（如果是项目/模块导读）

```
1. 读项目根目录结构（ls / Glob）
2. 读配置文件（package.json / pyproject.toml / tsconfig.json）
3. 读 README / CLAUDE.md / docs/（如果有）
4. 检查 git log 最近 20 条提交（了解活跃区域）
```

提取关键信息：
- **技术栈**：语言、框架、主要依赖
- **项目类型**：前端应用 / 后端服务 / 全栈 / CLI 工具 / 库
- **目录组织**：按功能分还是按类型分？有没有约定

### 2.2 目标区域

定位到导读目标后，了解：
- **入口文件**：这个模块/功能从哪里开始？
- **文件清单**：涉及哪些文件？各自大概多少行？
- **依赖关系**：依赖了什么外部模块？被谁依赖？

---

## 第三步：分层梳理

按照 **架构 → 流程 → 细节** 的顺序递进，每一层解决不同的问题。

### Layer 1：架构层 — "系统由什么组成"

回答：**这个系统/模块的整体结构是什么？各部分各司什么职？**

输出格式：
```markdown
## 架构概览

### 模块组成
- `src/api/` — API 路由层，接收请求、参数校验、调用 service
- `src/services/` — 业务逻辑层，核心计算和编排
- `src/models/` — 数据模型，定义实体和数据库交互
- `src/utils/` — 工具函数，无业务语义

### 依赖关系
api → services → models
         ↓
       utils

### 数据流向
请求 → 路由 → 中间件（认证/校验）→ service → model → 数据库
                                                    ↓
响应 ← 路由 ← ─────────────────────── service ← model
```

### Layer 2：流程层 — "核心功能怎么运转"

回答：**一个请求/操作从头到尾经过了哪些步骤？**

选择 1-3 个**最核心的流程**做详细走读：

```markdown
## 核心流程

### 流程 1：用户登录
1. `POST /api/login` → `src/api/auth.ts:handleLogin()`
   - 参数校验：email + password
2. → `src/services/auth.ts:login()`
   - 查询用户：`UserModel.findByEmail(email)`
   - 验证密码：`bcrypt.compare(password, user.hash)`
   - 生成 token：`jwt.sign({ userId: user.id }, secret, { expiresIn: '7d' })`
3. → 返回：`{ token, user: { id, name, email } }`

关键点：
- token 过期时间 7 天，写死在代码里（可能需要改为配置）
- 密码验证用 bcrypt，安全
- 没有登录失败次数限制
```

### Layer 3：细节层 — "关键设计决策和隐含知识"

回答：**为什么这么写？有什么不明显的约定或陷阱？**

```markdown
## 关键设计决策

### 决策 1：为什么用 Redis 做 session 而不是 JWT 无状态？
- 见 `docs/specs/2026-03-23-auth-session-design.md`（如果有文档）
- 或从代码推断：支持主动注销（删 Redis key 即失效）

### 决策 2：为什么 UserModel 同时用了 ORM 和 raw SQL？
- ORM 用于常规 CRUD
- raw SQL 用于复杂聚合查询（`src/models/user.ts:237` 的注释说明了原因）

## 隐含约定
- 所有 API 响应统一包装为 `{ code, data, message }` 格式（见 `src/middleware/response.ts`）
- 错误处理走全局 error handler（`src/middleware/error.ts`），不需要每个路由单独 catch
- 环境变量从 `.env` 加载，必填项在 `src/config.ts` 中校验

## 注意事项 / 潜在风险
- `src/services/order.ts:89` — 库存扣减没有并发保护
- `src/utils/cache.ts` — 缓存 key 没有 namespace，多服务共用可能冲突
```

---

## 第四步：输出导读文档

### 输出格式

根据导读深度选择输出方式：

| 深度 | 输出 |
|------|------|
| 快速了解（聊天中回答） | 直接在对话中输出，不存文件 |
| 完整导读（需要沉淀） | 写入 `docs/guides/<模块名>-walkthrough.md` |

### 完整导读文档结构

```markdown
# 代码导读：<模块/项目名>

> 一句话概括这个模块/项目做什么

## 技术栈
- 语言/框架/主要依赖

## 架构概览
（Layer 1 的输出）

## 核心流程
（Layer 2 的输出，1-3 个关键流程）

## 关键设计决策
（Layer 3 的输出）

## 隐含约定
（不写在代码注释里但需要知道的规则）

## 注意事项
（潜在风险、技术债、容易踩的坑）

## 相关文档
- 指向 docs/ 下的相关 spec、plan、decision
```

---

## 导读准则

- **不逐行翻译**：读者是开发者，能读代码。导读要提炼的是"代码没直接告诉你的东西"——架构意图、设计理由、隐含约定
- **先宏观后微观**：先给全景地图，再放大关键区域。不要一上来就钻进某个函数
- **关注连接**：模块之间怎么交互？数据怎么流转？比单个模块内部逻辑更重要
- **标注位置**：提到具体逻辑时标注 `文件:行号`，方便读者跳转查看
- **诚实说不知道**：如果某个设计决策从代码看不出原因，说"从代码推断可能是因为 X，但不确定"，不要编理由
- **按读者水平调整**：用户说"我是 Go 高手但不懂 React"，就用 Go 的类比解释 React 的概念

---

## 与其他 skill 的关系

```
接手新项目 → code-walkthrough（建立心智模型）
                ↓
准备改动 → refactoring（影响分析可以复用导读的架构理解）
                ↓
改动前评估 → dependency-map（导读关注"是什么"，依赖分析关注"改了影响谁"）
```

**code-walkthrough vs dependency-map 的区别**：
- code-walkthrough：理解代码，回答"这是什么、怎么运转、为什么这么写"
- dependency-map：评估影响，回答"改这里会动到哪里"
- 通常先 walkthrough 理解，再 dependency-map 评估影响