构建 AI Agent 的关键经验教训

How we made our AI code reviewer stop being so noisy

我是 Paul，cubic 的联合创始人——一个"原生 AI GitHub"。

我们的核心功能之一是一个 AI 代码审查 agent，它执行 PR 的初次审查，捕捉 bugs、反模式、重复代码等问题。

当我们在 4 月首次发布时，主要反馈是它太"吵闹"了。

即使小型 PR 也经常充斥低价值的评论、过度挑剔或直接的假阳性。它不是帮助审查者，反而增加了混乱，掩盖了真正有价值的反馈。

我们决定退一步，调查为什么会出现这种情况。

经过三次主要的架构修改和大量的离线测试，我们设法将假阳性减少了 51%，而不牺牲召回率。

这些经验教训被证明非常有用，不仅用于代码审查，还用于设计有效的 AI agents，从开发者工具到面向客户的体验，如现代语音 AI Agent。

1. The Face‑Palm Phase: A Do‑Everything Agent

我们的 AI 代码审查工具的初始架构很简单但有问题：

[diff]
↓
[single large prompt with contextual codebase info]
↓
[list of comments]

在理论上看起来很干净，但在实践中迅速崩溃：

Excessive false positives: The agent often mistook style issues for critical bugs, flagged resolved issues, and repeated suggestions our linters had already addressed.

过多假阳性：agent 经常将样式问题误认为是关键 bug，标记已解决的问题，重复我们 linter 已处理的建议。

Users lost trust: Developers quickly learned to ignore the comments altogether. When half the comments feel irrelevant, the truly important ones get missed.

用户失去信任：开发者很快学会了完全忽略这些评论。当一半的评论看起来无关时，真正重要的评论被遗漏。

Opaque reasoning: Understanding why the agent made specific calls was practically impossible. Even explicit prompts like "ignore minor style issues" had minimal effect.

推理不透明：理解 agent 为什么做出特定决定几乎是不可能的。即使是明确的提示，如"忽略轻微的样式问题"，也只有最小的效果。

我们尝试了标准解决方案——更长的 prompt、调整模型的 temperature、实验采样——但没有看到有意义的改进。

2. What Finally Worked

经过广泛的试错，我们开发了一个架构，它在现实世界的仓库中显著改进了结果。

这导致了目前在生产中运行的假阳性减少 51%。

我们要求 AI 在提供任何反馈前明确陈述其推理：

{
  "reasoning": "`cfg` can be nil on line 42; dereferenced without check on line 47",
  "finding": "Possible nil‑pointer dereference",
  "confidence": 0.81
}

这种方法提供了关键好处：

Enabled us to clearly trace the AI's decision-making process. If reasoning was flawed, we could quickly identify and exclude the pattern in future iterations.

使我们能够清楚地追踪 AI 的决策过程。如果推理有缺陷，我们可以快速识别并在未来的迭代中排除该模式。

Encouraged structured thinking by forcing our Code Review AI to justify its findings first, significantly reducing arbitrary conclusions.

通过强制我们的代码审查 AI 首先为其发现辩护来鼓励结构化思考，显著减少武断的结论。

Created a foundation to diagnose and resolve root causes behind other issues we faced.

为诊断和解决我们面临的其他问题的根本原因创建了基础。

最初，agent 有广泛的工具：语言服务器协议（LSP）、静态分析、测试运行器等。

然而，显式推理日志显示大多数分析依赖于几个核心工具，额外的复杂性导致混淆和错误。

我们将工具集精简到仅必需的组件，一个简化的 LSP 和一个基本的终端。

由于干扰减少，agent 花费更多精力确认真实问题，显著提高了精度。

最初，我们的直觉是持续向单个大 prompt 中添加更多规则来处理边界情况：

"Ignore unused variables in .test.ts files."

"Skip import checks in Python's init.py."

"Don't lint markdown files."

这迅速变得不可持续，而且效果不佳，因为 AI 代码审查工具经常忽略许多规则。

我们的突破来自于使用专门的微型 agents，每个处理狭义定义的范围：

Planner: Quickly assesses changes and identifies necessary checks.

Planner：快速评估变化并识别必要的检查。

Security Agent: Detects vulnerabilities such as injection or insecure authentication.

Security Agent：检测注入或不安全身份验证等漏洞。

Duplication Agent: Flags repeated or copied code.

Duplication Agent：标记重复或复制的代码。

Editorial Agent: Handles typos and documentation consistency.

Editorial Agent：处理拼写错误和文档一致性。

专门化使每个 agent 能够保持聚焦的上下文，保持 token 使用效率和精度高。主要的权衡是由于重叠的上下文导致 token 消费增加，通过有效的缓存策略进行管理。

3. Real-world Outcomes

这些架构和 prompt 改进在来自活跃开源和私有仓库的数百个真实 pull 请求中产生了有意义的结果。具体来说，在过去的六周内：

51% fewer false positives, directly increasing developer trust and usability.

假阳性减少 51%，直接增加了开发者的信任和可用性。

Median comments per pull request cut by half, helping teams concentrate on genuinely important issues.

每个 pull 请求的中位评论数减少了一半，帮助团队专注于真正重要的问题。

Teams reported notably smoother review processes, spending less time managing irrelevant comments and more time effectively merging changes.

团队报告了明显更顺利的审查过程，花费更少的时间管理无关评论，更多的时间有效地合并变化。

此外，减少的噪音显著改进了开发者的信心和参与度，使审查更快、更有影响力。

核心要点

Explicit reasoning improves clarity. Require your AI to clearly explain its rationale first. This boosts accuracy and simplifies debugging.

显式推理提高清晰度。要求你的 AI 首先清楚地解释其理由。这提高了准确性并简化了调试。

Simplify the toolset. Regularly evaluate your agent's toolkit and remove tools rarely used (less than 10% of tasks).

简化工具集。定期评估你的 agent 工具集，删除很少使用的工具（少于 10% 的任务）。

Specialize with micro-agents. Keep each AI agent tightly focused on a single task, reducing cognitive overload and enhancing precision.

使用微型 agents 专门化。保持每个 AI agent 紧密聚焦于单个任务，减少认知过载并增强精度。

Microservices code review

微服务代码审查

© 2026 cubic. All rights reserved.

© 2026 cubic. 版权所有。