对AI友好的代码：从“易读”到“高信噪比”

visual_zhang
5 阅读6分钟

在引入 Claude Opus 4.6 作为团队的主力辅助模型后，我观察到一个有趣的现象：模型的推理能力确实强悍，但这并不意味着我们可以忽视代码质量。

相反，一个残酷的现实逐渐浮出水面：AI 的效能上限，依然被工程代码的质量下限所锁死。

以前我们认为“烂代码”会让 AI 读不懂；现在的情况是，凭借 Claude 强大的上下文窗口和推理能力，它确实能读懂那些逻辑混乱的代码，但代价是消耗惊人的 Token。为了理清一个隐晦的全局状态，它可能需要加载几十个文件的上下文。这不仅导致成本飙升、响应变慢，更重要的是，当上下文过载时，模型的注意力会被稀释，幻觉（Hallucination）的风险依然存在。

因此，我们需要重新审视代码规范，建立一套**“AI 友好（AI-Friendly）”**的工程标准。

一、 定义“AI 友好”的新标准

在 AI 辅助编程（AI-Assisted Programming）日益普及的今天，代码的受众已不再仅仅是人类工程师，还包括了作为“副驾驶”的大语言模型。

什么样的代码才算是“AI 友好”？我认为主要包含三个维度：

  1. 低 Token 消耗（Token Efficiency）： 这是最直观的指标。完成同样的任务，AI 需要读取的上下文越少，效率越高。好的架构应该能让 AI 在“局部上下文”中就能准确理解逻辑，而不是被迫去扫描整个项目。

  2. 高信噪比（High Signal-to-Noise Ratio）： 代码应当具备清晰的语义和显式的约束。减少模棱两可的命名和隐式逻辑，降低 AI 在推理时的“猜测”成分。

  3. 抗腐蚀性（Anti-Corrosion）： 随着代码库的迭代，AI 工具（特别是基于 RAG 的检索工具）很容易拿到过期的上下文。代码设计需要具备抵抗“上下文失效”的能力。

二、 显式依赖：用架构换取 Token 效率

关于单例模式（Singleton）或隐式全局状态（Global State），过去我们常说它是“AI 的噩梦”。严格来说，这个说法在 Claude Opus 4.6 面前已经不完全准确了。

如果我们将整个项目的代码都喂给模型，它确实有能力追踪到 User.current 在哪个角落被修改了。但问题在于：值得吗？

为了理解一个简单的状态变更，AI 不得不消耗大量的 Token 去遍历所有可能的调用方。一旦任务过于庞大，或者代码质量本身较低（比如缺乏注释、命名混乱），即便是最先进的模型，也无法通过堆砌 Token 来完全消除幻觉。

[这里请补充一个你遇到的真实案例：比如任务过于庞大，导致 AI 虽然读了很多代码，但依然在某个边缘 Case 上产生了幻觉，或者消耗了大量 Token 却给出了错误的修改建议]

解决方案：拥抱依赖注入（DI）。

通过构造函数明确声明模块所需的依赖，本质上是在划定上下文的边界。

  • 高 Token 消耗写法（隐式依赖）：

    class ProfileManager {
    func update() {
        // AI 需要扫描整个 NetworkService 的引用链才能确定其状态
        NetworkService.shared.post(...) 
    }
}

  • 低 Token 消耗写法（显式依赖）：

    class ProfileManager {
    let network: Networking
    
    // AI 仅需读取这个 init，就能以极低的 Token 成本理解该类的能力边界
    init(network: Networking) { 
        self.network = network 
    }
}

这种写法让 AI 能够在极小的上下文窗口内（Small Context）完成高准确率的推理，这才是真正的“AI 友好”。

三、 强类型与测试：提供确定性的决策依据

1. 强类型约束：减少幻觉

虽然 Swift 是强类型语言，但在处理遗留代码或 JSON 数据时，Dictionary<String, Any> 依然常见。这对 AI 来说意味着巨大的不确定性。

AI 友好实践：

  • 利用 Enum 表达状态：Swift 的枚举及其关联值（Associated Values）能强制 AI 处理所有分支。
  • 面向协议编程（Protocol-Oriented）：当让 AI 实现功能时，直接提供清晰的 Protocol 定义。相比于自然语言描述，Protocol 是最高效的 Prompt，它能生成非常标准的 Mock 或 Impl 代码。

2. 测试即文档：唯一不过期的上下文

文档（Wiki/Readme）往往滞后于代码，AI 检索到的可能是过时的业务规则。而测试代码是唯一“保证正确”的文档。

AI 友好实践：

  • 语义化测试用例：将测试用例命名得像自然语言一样清晰（如 test_calculateDiscount_givenVIP_returns20Percent）。
  • Grounding（接地）：当 AI 检索“如何计算折扣”时，如果检索到了上述测试用例，这比检索具体的实现代码更能抵抗“实现细节的漂移”。因为实现细节常变，但业务规则相对稳定。

四、 对抗“上下文失效”：让工具始终在线

这是业界常被忽视的维度。随着代码库的快速迭代，AI 工具所依赖的上下文（如函数签名、API 定义）很容易过期（Stale）。

1. 语义锚点 (Semantic Anchors)

AI 工具如果依赖具体的行号或文件名（如 User.swift:50-100），一旦文件重构或移动，工具立即失效。

建议：在关键业务逻辑处使用特定的 Annotation 或 Marker Protocol。

// MARK: - [Auth_Core_Logic] 登录核心流程
// 即使函数名改为 signIn，AI 工具依然能通过关键词锚定这段逻辑。
func performLogin() { ... }

2. 向量化友好的原子结构

在 RAG（检索增强生成）场景下，几千行的“上帝类”（God Class）会导致检索结果包含大量无关噪音，迫使模型处理大量无效 Token。

建议：将代码拆得越细（例如一个文件只放一个 Extension 或一个 View），向量化检索的颗粒度就越精准。这不仅降低了 Token 消耗，也提高了检索的相关性。

五、 总结

在 AI 时代，代码的可维护性不仅仅是为了方便人类同事接手，更是为了让 AI 助手能更经济、更准确地协助我们工作。

AI 友好的代码设计 = 强类型约束（减少幻觉） + 极度解耦（降低上下文成本/Token 消耗） + 语义锚点（防止工具失效） + 完善的测试（提供决策依据）。

我们将代码库从一个单纯的“指令集”，升级为一个**“AI 可读、可理解、可追踪的知识库”**。这不仅是工程标准的升级，更是我们在大模型时代提升研发效能的必经之路。

avatar
文章
阅读
粉丝