Codebase Optimization for Agents

在将AI Agent引入代码库时，人们往往会本能地倾向于保留人类开发者体验（DX）。但这种做法会限制Agent的效能，因为代码库仍是针对人类而非日益趋向自主运作的AI智能体优化的。

另一个相关问题是：即便性能优异的模型，在缺乏清晰反馈循环的情况下也难以发挥应有作用。当Agent无法验证自身修改是否有效时，它的失效并非源于能力限制，而是因为代码库与Agent之间未能实现紧密适配。

优先针对Agent优化代码库，人类需求其次。接受为了大幅提升Agent性能，工具、工作流甚至编辑器体验对人类而言可能出现倒退。

反直觉的核心洞察：一旦采用面向Agent优化的工作流，你会大幅减少使用VS Code这类以人类为中心的工具，因此这类工具的体验倒退影响并不大。

AMP团队的真实实践案例： 该团队开发了Zveltch（基于Zig语言实现的拼写检查工具），目的是为Agent提供更高效的拼写检查能力。但这却导致人类开发者使用VS Code的体验下滑。他们面临艰难抉择：是保留人类的DX体验，还是优先优化Agent？

最终他们选择优先优化Agent，进而引发了“滚雪球效应”：

• Agent工具性能显著提升
• 人类更多依赖Agent完成工作
• 人类使用编辑器的频率降低
• 编辑器体验的重要性随之下降
• 进一步优化Agent的动力更强

graph LR
    A[代码库为人类优化] --> B[Agent表现不佳]
    A --> C[人类DX体验优异]

    D[优先优化Agent] --> E[Agent表现出色]
    D --> F[人类DX体验倒退]
    E --> G[人类更多使用Agent]
    G --> H[人类更少使用编辑器]
    H --> I[编辑器DX重要性降低]
    I --> D

    style F fill:#ffcdd2,stroke:#c62828
    style E fill:#c8e6c9,stroke:#2e7d32
    style G fill:#c8e6c9,stroke:#2e7d32

核心原则：要敢于摒弃传统开发工具领域的固有信条。

“将Agent与代码库‘焊接’绑定”：

“焊接”这一比喻，指的是构建紧密的自动化反馈循环，让Agent能够：

• 自动验证自身修改是否生效
• 获取清晰的成功/失败信号
• 无需人工介入即可自主迭代

“你要把Agent和代码库牢牢焊接在一起。要确保Agent与代码库结合后，明确知道如何验证修改、获取反馈，确保自身操作的有效性。”

实践场景示例：

• 带截图捕获标记的终端模拟器：新增--capture-to标记，让Agent可以截取屏幕截图，验证渲染修复效果
• 纯数据输出的CLI：开发新的子命令，仅输出原始数据（无UI格式化），便于Agent以编程方式解析结果
• 一键式测试命令：支持单命令执行测试（如pnpm test），并提供测试结果缓存能力

Agent优化与人类优化的差异领域

1. 命令行界面（CLI）

# 面向人类优化的CLI
- 交互式提示
- 彩色输出
- 进度条
- 帮助文本与菜单

# 面向Agent优化的CLI
- 单命令界面（例如`pnpm test`）
- 机器可读输出
- 结果缓存
- 最小化冗余输出

2. 文档与知识库

# 面向人类优化的文档
- 叙事性说明
- 教程与指南
- 截图与示意图

# 面向Agent优化的文档
- 结构化参考文档
- 代码示例
- 清晰的输入/输出格式
- 封装工作流的技能

3. 测试与验证

# 面向人类优化的测试
- 描述性测试名称
- 实用的错误提示
- 调试输出

# 面向Agent优化的测试
- 快速执行
- 结果缓存
- 清晰的通过/失败信号
- 自动化修复建议

4. 技能与能力

最具影响力的优化方向：构建可封装代码库独特操作的技能。

以AMP项目为例：

• 用于日志分析的GCloud技能（替代Web仪表板的需求）
• 用于数据查询的BigQuery技能
• 发布管理技能
• 部署技能

5. Agents.md 文件

创建AGENTS.md或类似文档，明确说明以下内容：

• 如何测试应用
• 如何完成身份验证
• 应使用哪些反馈机制
• 自动化交互的特殊注意事项

“原生Agent代码库”检查清单（对应乔尔·斯波尔斯基测试的2026年版本）

| 乔尔测试（2004年） | Agent测试（2026年） | |-------------------|-------------------| | 新人能否在第一天就交付成果？ | Agent能否在10分钟内交付成果？ | | 一键式开发环境搭建 | 一键式测试/验证流程 | | 易于推送至生产环境 | 便于Agent部署与验证 | | 易于代码评审 | 便于Agent自我验证 | | 持续集成（CI）运行测试 | 持续集成（CI）提供机器可读的反馈 | | 完善的文档 | 包含工作流说明的AGENTS.md |

决策框架

当需要在面向人类与面向Agent的优化间做选择时：

| 问题 | 是 → | 否 → | |----------|----------|---------| | 人类是否每日使用该功能？ | 考虑混合优化 | 优先为Agent优化 | | Agent的使用频率是否是人类的10倍以上？ | 优先为Agent优化 | 保留面向人类的开发者体验（DX） | | 这是核心开发者工作流吗？ | 采用混合方案 | 优先面向Agent | | 该功能是否需要人类判断？ | 优先面向人类 | 优先面向Agent |

滚雪球效应的实际体现

1. 针对Agent优化工具（可适当降低面向人类的开发者体验）
2. Agent的效能提升
3. 人类更多使用Agent，更少直接操作工具
4. 面向人类的开发者体验重要性降低（无需频繁操作编辑器）
5. 拥有更多空间为Agent优化
6. 重复上述循环

优势：

• 大幅提升Agent性能：Agent运行速度更快、可靠性更高
• 加速向Agent优先工作流转型：激励用户以Agent替代人工操作
• 面向未来兼容：为代码库适配更高程度的AI自主性奠定基础
• 复合式正向循环：更优质的Agent → 更高使用频次 → 更多资源投入 → 更优质的Agent

劣势：

• 人类开发者体验（DX）倒退：传统工作流的使用体验可能变差
• 团队抵触情绪：开发者可能抗拒这类“体验不佳”的工具
• 混合团队适配挑战：部分团队成员可能不会高频使用Agent
• 技术锁定风险：针对Agent专属模式的大量投入可能导致技术锁定

认知转变：

“Agent的兴起，并不意味着那些复杂的构建工具与可复现构建方案会成为最终赢家。我反倒认为，Agent特别擅长使用简单的傻瓜式工具——根本不需要那些复杂笨重的工具。”

Agent适配简单、可靠的“傻瓜式”工具表现极佳。为人类设计的复杂工具往往会增加不必要的额外开销。

适合为Agent优化的场景：

• Agent使用某一工作流的频次是人类的10倍以上
• 工作流具备可自动化属性且定义清晰
• 速度优先级高于用户体验
• 已明确采用Agent优先的开发策略

适合保留人类开发者体验的场景：

• 工作流需要人类的创造力或主观判断力
• 人类是核心使用者（Agent极少涉及该工作流）
• 工作流处于探索阶段或定义模糊
• 团队尚未完全认同Agent优先的发展方向