kiss

KISS — 保持简单

应用前

如果存在 .agents/stack-context.md，请先阅读。根据检测到的技术栈，使用符合其惯用方式的模式来应用此原则。有关框架特定的细节，请使用 context7 MCP 或网络搜索，不要猜测。

原则

如果两种方案能产生相同结果，优先选择更易于阅读、理解和修改的方案。

这对生产环境为何重要

简单的代码经得起生产环境的考验。复杂的代码会以难以诊断、难以修复，也难以确认修复未引入其他问题的方式出错。每次故障响应都始于有人在压力下阅读代码——如果他们无法快速理解，故障持续时间就会更长。

复杂性会层层叠加。今天「稍微巧妙」的方案，经过三位不同开发者六个月的修补后，就会变得「令人费解」。

最危险的 Bug 藏在复杂到任何一个人都无法完全记在脑中的代码里。

规则

1. 优先考虑易读，而非易写。 代码被阅读的次数是编写次数的 10 倍。一段多几行但清晰的代码，胜过需要注释才能解释的一行代码。
2. 使用成熟可靠的技术。 相比新颖的工具、模式和库，优先选择经过充分理解的方案。新颖方案会在调试、招聘和文档方面带来隐藏成本。
3. 限制嵌套深度。 如果函数的嵌套超过 3 层，就用提前返回、守卫子句或提取辅助函数来扁平化结构。
4. 一个函数只做一件事。 如果描述函数功能时需要用到「以及」，就把它拆分。
5. 根据功能命名，而非实现方式。 使用 get_active_users()，而不是 query_db_filter_status_map_results()。
6. 避免炫技式技巧。 位运算技巧、用于复杂解析的正则表达式单行写法、用于不直观操作的运算符重载——这些迎合的是编写者的自负，而非读者的理解能力。
7. 优先选择显式，而非隐式。 魔法值、隐藏状态、隐式类型转换和远距离副作用会让代码变得难以预测。

反模式

• 过早优化： 在没有性能分析数据证明优化确有必要时，为了性能牺牲可读性
• 抽象过度： 工厂的工厂模式、层层嵌套的泛型、为简单任务引入框架
• 炫技式单行代码： 将逻辑压缩到晦涩难懂的密集表达式
• 上帝函数： 长达 200 行以上、处理多个关注点的函数
• 字符串类型泛滥： 使用原始字符串，而不使用能提升清晰度的枚举、类型或常量
• 隐藏控制流： 装饰器、中间件链或事件系统，让人无法追踪请求到达时会发生什么

示例

-- Overly clever
users = {u.id: u for u in db.query(User) if u.active and u.role in roles and not u.banned}

-- Simple and scannable
active_users = db.query(User).where(active=true, banned=false)
users = filter_by_role(active_users, roles)
users_by_id = index_by(users, key="id")

-- Deeply nested
def process(data):
    if data:
        if data.valid:
            if data.type == "order":
                if data.items:
                    # actual logic buried 4 levels deep

-- Flattened with guard clauses
def process(data):
    if not data:
        return
    if not data.valid:
        return
    if data.type != "order":
        return
    if not data.items:
        return
    # actual logic at top level

边界

• 简单不代表天真。 错误处理、输入验证和恰当的数据结构都不属于「复杂性」——它们关乎正确性。不要以简单为名削弱安全性。
• 简单不代表原始。 使用精心挑选的库或模式（例如用状态机处理复杂的状态转换），可能比手动实现等效逻辑更简单。
• 有些领域本质上就很复杂。 密码学、分布式共识和金融计算都有无法消除的复杂性。KISS 的意思是不要在此基础上再添加不必要的复杂性。
• 与 DRY 的张力： 有时，重复几行代码比引入抽象更简单。优先选择新团队成员能在 30 秒内理解的版本。

代码审查清单

• 新团队成员能否在不询问作者的情况下理解这段代码？
• 是否有为了减少代码行数而牺牲清晰度的「巧妙」捷径？
• 所有代码的嵌套深度是否都不超过 3 层？
• 每个函数是否都有单一且明确的职责？
• 是否可以用命名清晰的辅助函数替换复杂逻辑？
• 是否有注释解释「做什么」而非「为什么」？（如果有，说明代码本身还不够清晰。）

相关技能

• yagni：当复杂性源于构建当前还不需要的功能时
• separation-of-concerns：当复杂性源于职责混杂时
• solid：当复杂性源于模块设计不佳时