面试文档构建规范（V4）#

# M{N} · {模块名}

> **简历 Bullet Point**: {对应的简历原文，M0/M6-M9 无 bullet point 的写一句话定位}

---

## 开场钩子

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

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

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

钩子来源不限于线上事故——V4 新增模块（M3 Runbook、M6 Incident 状态机等）如果没有事故历史，
可以从"V3 遗留问题驱动 V4 重设计"或"设计过程中的反直觉发现"来构造，同样有画面感。

---

## 一、模块运作流程

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

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

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

### 1.4 数据流 trace（具体输入走一遍）
拿一条具体的输入，端到端走一遍本模块涉及的流程。各模块自选合适的例子：
- M1-M5：一条告警（如 `MySQL replica lag > 10s on db-slave-02`）
- M7(RAG)：一条检索 query
- M8(队列)：一条任务消息从入队到消费
- M9(Benchmark)：一条测试用例从构造到出分

每一步标清：
- **输入**：这一步收到什么数据（字段级）
- **处理**：做了什么变换
- **输出**：产出什么交给下一步
让读者看完能回答"一条真实请求经过这个模块时，数据长什么样、怎么变的"。

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

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

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

---

## 二、踩坑实录

每个坑按统一格式：

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

至少 3 个坑。

#### 什么算踩坑

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

- LangGraph 的 recursion_limit 是 super-step 数不是工具调用数，导致 Tier 3 深度调查提前截断
- pgvector 的 IVFFlat 索引在小数据量下召回率低于暴力搜索，冷启动阶段反而更慢
- 百炼调 DeepSeek-V4 的真实限流瓶颈是 TPM 不是 RPM，本地令牌桶参数全配错
- Alertmanager 的 group_wait 语义与自建聚合窗口的交互导致双重延迟

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

---

## 三、量化评估（仅可量化的模块需要）

如果本模块的效果可以量化验证，按以下结构写清楚：

### 3.1 评估数据集构建
- **数据来源**：从哪里来的（生产日志采样 / 手工构造 / 开源数据集 / 历史 Incident 回放）
- **规模与分布**：多少条、覆盖哪些场景、正负例比例
- **标注方式**：谁标的、标注标准是什么、有没有交叉验证

### 3.2 评估方法
- **怎么跑**：用什么脚本/工具、跑在什么环境
- **对照组**：和什么 baseline 对比（关掉某层 / 替换某组件 / 纯人工）
- **可复现性**：别人拿到代码能不能一键跑出同样结果

### 3.3 结果与解读
- **核心指标**：列出关键数字（准确率 / 召回率 / 延迟 / 降噪率 / token 成本等）
- **数据来源标注**：每个数字标明来源（`scripts/eval_xxx.py` 输出 / 压测报告 / 日志统计）
- **局限性**：这组数据能说明什么、不能说明什么

不是每个模块都能量化——纯机制 / 纯治理类模块（如 M4 安全治理、M6 状态机）可以跳过此板块，
或改为定性验证（如红队测试通过率、非法迁移拒绝率）。
M9（Benchmark 方法论）跳过此板块——整篇 M9 就是量化评估的展开，不需要再套一层 meta-evaluation。

---

## 四、面试问答

### 基础题（必问级）

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

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

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

### 进阶题（区分度）

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

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

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

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

---

## 五、前沿概念与延伸

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

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

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

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

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

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

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

---

## 六、诚实边界

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