# Assessing Internal Code Quality with AI Agents

> 原文链接：https://martinfowler.com/articles/exploring-gen-ai/ccmenu-quality.html
> 作者/来源：Erik Doernenburg / Thoughtworks (Martin Fowler's blog)
> 阅读日期：2026-04-02

## 一句话总结
AI coding agent 虽然能快速生成功能性代码，但会频繁引入技术债务（类型系统违规、不必要的复杂性、不完整实现）；开发者专业判断仍然是保护代码库内部质量不退化的关键。

## 核心论点

Erik Doernenburg 通过为 CCMenu（一个 Swift 编写的 macOS CI/CD 状态应用）添加 GitLab 支持的实际案例，深入探讨了 AI agent 在代码质量方面的表现。他的核心主张是：**内部代码质量对于软件在数年时间跨度内保持可持续开发至关重要**，而 AI agent 在缺乏适当监督的情况下，往往会在快速生成功能代码的同时大量引入技术债务。

文章详细记录了多类质量问题。**类型系统违规**：agent 在 wrapper 函数中将 token 声明为 non-optional，造成语义不匹配。当 UI 代码需要 optional token 时，agent 提议用 `??` 运算符配合空字符串来变通，而不是修复底层函数签名——正确做法只需在参数上加一个 `?`。这种 workaround 违反了 Swift 惯用法、混淆了意图、且要求在整个代码库中做修改。

**不必要的复杂性**：agent 提出了不需要的功能（如未经解释的缓存系统），并在多处重复 URL 构造逻辑而非复用已有函数。**不完整实现**：agent 遗漏了 macOS defaults 系统用于测试中 base URL 覆盖的功能。**API 误解**：agent 难以区分 GitHub 和 GitLab 的设计模式差异——特别是 GitLab 需要单独的 API 调用获取用户头像。

Doernenburg 的经验从怀疑到谨慎采用：从 Windsurf/Sonnet 3.5 升级到 Claude Code/Sonnet 4.5 后，代码质量和返工量都有所改善，但仍然需要大量人类监督。

## 关键概念
- **内部质量 vs 外部质量**：外部质量（功能是否工作）agent 表现不错，但内部质量（代码结构、可维护性）需要人类把关
- **Workaround 倾向**：agent 倾向于用变通方案解决问题而非修复根本原因，导致技术债务累积
- **模式违规（Pattern Violations）**：agent 可能不理解代码库中已建立的设计模式和惯用法，产生不一致的代码
- **上下文缺失**：agent 不了解测试策略（如 macOS defaults 系统）等隐含的开发实践
- **工具/模型代际差异**：从 Sonnet 3.5 到 Sonnet 4.5 的升级显著改善了代码质量表现

## 实践建议
1. 始终审查 agent 生成的代码——不仅检查功能正确性，更要关注类型系统一致性、代码复用和惯用法遵循
2. 警惕 agent 提出的"不需要的功能"——如果无法解释其必要性，很可能是 hallucination
3. 当 agent 提出 workaround 时，先思考是否存在更根本的修复方案
4. 在 `CLAUDE.md` 或 `AGENTS.md` 中明确说明代码库的设计模式和惯用法，减少 agent 的模式违规
5. 使用最新一代的模型和工具——代际升级带来的质量提升是显著的
6. 对于不同 API 或框架的差异（如 GitHub vs GitLab），在上下文中明确说明，而不是假设 agent 能正确区分

## 独到观点
这篇文章的独特价值在于提供了**具体的、代码级别的质量问题案例**，而不是抽象地讨论"AI 代码质量"。`??` 运算符 vs `?` 参数修饰的对比特别有教育意义——它清晰展示了 agent 的 workaround 倾向如何将一个简单的修复变成代码库范围的污染。此外，从 Sonnet 3.5 到 4.5 的对比实验为模型选择提供了实证依据。

## 与其他文章的关联
- 与 **Writing a Good CLAUDE.md**（#15）直接相关：文中发现的设计模式违规问题可以通过在 `CLAUDE.md` 中明确说明代码库惯用法来缓解
- 与 **HumanLayer Backpressure**（#13）关联：agent 的 workaround 倾向部分源于 context 不足——backpressure 策略可以帮助 agent 在有限 context 中聚焦于关键信息
- 与 **Fowler Anchoring to Reference**（#21）互补：通过参考实现来锚定 agent 的代码质量标准
- 与 **Fowler Humans and Agents**（#22）相关：代码质量维护是人机协作中人类最重要的职责之一
- 与 **OpenHands Context Condensation**（#14）相关：长时间任务中 context 退化可能加剧质量问题
- 与 **Fowler SDD Tools**（#24）互补：开发工具链的选择直接影响 agent 的代码质量表现