一、单体应用扩容后，新同学为啥会卡壳

之前我们团队刚从15人涨到25人那会，有个刚毕业的同学要加个“新用户邀请得积分”的小功能，原本以为改个两三个文件就行，结果翻了整整4天代码，改了8处地方，上线当天还出了bug——把老用户的积分给扣了。后来复盘才发现，那个功能的逻辑，用户模块管了积分，订单模块管了邀请，两个模块的边界本来就定死了，但没人把这个规则写清楚，新同学以为所有积分都在用户模块里，直接动了订单模块里的逻辑，才出的错。这种情况在团队规模小的时候不会有，因为15个人大家天天挤在一块，改代码随口问就行，但人多了，不可能每个人都熟所有细节，这就是单体应用扩容后最头疼的入门成本问题：新同学要花大量时间找“代码到底在哪”“规则是啥”“边界在哪”。

二、两个简单方法，降成本保一致

解决这个问题不用搞复杂的架构，就两个接地气的办法——把“为什么这么做”写下来，让代码自己“说人话”。

2.1 架构决策记录：把“当时为啥定这规则”存好

很多团队改代码只写“做了什么”，不写“为什么这么做”，就像你把衣服叠得整整齐齐，但不贴标签，后来找的时候全乱。架构决策记录（咱们就叫“规则笔记”吧）就是把当初定技术方案、模块边界的原因写清楚，不管过多久，新人一看就懂。 咱们举个例子，就说刚才的用户模块的规则笔记，技术栈不算复杂，就是文本记录：

ADR编号：ADR-003
决策时间：2023年6月
决策内容：用户核心数据（积分、等级）存在模块内的字典里
原因：
1. 团队初期人少，单体应用功能不多，用字典读写快，不用搭数据库，省时间
2. 后续要换数据库的话，只改模块里的读写部分，不用动其他业务逻辑
边界：
- 用户的订单、地址逻辑绝对不能放这个模块，必须单独做订单模块
- 积分只能用add_points方法改，不能直接碰字典里的points，保证后续切换数据库不崩

这个笔记就是给新人留的“导航图”，比如新同学要改积分相关的，一看就知道：只能在用户模块里加，还要用专门的方法，不能乱碰其他地方，避免跨模块乱改。

2.2 模块自解释：让代码不用查文档也懂

代码本身要“说人话”，不用别人猜。比如之前的用户模块代码，要是写得全是黑话，新人肯定懵，但要是写得明明白白，比如用Python写的：

# 技术栈：Python 3.10
# 用户模块：只负责用户的核心操作，比如注册、加积分、算等级，其他的都不管
class UserModule:
    def __init__(self):
        # 存用户的临时数据，参考ADR-003，后续换数据库只要改这块
        self.user_db = {}
    
    def add_points(self, user_id, points):
        # 划重点：这个方法只负责给用户加积分，绝对不发券！发券是订单模块的事，别越权！
        if user_id not in self.user_db:
            raise Exception("用户不存在，先注册再说")
        self.user_db[user_id]['points'] += points
        # 加完积分自动更新等级，规则别改，青铜100以下，白银101-500，黄金501以上
        self._update_level(user_id)
    
    def _update_level(self, user_id):
        # 等级规则：青铜0-100，白银101-500，黄金501+，别乱改！改了所有人都懵
        current_points = self.user_db[user_id]['points']
        if current_points >=501:
            self.user_db[user_id]['level'] = '黄金'
        elif current_points >=101:
            self.user_db[user_id]['level'] = '白银'
        else:
            self.user_db[user_id]['level'] = '青铜'

这里的注释都是新人能看懂的大白话，不仅说了做什么，还说了“不能做什么”“别改什么”，比如“绝对不发券”“别越权”，相当于给新人画了安全线，不会乱碰边界。

三、落地的时候要注意啥，别踩坑

3.1 应用场景：刚好是团队从10人涨到30人的时候

小团队（10人以内）大家天天凑一块，改个代码喊一声就知道，不用这些方法；但当团队超过20人，模块开始变多，很多人不用天天写同一个模块，这时候就需要规则笔记和自解释代码，不然肯定会出乱子。比如我们团队25人后，用了这两个方法，新同学入门时间从之前的1周降到了1天，跨模块的bug少了80%。

3.2 优缺点：初期花点时间，长期省大麻烦

架构决策记录的优点是，过半年甚至一年，有人接手老模块，一看笔记就懂当初的规则，不会乱改；缺点就是要花1-2个小时写每一条规则，初期可能觉得麻烦，比如我们团队第一次写ADR的时候，花了3天，之后再也没因为规则不懂出过大bug。 模块自解释的优点是，代码本身就是文档，不用专门查别的东西；缺点就是如果注释写得太笼统，比如只写“处理用户”，反而误导人，所以注释要写“为什么”，不是只写“做什么”。

3.3 注意事项：别把规则写成死的，要更新

规则笔记不是写完就不管了，比如你把字典换成了数据库，要马上更新ADR-003的内容，告诉大家现在用数据库了，还有对应的注释也要改；模块的命名和方法名要统一，比如所有模块都叫xxx_module，方法用下划线，不用驼峰，新人一看就知道是什么。

3.4 总结：不用搞复杂的东西，把细节说透就行

其实这两个方法本质上就是把“隐性的经验”变成“显性的规则”，让新同学不用猜，不用踩坑，也保证整个团队的代码不会变得乱七八糟，模块之间不会乱碰，一致性就有了，入门成本也降下来了。