1. context-mode 是什么，以及我为什么会写下这套东西
先交代一下背景。几个月前，我在维护一个接手不到两周的业务系统，代码量不大，但每次改一行逻辑都要把调用链从头捋一遍。不是代码写得烂，而是注释里只写了“做了什么”，完全没写“为什么这样做”。更麻烦的是，同一个业务字段在不同文件里有三种叫法，三个模块对同一个状态的判断逻辑各有各的理解。那时候我就意识到，团队缺的不是代码规范，缺的是一套能把上下文信息固化下来的表达方式。
后来我把这套表达方式整理成了一个小型的设计约定，代号就叫 context-mode。它不是框架，不是插件，也不是某个仓库里的配置项。它本质上是一种编写代码注释和整理技术信息的范式：在代码的关键位置，用统一的格式补充出“业务背景、依赖关系、设计取舍”这三类上下文。这个项目标题看起来像个命令行参数或者编辑器配置，但它真正的价值在于，把散落在文档、聊天记录、会议纪要里的隐性知识，重新放回到代码本身里面。
这套东西适合谁呢？我觉得适合三类人：第一类，经常要接手老项目、每次都要靠“考古”才能搞懂逻辑的开发者；第二类，团队里负责技术规范和质量把控的负责人，想在不大动干戈的前提下提升代码可读性；第三类，自己写代码但几个月后回看也会发懵的个人开发者。后面我会把定义、用法、落地时机、踩坑记录全部拆开讲，并且附上可以直接抄走的模板。
有一点先说明：以下所有方案都来自我在实际项目中的摸索，不代表任何官方标准。你可以把它当做一个可裁剪的实践参考，核心思路比具体格式更重要。
2. 为什么普通的注释不够用：从一次重构事故说起
2.1 那次让我下定决心的事故
前阵子有个内部系统要做重构，其中一个模块是从单体服务里抽离出去，改成独立部署。从代码层面看，结构很清晰，接口也规范，单元测试覆盖率不低。但我接手之后发现，真正难的不是抽代码，而是搞明白几个关键问题。
第一个问题是：某个字段的值从 A 变到 B 之后，为什么会对下游三个服务的返回结果产生影响？代码里没有任何一处注释提到这个联动。第二个问题是：一个看起来“多余”的判断分支，到底是在防御什么异常场景？如果删掉，会不会在某个特定数据组合下出隐性 bug？第三个问题是：为什么某个表的数据不在本地库，而是要从远端接口拉取？这个设计是不是已经过时了？
我当时翻了需求文档、查了 Git 提交记录、看了好几个月的群聊天记录，才拼凑出大概的答案。这个过程花了一天多，真正写重构代码只花了三个小时。这件事给我的触动很大：代码里缺失的上下文，最终是靠人肉去补的，而且每换一个人，就要重新经历一次同样的考证过程。
2.2 注释的三种“疾病”
我把传统注释的问题归结为三种。
第一种叫复读机注释。就是注释把代码又念了一遍，比如let count = 0;后面写// 设置 count 为 0。这种注释对理解毫无帮助，唯一的作用是让代码行数显得多一点。
第二种叫心情注释。就是只写“这里逻辑很复杂”“此段代码请勿乱改”“后面有空优化一下”，但完全不交代复杂在哪、为什么别改、哪里要优化。几年后有人看到这些字，只能靠猜。我也在不少仓库里见过 “// 慎动！” 后面其实只是一个普通的排序函数，真不知道当初写这几个字的人在想什么。
第三种叫过期注释。注释写的是旧逻辑，代码已经改过三轮了，注释还停留在最初那个版本。这比没有注释更危险，因为看注释的人会被误导到完全错误的方向上。
2.3 context-mode 的核心出发点
context-mode 想解决的就是这三类疾病的共性问题：缺少语境。我要求的注释不是记录代码在做什么，而是记录代码为什么存在、为什么这么写、改动时需要注意什么。
打个比方。普通注释像地图上的路名，context-mode 则是给每条路加上了路牌说明——这条路通向哪个城区、路况如何、什么时间段容易堵。有了这些信息，后来的人才能在不同情况下做出正确选择，而不是靠感觉乱走。
3. context-mode 的三维拆解：业务背景、依赖说明、设计取舍
3.1 第一维：写清业务背景，而不是业务过程
很多注释喜欢写“此接口用于查询订单列表”，这是过程描述。context-mode 要求的是把业务背景写出来，让人知道这个查询在业务上意味着什么。
举一个实际例子。一个订单系统里有这样一段代码：对订单状态做判断，值为 2 时走退款流程。普通注释可能写// 状态为2时走退款。context-mode 会写：
// 订单状态：1-待支付，2-已支付待审核，3-审核通过，4-已退款 // 状态为2时进入退款预审流程，此时资金尚未冻结，支持用户主动取消 // 注意：状态2的订单在每日凌晨的定时任务中会自动流转到状态3， // 如果有退款诉求需在状态2触发，否则需走人工介入通道这三行字看似啰嗦，但它把状态枚举、该状态下的业务时机、自动流转规则一次说清了。后来维护的人在改这段逻辑时，就不会只盯着 if 条件看，而是先想清楚这个时间窗口是否允许变更。
3.2 第二维：标注依赖关系，特别是隐性的那部分
代码里的依赖不只是 import 和 API 调用。隐性依赖才是坑，典型的有三种：数据依赖（比如字段值的变更会影响下游统计）、时序依赖（只有某个阶段调用了初始化函数，后续流程才正常）、环境依赖（依赖某个特定配置项或外部服务的返回值）。
context-mode 要求在每个核心模块的入口处，用一个固定段落说明“我依赖什么，以及谁依赖我”。模版类似这样：
<!-- context-mode-依赖说明 --> <!-- 依赖上游：用户服务提供的用户等级字段（user_level） --> <!-- 影响下游：清算服务的对账报表（字段变更需同步通知） --> <!-- 环境要求：需在配置中心开启 features.trade.v2 开关 -->这段内容不追求面面俱到，但必须在改动这个模块时能让人一眼看到影响范围。我见过不少线上故障就是改了一个“看起来只有自己用”的字段，结果下游报表整体错位。如果你在每个模块上都留下这类依赖标签，这种问题至少能提前拦截一半。
3.3 第三维：记录设计取舍，把“当时的思考”留给后来的人
第三个维度是记录取舍。技术方案没有绝对的对错，只有取舍。把取舍写下来，不仅是在帮后来的人理解，更是在防止后人把曾经验证过的错误又重做一遍。
举个例子，我处理过一个项目，原本用乐观锁控制并发，但后来在部分接口里改成了分布式锁。从代码规范角度讲，两种方式混用确实不够统一。但当时改成分布式锁是受了业务方的强制要求：特定用户可能在同一毫秒内发起多笔订单请求，乐观锁的版本冲突会给用户带来较差的反馈体验。如果注释里不记录这个背景，后续维护者大概率会“好心”把代码改成统一用乐观锁，然后线上出现一批诡异的失败订单。
context-mode 里的取舍记录，格式可以很轻量：
<!-- context-mode-设计取舍 --> <!-- 决策：本接口使用分布式锁而非乐观锁 --> <!-- 原因：用户连续点击下单时，乐观锁冲突导致请求失败需重试，体验风险高 --> <!-- 副作用：单机压测时吞吐量比乐观锁方案低约15%，但业务峰值场景完全可接受 --> <!-- 替换条件：如果未来拆分了库存服务，可重新评估两种方案的边际成本 -->一段话把“当时为什么这么选”“带来什么代价”“什么时候可以重做”都交代了。这就是把设计文档的精华浓缩到了代码注解里。
3.4 为什么这三个维度足够用
有人可能会问，除了这三类，上下文还包括性能要求、安全约束、过期计划等等。确实存在，但我不建议把这些全都塞进注释体系里。因为粒度太细的规范很难长期坚持，注释写得像论文，维护成本反而上涨。业务背景、依赖说明、设计取舍是每一段核心代码都绕不开的三要素，先把它做扎实，其他的可以根据团队需要再扩展。
4. context-mode 的落地步骤：如何在自己的项目里开始
4.1 第一步：选定试验范围，不要全面铺开
我踩过的第一个坑就是试图把所有文件都补上注释，结果坚持了两周就放弃了。原因很简单：存量代码太多，补注释变成了一个望不到头的任务，每天新增的代码又不断挤压时间。
后来我调整了策略。第一个试点范围只圈定三层代码：第一层是核心数据模型（表结构映射、状态机逻辑）；第二层是跨模块调用的接口入口；第三层是带有明显 if-else 分支、策略模式或定时任务的业务逻辑。这三个位置的上下文是最容易丢失的，也是最值得固化的。其他普通的 CRUD 代码，维持原有注释风格即可。
4.2 第二步：借用代码评审把规范钉进去
光靠自觉，规范是落不了地的。我把 context-mode 的检查项直接写进了团队的代码评审模板里，每次提 MR 时都会要求提交者自查两个问题：这是一个后续可能被他人修改的核心逻辑吗？如果是，是否已经补齐业务背景、依赖说明、设计取舍三类上下文？
这样做有一个额外的好处：写的人如果在评审前发现自己讲不清楚某个设计的取舍，那大概率说明他本人还没想清楚。这是一个非常有效的自检工具。有几次开发同事在补齐 context-mode 注释的过程中，主动发现原有的逻辑有边界漏洞，进而修改了实现方案。
4.3 第三步：给上下文注释一个固定的“壳”
我建议所有 context-mode 注释使用统一的 XML 注释风格，就像这样：
/** * @context-mode * @business 用户发起退款申请后，系统先校验订单是否超过售后期， * 超过则直接驳回，未超过则进入人工二审。 * @dependency 依赖用户中心返回的注册日期字段(reg_date)， * 退款单创建后会影响财务侧的日资金汇总报表。 * @tradeoff 使用同步校验而非异步消息，隔离复杂度低； * 缺点是退款接口耗时增加约30ms，可接受。 */好处很明显：团队成员只要打开文件就能用搜索引擎或代码检索工具快速定位所有上下文注释，甚至可以脚本化检查覆盖率。如果团队使用支持结构化注释的 IDE，还能获得额外的代码提示。
4.4 第四步：用索引文件串联阅读路径
context-mode 的另一种应用方式，是在每个子模块的根目录放一个名为CONTEXT.md的总览文件，内容是一份模块上下文清单。它不是传统意义上的设计文档，而更像一个索引，指向每个核心代码文件里的 context-mode 注释。
我当时在一个物流订单模块里维护了这样一个 INDEX 清单，效果非常显著。新入职的同事通过这个清单，只花了一天时间就把模块的业务链路说得七七八八，而之前同样的事情通常需要一周到两周。这份索引文件同时也成了代码评审的入场指引：评审者先读它，再去看 diff，对变更的理解速度快了很多。
5. 在 AI 辅助开发时代，context-mode 的价值被放大了
5.1 上下文注释就是给 AI 的“提词器”
现在越来越多的开发者开始使用 AI 辅助编程工具。我发现一个很有意思的现象：AI 工具在代码质量差、注释缺失的仓库里，表现就像个没有感情的接话机器，改出来的东西风格飘忽，甚至会经常性带入上下文不匹配的幻觉；但一旦仓库里出现了结构化的上下文注释，AI 生成代码的准确性呈几何级提升。
原因不复杂。大语言模型在补全代码时，依赖输入序列里的信息来推测意图。传统注释是“非结构化”的，模型很难从中稳定捕捉“为什么要写这段代码”。而 context-mode 提供的三要素注释，本身就是一种简洁的结构化语料。它把业务约束、依赖关系、取舍边界都摆出来了，模型生成时自然会遵循这些边界条件。
我自己实测过，在一个订单模块里，同样的需求让 AI 生成新接口，有 context-mode 注释和没有是完全两套体验。前者生成的代码基本一次通过，后者总是出现枚举值不匹配、错误处理缺失这类问题。这相当于给 AI 配了一个“业务方向盘”。
5.2 处理与 AI 工具的协同：注释和代码的版本同步问题
引入 context-mode 后发现一个微妙的问题：AI 工具会基于注释生成代码，但如果开发者修改了代码却没有同步更新注释，模型就会继续犯和人类一样的错误——根据过期的上下文输出不合理结果。
我的应对方案就是两条：第一，把 context-mode 注释纳入日常修改，凡改了代码逻辑就必须同步检查相邻的上下文注释是否仍然成立；第二，在代码评审环节加入自动脚本检查，扫描所有含有@context-mode标签的注释是否有过期的敏感说法，比如出现“不再使用的状态”“已废弃的方法”等关键词时予以提示。这两条并不复杂，但很管用。
6. 不踩坑指南：context-mode 最容易翻车的六个场景
6.1 把小作文塞进注释
context-mode 不是用来写长文的。我见过有人把一段完整的需求分析贴进代码文件里，一段注释两百行，滚半天滚不到底。这已经完全违背了轻量固化的初衷。核心代码注释应该控制在一屏之内，超过这个长度说明信息应该放到文档或需求系统里，注释里只留最核心的判断线索。
6.2 把注释写成了“项目史记”
还有一种是越写越偏，把 context-mode 弄成了变更日志。比如“2024年3月改为A方案，2024年5月因为B问题加了判断，2024年7月又改为C方案”。这样看似很详细，真正需要的“现状背景”反而被历史噪声淹没了。我自己的习惯是：注释里只保留最终决策的结论和理由，历史上曾经尝试但被否掉的方案就别写了。想看历史有 Git 呢。
6.3 为了维护而维护
任何规范一旦变成形式主义，就会迅速失去真实价值。有几个月我所在的项目在赶版本，团队里开始出现大量模板化的 context-mode 注释，比如在简单工具函数里也硬凑业务背景和设计取舍，一眼就看出来是套话。这说明大家在赶工时把它当作了一个必经流程，而不是理解代码的工具。我当时的处理方式是主动降低检查频率，改成只抽查核心模块，同时重申“不是所有函数都需要注释，需要上下文的才写”。
6.4 忽略注释本身的准确性
这个问题最致命。如果注释里写的信息是错误的，它比没有注释更坑人。有一次我排查一个故障，第一反应把 context-mode 里标注的“该字段值只可能为 1 或 2”当做权威信息，结果忽略了数据库里还躺着一个历史脏数据 3，浪费了两个小时。后来我叮嘱自己和团队：注释只能信任，不能迷信；真正执行时还是要以实际代码和实际数据为准。
6.5 用 context-mode 替代一切文档
这是方向性错误。context-mode 只适合记录“紧贴代码的、微型的、运行时相关的”上下文信息。涉及多人协作流程的、跨季度规划的、需要产品背景解读的大型设计，还是应该放到正规模档体系中。两者是互补关系，不是替代关系。把什么都塞进注释，最终只会让代码库变得又冗余又难翻。
6.6 忽略团队认知水平的不同阶段
最后一条是组织层面的：context-mode 不能一次性以“规章制度”的形式强推下去。不同团队对“什么是核心逻辑”“什么算值得记录的设计决策”的认知差异很大。强推只会产生两类情况，一类是资深工程师觉得被限制得难受，一类是初级工程师完全不知道该怎么写。我更建议先在一个小范围内小规模试行，打出样例和模板，让效果自己说话。
7. 落地路线参考：四周从零到一推行 context-mode
这里分享我一套基于实操验证的渐进式落地节奏，供有想法在团队里推一推的读者参考。
第一周——定义与试点。圈定一个核心业务模块，约 20 到 30 个文件即可。团队全员参考已有样例格式，给该模块的核心方法补齐 context-mode 注释。目标不是追求覆盖率，而是建立团队对这类注释的体感，把“什么内容该进注释”这个边界问题讨论清楚。
第二周——存量梳理。根据影响范围排序，优先给跨模块同步的接口、定时任务、状态机转换三个位置补充上下文。这一周的重点是确认依赖说明的准确性。注意别贪多，每天给自己限定三个文件的补注释上限，不然第三周一定会断更。
第三周——建立引用路径。把每个子模块的 CONTEXT.md 索引搭起来，让新人在看代码前先花二十分钟读透这份索引文件。这时候团队会明显感受到变化：新人对业务流程的认知速度变快了，评审会议问出的问题也从“这个函数是干嘛的”变成了“这个状态流转在什么场景下触发”。
第四周——复盘与调整。看三组数据：核心代码文件中 context-mode 注释的覆盖率、代码评审中因上下文缺失而产生的修改轮次、新人梳理业务逻辑耗费的时长。这些指标不需要很精确，只要趋势变好，就说明这套方法在你的团队里是有效的。之后就可以把规范固化到脚手架的模板和代码评审模板里。
我自己的体会是，任何代码规范类方法，能不能长期活下去，靠的不是惩罚机制，而是它真的能在关键时刻帮人节约时间。当大家在一次线上问题排查中因为一段 context-mode 注释而省掉几小时的分析过程时，这套规范就牢牢地站稳脚跟了。如果你所在的团队也被“代码一看就懂、一细想全是问号”的问题困扰，不妨按我上面的路线，先拿一个模块试上一个月。一个月后你大概率会发现，同样的时间投入，换来的省心程度远超预期。
