项目掌握：从读懂代码到能够安全交付¶
“熟记代码”不是掌握项目。真正的掌握，是在不打开仓库时仍能解释系统如何工作，预测改动会影响什么，并在故障发生时知道从哪里验证和恢复。
这是一套学习与交付共用的框架。它适用于接手陌生仓库、做需求变更、排查线上问题，以及训练系统设计能力。
掌握的定义¶
掌握一个项目，不是记住文件名、函数名或每一行实现，而是能做到：
- 解释系统解决的问题和主要组成。
- 重建关键请求、事件和数据的流动路径。
- 说明各层依赖的语言、框架和基础设施原语（primitive）。
- 区分代码事实、合理推断和未经证实的设计意图。
- 预测重试、并发、超时、重启和依赖失效时的行为。
- 设计并实施改动，同时保护已有不变量。
- 关闭仓库后，画出简化架构并解释主要取舍。
可以把目标写成：
其中，原语是构成系统的积木；链路是这些积木如何协作；不变量定义何时仍然正确。后面的设计意图、失败模式、修改和重建，检验的是能否真正拥有这个系统的心智模型。
六张认知地图¶
1. Primitive Map：原语地图¶
列出决定系统行为的基本构件，而不是罗列所有 API。
| 类别 | 例子 | 需要回答的问题 |
|---|---|---|
| 语言 | goroutine、channel、transaction、mutex | 语义、生命周期、约束是什么？ |
| 框架与库 | React hook、Spring transaction、ORM unit of work | 框架替你做了什么，何时会失效？ |
| 基础设施 | RPC、队列、缓存、lease、重试 | 可靠性、顺序、超时和一致性由谁保证？ |
| 项目抽象 | service、aggregate、job、adapter | 谁拥有状态，谁可以修改它？ |
对每一个关键原语，记录它在哪里被使用、误解它会破坏什么、以及需要维持的约束。
2. Link Map：链路地图¶
为重要操作画出从入口到结果的完整路径：
同时标出调用链、数据变形、分支、异步边界、进程边界、存储边界和状态所有权。优先追踪三到五条代表性路径：最重要、最复杂、最容易失败、最异步、最有状态的操作。
3. Invariant Map：不变量地图¶
不变量是系统无论处于什么中间状态都必须维持的事实。例如：
- 同一笔扣款不能被重复执行。
- 旧服务版本与新服务版本能在发布期间共存。
- 重试不能制造额外副作用，或者操作必须可幂等。
- 状态转换只能从合法前置状态发生。
- 缓存不能比它代表的所有权租约存活更久。
每项不变量都应有五个字段：陈述、建立位置、依赖位置、破坏方式、可观测症状。如果还没找到不变量，就不能因为测试通过而判断变更风险低。
4. Why Map：设计意图地图¶
对每个非平凡设计提出同一组问题：为什么选它？替代方案是什么？它换来了什么，又牺牲了什么？是刻意设计，还是历史遗留？
必须把结论分层：
| 层级 | 含义 |
|---|---|
| FACT | 代码、测试、文档明确证明的事实 |
| INFERENCE | 由证据可合理推出的判断 |
| UNKNOWN | 证据不足，不能当作设计意图 |
没有证据时，“不知道”比编造一个漂亮的架构理由更有价值。
5. Failure Map：失败地图¶
对关键子系统，从正常链路反向推演失败：
至少检查超时、重试、重复请求或事件、部分失败、崩溃窗口、陈旧缓存、依赖不可用、Schema 不匹配、混合版本、错误配置和重启后的恢复。每个场景都要能回答：发生后留下什么状态？怎么发现？从哪个信号开始查？如何恢复？
6. Modification Map：修改地图¶
在写代码前，选择一个真实改动并预测其爆炸半径：受影响的模块、API、状态、存储、异步链路、不变量、测试、性能和新增失败模式。
常见练习包括新增 API、变更 Schema、引入缓存、增加并发、修改状态转换、替换依赖或增加事件类型。实现后，把预测与现实对比；两者之间的差距就是最有价值的学习信号。
学习与交付的循环¶
不要从头到尾线性阅读仓库。用下面的顺序建立模型：
- 问题：用一到三句话说明系统为谁解决什么问题。
- 骨架：找入口、主要模块、数据结构、外部依赖、持久化、异步系统和配置。
- 关键链路：端到端追踪三到五个代表性操作。
- 不变量与 Why：写出正确性条件，并明确证据等级。
- 失败优先：假设依赖消失、操作执行两次、并发执行、执行到一半、超时或重启。
- 预测后修改：先预测影响范围，再做小改动，并比较实际结果。
- 闭卷重建：关掉仓库，重画架构、状态、链路、不变量和风险，再打开代码校正。
它可以浓缩成一条固定循环：
这里的 Break 是受控地推演或测试失败条件，并不意味着在生产环境制造事故。
用交付视角检验掌握程度¶
项目学习的终点是能够安全地改变和运行系统。一个生产相关的改动，应至少形成下面这份简短交付记录：
| 维度 | 需要写清的内容 |
|---|---|
| System | 触及的入口、模块、数据、调用方和下游依赖 |
| Invariants | 发布前、中、后都必须保持为真的条件 |
| Risks | 三到五个最重要的失败模式和可见信号 |
| Plan | 变更顺序、兼容策略、验证、停止条件和回滚 |
| Execution | 实际改了什么、为何这样改 |
| Verification | 已观察到的证据；与未验证的推断分开 |
| Delivery record | 残余风险、恢复路径和本次新获得的系统知识 |
对于数据库、API、事件和依赖升级，尤其要检查混合版本、重试幂等性、部分发布、数据迁移以及回滚无法撤销的数据副作用。CI 通过只证明部分代码层面的正确性，不能自动证明目标环境中的行为正确。
主动回忆与掌握度测试¶
反复重读代码很容易产生“熟悉感”，却未必形成可预测的模型。更有效的方式是先回答问题，再打开代码验证：
- 请求或事件从哪里产生？下一跳是什么？谁拥有状态？
- 哪个组件能修改它？缺失、超时或重复时会怎样？
- 哪个机制保证顺序、幂等性或一致性？
- 为什么这里要异步？为什么需要缓存或队列？
- 某个症状出现时，第一处该看什么信号，为什么？
闭卷完成下面的问题，可作为阶段测试：
- 系统解决什么问题，主要组件是什么？
- 三条最重要的执行路径和数据变化分别是什么？
- 关键状态归谁所有，哪些不变量必须维持？
- 重要架构选择的证据和取舍是什么？
- 重试、并发、依赖失败和重启时会发生什么？
- 新增一个功能会改动哪些边界，又可能破坏什么？
- 能否从内存写出一个简化版本，并解释保留和删除了什么？
答不上来时，不要笼统地“再读一遍”。定位缺的是哪张地图：Primitive、Link、Invariant、Why、Failure、Modification 或 Reconstruction，然后只补那个维度。
掌握等级¶
| 等级 | 能力 |
|---|---|
| 0 · Exposure | 认识文件和概念 |
| 1 · Navigation | 能定位相关代码 |
| 2 · Explanation | 能解释重要代码路径 |
| 3 · Causal understanding | 能解释系统为什么如此行为 |
| 4 · Modification | 能在保持不变量的前提下修改 |
| 5 · Diagnosis | 能从症状推测可能原因 |
| 6 · Reconstruction | 能从记忆重建简化系统 |
| 7 · Transfer | 能将背后的架构原则迁移到新系统 |
目标不是“我以前见过这段代码”，而是“我能在运行前预测它会做什么，并能预测改动后会发生什么”。
反模式¶
- 记住文件名不等于理解架构。
- 认识代码不等于能重建它。
- 背 API 不等于理解原语。
- 只追 happy path 不等于理解系统。
- 知道代码做什么不等于知道为什么存在。
- 测试通过不等于已证明不变量或生产安全。
来源说明¶
本文由用户提供的 ChatGPT 临时对话摘录整理，并结合本地 delivery-coach Skill 的交付检查框架形成。它是一套学习与工程推理方法，不描述任何具体项目的真实架构、生产状态或运维能力；把它应用到某个仓库时，应以该仓库的代码、配置、测试、部署资料和运行证据为准。