面试文档构建规范#

# M{N} · {模块名}

> **简历 Bullet Point**: 一句话，面试官扫简历时抓眼球用

---

## 开场钩子

### 场景
用一个真实开发中遇到的事故/意外/反直觉发现引入这个模块。结构：
**出了什么事**（具体、有画面感）→ **发现了什么问题**（根因分析）→ **引出这个模块要解决什么**。
让面试官有代入感，自然追问。不要编故事——从真实 git 历史和开发过程中提取。

### 面试官切入
> "你提到了 {钩子里的关键词}——能展开讲讲吗？"

开场钩子的目的是**掌握面试节奏**：你用故事引出一个关键词，面试官大概率沿这个词追问，
正好接到你准备好的"模块运作流程"和"面试问答"里。

---

## 一、模块运作流程

### 1.1 一句话定位
这个模块解决什么问题、为什么需要它（不超过 3 句）

### 1.2 全景流程图（文字版）
用文字描述端到端流程，标清入口 → 中间节点 → 出口

### 1.3 分步详解
按流程顺序，每步讲清：
- **做什么**：这一步的输入输出
- **怎么做**：核心逻辑（伪代码级，不贴大段源码）
- **为什么这么做**：设计决策的理由

### 1.4 数据流 trace（具体 query 走一遍）
拿一个具体的用户 query（如"旅行三件套，预算 300"），端到端走一遍本模块涉及的流程。
每一步标清：
- **输入**：这一步收到什么数据（字段级）
- **处理**：做了什么变换
- **输出**：产出什么交给下一步
让读者看完能回答"一条真实请求经过这个模块时，数据长什么样、怎么变的"。

### 1.5 技术选型决策表（仅涉及选型的模块需要）
本模块用到的关键技术组件，每个列出：
- **选了什么**
- **备选方案**（至少 1 个）
- **为什么选它**（核心理由，1-2 句）
- **什么情况下换**（边界条件）

不是每个模块都有选型决策——如果本模块没有技术选型（纯逻辑 / 纯机制），跳过此节。
M0（项目全景）必须有一个**汇总级**选型表覆盖全局关键组件。

### 1.6 口述脚本
面试时怎么用 1-2 分钟讲清这个模块。
标出节奏、转折、留钩子引导追问的位置。

---

## 二、踩坑实录

每个坑按统一格式：

### 坑 {N}：{一句话标题}
- **现象**：出了什么问题
- **根因**：为什么会这样
- **修法**：怎么修的
- **教训**：抽象成通用工程原则

至少 3 个坑。

#### 什么算踩坑

✅ **要的**——工程实践中的认知陷阱、设计决策的反直觉后果、技术选型的隐性代价、
依赖/环境/协议层面"看起来应该对但实际不对"的坑。例：

- 框架的某个参数语义与直觉不同（recursion_limit 是 super-step 数不是迭代数）
- 缓存协议的前缀精确匹配导致摘工具破坏命中率
- CJK 文本用英文 tokenizer 计数偏差 2-3 倍
- 纯在线推理无降级链，上游 502 时全链路挂

❌ **不要的**——代码层面的 bug（early-return 写错、变量拼错、忘了 await、条件判断反了）。
这些是代码错误，不是工程踩坑。

---

## 三、验收与量化

面试官追问"怎么证明你做的东西有效"时用这一节回答。分两种情况：

### 数据来源规则

**⚠️ 硬约束：量化数据从 `refdocs/` 和 `docs/milestones/` 的设计文档中取（代表设计目标与方法论），
不从 `data/eval/` 的真实跑分结果取。** 真实跑分变量未充分控制、数据质量不足以面试展示。
面试时用设计文档中的数据讲方法论和预期效果，不要拿真实跑分的裸数据当论据。

### 有独立量化指标的模块

列出核心指标 + 基线 → 改进数据 + 评测数据怎么来的。格式：

#### 核心指标
| 指标 | 含义 | 基线 | 改进后 | 变化 |
|------|------|------|--------|------|
| recall@20 | 前 20 召回命中率 | X | Y | +Z% |
| ... | ... | ... | ... | ... |

#### 评测数据怎么来的
- **数据集**：从哪来、多大规模、怎么构建（如"18 条手写种子 query 覆盖 13 个场景桶"）
- **Ground truth**：怎么标注 / 怎么定义"对"（如"人工标注相关商品集"或"P0 红线通过即算对"）
- **评测方法**：怎么跑、用什么框架（如"Rubrics as Rewards 三级评分 + judge 模型逐条打分"）

#### 基线 → 改进
改之前什么水平 → 做了什么改动 → 改之后什么水平。给出归因（涨分来自哪个改动）。

### 纯机制模块（无独立量化指标）

这类模块（如 fork 安全四层、阶段状态机、Harness Hook Pipeline）的效果靠两条路径验证：

1. **回归测试**：列出关键 test case 和覆盖的场景（如"递归 fork 被拦截""超时强制收尾"）
2. **端到端 Rubric 间接反映**：加了这个机制后，端到端评测的哪些指标变了
   （如"加漂移检测后 P0 通过率从 X 到 Y"）

诚实标注"无独立量化"——面试时说"这个模块的效果通过端到端评测间接验证，
没有单独的 A/B 数据"比编数据强一百倍。

---

## 四、面试问答

### 基础题（必问级）

#### Q1: {问题}
**答：** 结论先行 → 关键细节 → 代码级证据

> **追问 1：** {面试官大概率追问}
> **答：** ...

> **追问 2：** ...
> **答：** ...

### 进阶题（区分度）

#### Q{N}: {问题}
...

### 压力题（面试官挑战设计决策）

#### Q{N}: {问题}
...

每个模块至少 6 道题，含追问链，覆盖基础/进阶/压力三档。
回答风格：**结论先行 → 关键细节 → 生产经验**。

---

## 五、前沿概念与延伸

### 4.1 {概念/范式名}

**是什么**：一句话定义

**为什么要这么做**：这个概念要解决的核心问题

**这么做的理由**：相比其他方案的优势

**举例说明**：用本项目或业界案例具象化

**延伸问答**：
> 面试官："你还知道其他 {同类} 吗？什么情况下用哪个？"
> 答：对比 + 选型决策

每个模块至少 2 个前沿概念，紧扣该模块涉及的技术方向。
每个概念必须包含上述四项（为什么 / 理由 / 举例 / 延伸问答）。

---

## 六、诚实边界

这个模块没做什么、为什么没做、真实局限在哪里。
面试时被问"有什么不足"直接用这段。