Reading code is like reading a book—first look at the table of contents to understand the structure, then read the core chapters to understand the logic, and finally look at the details. It is not translating code line by line, but helping the reader build a mental model of "how this system operates."
Step 1: Determine the walkthrough scope and depth
导读请求
│
├─ 整个项目？
│ └─ 全局导读：项目架构 → 模块职责 → 核心流程 → 关键决策
│
├─ 某个模块/目录？
│ └─ 模块导读：模块职责 → 内部结构 → 核心逻辑 → 对外接口
│
└─ 某个具体功能/流程？
└─ 流程导读：入口 → 数据流 → 关键分支 → 输出
Use AskUserQuestion to confirm:
- Walkthrough target: What to look at? The entire project, a certain module, or a certain feature?
- Walkthrough purpose: Why look at it? Taking over maintenance, preparing to make changes, or just understanding it?
- Existing knowledge: How much is already known about this code? (Avoid outputting information the user already knows.)
Step 2: Global scan
Regardless of the walkthrough scope, first spend 2-3 tool calls to establish global awareness:
2.1 Project-wide (if it is a project/module walkthrough)
1. 读项目根目录结构（ls / Glob）
2. 读配置文件（package.json / pyproject.toml / tsconfig.json）
3. 读 README / CLAUDE.md / docs/（如果有）
4. 检查 git log 最近 20 条提交（了解活跃区域）
Extract key information:
- Tech stack: Language, framework, main dependencies
- Project type: Frontend application / backend service / full stack / CLI tool / library
- Directory organization: Is it organized by feature or by type? Are there conventions?
2.2 Target area
After locating the walkthrough target, understand:
- Entry file: Where does this module/feature start?
- File list: Which files are involved? Roughly how many lines does each have?
- Dependency relationships: What external modules does it depend on? Who depends on it?
Step 3: Layered organization
Proceed in the order of architecture → flow → details , with each layer solving a different problem.
Layer 1: Architecture layer — "What is the system composed of?"
Answer:What is the overall structure of this system/module? What is each part responsible for?
Output format:
## 架构概览
### 模块组成
- `src/api/` — API 路由层，接收请求、参数校验、调用 service
- `src/services/` — 业务逻辑层，核心计算和编排
- `src/models/` — 数据模型，定义实体和数据库交互
- `src/utils/` — 工具函数，无业务语义
### 依赖关系
api → services → models
↓
utils
### 数据流向
请求 → 路由 → 中间件（认证/校验）→ service → model → 数据库
↓
响应 ← 路由 ← ─────────────────────── service ← model
Layer 2: Flow layer — "How do the core features operate?"
Answer:What steps does a request/operation go through from start to finish?
Select 1-3most core flowsfor a detailed walkthrough:
## 核心流程
### 流程 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: Detail layer — "Key design decisions and implicit knowledge"
Answer:Why was it written this way? What non-obvious conventions or pitfalls are there?
## 关键设计决策
### 决策 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，多服务共用可能冲突
Step 4: Output the walkthrough document
Output format
Choose the output method according to the walkthrough depth:
| Depth | Output |
|---|---|
| Quick understanding (answer in chat) | Output directly in the conversation, do not save to a file |
| Full walkthrough (needs to be documented) | Write to docs/guides/<模块名>-walkthrough.md |
Full walkthrough document structure
# 代码导读：<模块/项目名>
> 一句话概括这个模块/项目做什么
## 技术栈
- 语言/框架/主要依赖
## 架构概览
（Layer 1 的输出）
## 核心流程
（Layer 2 的输出，1-3 个关键流程）
## 关键设计决策
（Layer 3 的输出）
## 隐含约定
（不写在代码注释里但需要知道的规则）
## 注意事项
（潜在风险、技术债、容易踩的坑）
## 相关文档
- 指向 docs/ 下的相关 spec、plan、decision
Walkthrough guidelines
- Do not translate line by line: The reader is a developer and can read code. What the walkthrough should distill is "what the code doesn't directly tell you" — architectural intent, design rationale, implicit conventions
- Macro before micro: Give the big-picture map first, then zoom into key areas. Don't dive into a single function right away
- Focus on connections: How do modules interact? How does data flow? This matters more than the internal logic of a single module
- Mark locations: When mentioning specific logic, mark
文件:行号, so readers can jump to view it - Honestly say you don't know: If the reason for a design decision can't be seen from the code, say "inferring from the code, it may be because of X, but I'm not sure" — don't make up reasons
- Adjust to the reader's level: If the user says "I'm a Go expert but don't understand React", use Go analogies to explain React concepts
Relationship with other skills
接手新项目 → code-walkthrough（建立心智模型）
↓
准备改动 → refactoring（影响分析可以复用导读的架构理解）
↓
改动前评估 → dependency-map（导读关注"是什么"，依赖分析关注"改了影响谁"）
The difference between code-walkthrough vs dependency-map：
- code-walkthrough: understand the code, answer "what is this, how does it work, why was it written this way"
- dependency-map: assess impact, answer "what will be affected if I change this"
- Usually do a walkthrough first to understand, then dependency-map to assess impact