• 平均每人每天3.5 个 PR
• 5 个月累计1500+ PR
• 全部通过 Agent 自审完成

把 AI Agent 从"野马"变成"赛马"

模式 1：AGENTS.md 作为目录，不是百科全书

核心做法

错误做法 vs 正确做法

OpenAI 踩过的坑

"Instead of treating AGENTS.md as the encyclopedia, we treat it as the table of contents."

落地三步走

Step 1：重构现有 AGENTS.md

• 保留：项目结构、build/test/lint 命令、禁区、Done Criteria
• 移除：详细规范、流程说明、背景知识
• 添加：指向 docs/ 目录的导航链接

Step 2：创建 docs/ 目录结构

docs/├── architecture/    # 架构文档├── design/          # 设计文档├── quality/         # 质量文档├── plans/           # 执行计划├── runbooks/        # 运维手册└── testing/         # 测试规范

Step 3：设置文档检查 CI

• 验证交叉链接有效性
• 检测过时文档（如代码变更但文档未更新）
• 扫描孤立文档（无其他文档引用）

核心判断

如果 Agent 需要阅读超过 500 行规则才能开始工作，说明规则组织方式有问题。

模式 2：架构分层强制执行，不是建议

核心做法

错误做法 vs 正确做法

OpenAI 的刚性架构

• 每个业务域分为固定层级：

• 代码只能"向前"依赖（不能反向或跨层）
• 跨域关注点（auth、connectors、telemetry、feature flags）通过Providers单一接口进入
• 其他依赖方式一律禁止，机械执行

"This is the kind of architecture you usually postpone until you have hundreds of engineers. With coding agents, it's an early prerequisite."

落地三步走

Step 1：定义架构分层

# 示例：电商订单域Order.Types      # 数据类型定义Order.Config     # 配置管理Order.Repo       # 数据访问层Order.Service    # 业务逻辑层Order.Runtime    # 运行时服务Order.UI         # 用户界面

Step 2：编写自定义 Linter

• 检查依赖方向（只能向前）
• 检查跨域访问（必须通过 Providers）
• 检查文件大小限制
• 检查命名规范

Step 3：集成到 Agent 工作流

• 预执行检查：生成代码前验证架构约束
• 后执行检查：提交前运行结构测试
• 错误信息包含修复建议

核心判断

如果架构违规需要人工 Code Review 才能发现，说明约束不够机械。

模式 3：可观测性对 Agent 可见，不是黑盒

核心做法

错误做法 vs 正确做法

OpenAI 实践

• 应用可 bootable per git worktree
• 可观测栈对 Agent 可见

"ensure service startup completes in under 800ms" "no span in these four critical user journeys exceeds two seconds"

落地三步走

Step 1：搭建轻量可观测栈

• 日志：Loki + LogQL
• 指标：Prometheus + PromQL
• 链路：Tempo 或 Jaeger

Step 2：集成到 Agent 工具集

• 添加 query_logs(expression) 工具
• 添加 query_metrics(expression) 工具
• 添加 check_slo(service, metric, threshold) 工具

Step 3：定义性能目标

• 服务启动时间 < 800ms
• 关键路径延迟 < 2 秒
• 错误率 < 0.1%

核心判断

如果性能问题需要人工查看日志后告诉 Agent 修复，说明可观测性没有真正对 Agent 可见。

模式 4：UI 对 Agent 可见，不是截图

核心做法

错误做法 vs 正确做法

OpenAI 实践

• DOM 快照：Agent 可以获取当前页面 DOM 结构
• 截图：Agent 可以截取当前页面状态
• 导航：Agent 可以点击、输入、滚动等操作

• 直接复现 bug
• 验证 UI 修复
• 推理 UI 行为

落地三步走

Step 1：接入浏览器自动化工具

• Puppeteer 或 Playwright
• 通过 Chrome DevTools Protocol 控制

Step 2：封装 UI 操作 Skills

• navigate(url)：导航到指定 URL
• screenshot(element)：截取元素或页面截图
• query_dom(selector)：查询 DOM 元素
• click(selector)：点击元素
• type(selector, text)：输入文本

Step 3：定义 UI 验证任务

• "登录页在 Safari 下提交后 spinner 应该消失"
• "点击提交按钮后应该显示成功提示"
• "表单验证错误应该显示在输入框下方"

核心判断

如果 UI bug 需要人工复现后告诉 Agent，说明 UI 没有真正对 Agent 可见。

模式 5：Doc Gardening Agent，不是人工维护

核心做法

错误做法 vs 正确做法

OpenAI 实践

"A recurring 'doc-gardening' agent scans for stale or obsolete documentation that does not reflect the real code behavior and opens fix-up pull requests."

• 过时的 API 文档
• 与实际行为不符的设计文档
• 引用的代码已变更的说明
• 孤立的、无其他文档引用的内容

落地三步走

Step 1：定义文档新鲜度指标

• 文档最后更新时间 vs 代码最后变更时间
• 文档引用的代码是否存在
• 文档描述的 API 是否匹配实际签名

Step 2：创建 Doc Gardening Agent

• 定期扫描（如每天或每周）
• 对比文档与实际代码
• 发现不一致时创建修复任务

Step 3：设置修复工作流

• 小改动：Agent 直接修复并提交
• 大改动：Agent 创建 PR，人工 Review
• 无法判断：Agent 标记为需要人工审查

核心判断

如果文档过时问题需要人工发现后才修复，说明文档维护机制不够主动。

总结：5 个模式的共同特征

把"希望 Agent 记得做"升级为"系统保证一定会做"。

#HarnessEngineering #AIAgent #CodingAgent #OpenAI