Architecture Rot: How Code Degenerates from "Sweet" to "Beast"

What Is Architecture Rot?

Architecture Rot (Architecture Rot) is the process by which a system’s architecture loses its original design quality over time, becoming chaotic and hard to maintain.

Analogy

新建楼盘 → 5年后

初期：
┌─────────────────────┐
│ ████ │ ████ │ ████ │
│ ████ │ ████ │ ████ │
│ ████ │ ████ │ ████ │
│ ████ │ ████ │ ████ │
└─────────────────────┘
整洁、漂亮、功能完善

5年后：
┌─────────────────────┐
│ ▓▓▓ │ ███ │ ▒▒▒ │
│ ▓▓▓ │ ▒▒▒ │ ███ │
│ ▒▒▒ │ ███ │ ▓▓▓ │
│ ███ │ ▒▒▒ │ ▒▒▒ │
└─────────────────────┘
乱搭乱建、管道外露、功能退化

Stages of Architecture Rot

1. Healthy Phase (0‑1 year)

Clear architecture

Clean code

Complete documentation

Stable team

2. Debt Accumulation Phase (1‑3 years)

Small compromises appear

Technical debt grows

Documentation becomes outdated

Team turnover begins

3. Degradation Phase (3‑5 years)

Technical debt is obvious

Code quality drops

Adding new features becomes difficult

Team morale declines

4. Crisis Phase (5+ years)

System is almost unmaintainable

Any change may introduce bugs

Team refuses to take over

Consider rewriting

Manifestations

Code‑Level Symptoms

1. Duplicate code proliferation

// UserService.java
public User getUserById(Long id) {
    // 500行代码
}

// UserManager.java
public User queryUser(Long id) {
    // 同样的500行代码（复制粘贴）
}

// UserHelper.java
public User findUser(Long id) {
    // 还是同样的500行代码
}

2. Methods become excessively long

public void processOrder(Order order) {
    // 500行
    // 800行...
}

3. Inconsistent naming

public class User {
    // 到底哪个是用户名？
    private String userName;
    private String username;
    private String name;
    private String user_name;
    private String nickName;
}

4. Circular dependencies

// A.java
public class A {
    public void methodA() {
        B b = new B();
        b.methodB();
    }
}

// B.java
public class B {
    public void methodB() {
        A a = new A();
        a.methodA();
    }
}

Architecture‑Level Symptoms

1. Blurred boundaries

原来：
┌──────┐     ┌──────┐     ┌──────┐
│  A   │     │  B   │     │  C   │
└──────┘     └──────┘     └──────┘
边界清晰

现在：
┌─────────────────────────────┐
│     不知道什么乱七八糟的东西    │
│                               │
│     各种类纠缠在一起          │
└─────────────────────────────┘

2. Dependency chaos

原来：
A → B → C

现在：
   ↗   ↘
A → X ← C
↑   ↘   ↗   ↑
B ← Y ← Z

3. Single points of failure

原来：
┌────┐  ┌────┐  ┌────┐
│ S1 │  │ S2 │  │ S3 │
└────┘  └────┘  └────┘
无单点

现在：
┌────┐     ┌────┐     ┌────┐
│ S1 │────→│ S2 │────→│ S3 │
└────┘     └────┘     └────┘
    ↑                 │
    └───────────────────┘
    S2是单点，挂了全挂

Team‑Level Symptoms

1. Knowledge gaps

新员工A：我看不懂这段代码
新员工B：没人能看懂
老员工：我也看不懂了

2. Change aversion

开发：这个改动太大，不敢动
领导：尽量不要动老代码
运维：出问题了谁负责？

3. Low morale

- 没人愿意写代码
- 没人愿意接手项目
- 离职率上升

Root Causes

Business Causes

Requirement changes – business direction shifts faster than architecture can adapt

Rapid iteration – speed over quality leads to shortcuts

Temporary solutions become permanent

Technical Causes

Technical debt – unpaid debt accumulates

Poor technology choices – long‑term pain

Lack of standards – each team does its own thing

Team Causes

Personnel turnover – loss of knowledge

Insufficient communication – unclear design intent

Skill gaps – weak design capability

Detecting Architecture Rot

Quantitative Indicators

Code duplication rate: normal <5%, warning 5‑15%, danger >15%

Average method length: normal <20 lines, warning 20‑50, danger >50

Cyclomatic complexity: normal <10, warning 10‑20, danger >20

Dependency depth: normal <5 layers, warning 5‑10, danger >10

Test coverage: normal >80%, warning 50‑80%, danger <50%

Team‑Perceived Signals

New feature development time keeps increasing

Bug‑fix time keeps increasing

Code reviews become harder

No one dares to touch certain modules

Test cases cannot be written

Merge conflicts rise

Detection Tools

SonarQube scan (sonar‑scanner)

Complexity analysis (ck -t=30)

Dependency analysis (mvn dependency:analyze)

Code similarity detection (simian)

Governance Strategies

1. Prevention First

Code standards

# 代码规范
- 方法长度不超过50行
- 类长度不超过500行
- 圈复杂度不超过15
- 重复代码不超过3次

Code Review

每次代码提交必须Review
发现问题及时处理
防止问题积累

Continuous Testing

单元测试覆盖率 > 80%
每次提交自动跑测试
测试失败阻止合并

2. Regular "Health Checks"

Monthly: code‑quality scanning

Quarterly: architecture review

Yearly: system refactor evaluation

3. Incremental Refactoring

Principles

1. Do not change external behavior
2. Change only a little at a time
3. Test after each change
4. Continuous integration
5. Keep deployable

Timing Signals

Development efficiency drops 50% → refactor immediately

Frequent bugs → refactor as soon as possible

Unable to recruit → plan refactor

Business expansion exceeds architecture capacity → refactor proactively

4. Progressive Re‑architecture (Strangler Fig Pattern)

Strategy : Do not rewrite; replace the old system gradually from the outside.

步骤：
1. 识别核心模块
2. 抽取新服务
3. 逐步迁移
4. 旧代码自然消亡

Case Study: Refactoring a Rotting System

Before Refactoring

问题：
- 10万行业务代码
- 测试覆盖率 < 20%
- 单体架构，无法扩展
- 没有任何文档

状态：
- 新功能需要3个月
- Bug修复需要2周
- 团队5人，3个想离职

Refactoring Strategy

策略：strangler fig pattern（绞杀者模式）
不重写，而是在外围逐步替换
步骤：
1. 识别核心模块
2. 抽取新服务
3. 逐步迁移
4. 旧代码自然消亡

Refactoring Process

Month 1-2: 抽取用户模块 → 新服务
Month 3-4: 抽取商品模块 → 新服务
Month 5-6: 抽取订单模块 → 新服务
Month 7-8: 抽取支付模块 → 新服务
Month 9-10: 迁移完成，废弃旧系统

After Refactoring

状态：
- 10个微服务
- 测试覆盖率 > 80%
- 新功能2周交付
- Bug当天修复
- 团队稳定

Conclusion

Architecture rot is a gradual process; preventing it is far easier than trying to cure it after it reaches a crisis.

Architecture rot is a progressive process; prevention is much easier than remediation.