OpenAI 的 Agent 优先开发实践：3 个工程师 5 个月写了百万行代码#

核心工程决策：

1. Agent 看不到的内容等于不存在 — 知识必须在代码库本身
2. 约束编码化而非文档化 — 编码进 Linter 或 CI 的约束才可执行
3. Agent 端到端自主完成任务 — 全链路不需要人介入
4. 最小化合并阻力 — 测试偶发失败用重跑处理，不阻塞进度

右上角（目标明确 + 结果可自动验证）是最适合 Agent 发挥的区域。

上下文分层#

三种压缩策略#

会话管理的五种分支#

出错时 rewind 往往比 correct 更稳。 错误路径留在上下文里会继续干扰推理。

Skill 描述要包含反例#

没有反例时准确率从 73% 掉到 53%，加上反例后升到 85%，响应时间还降了 18.1%。

Skill 描述优化#

1
# 低效（~45 tokens）
2
description: 很长的一段功能介绍...
3

4
# 高效（~9 tokens）
5
description: Use when deploying to production or rolling back.

Compact Instructions 模板#

1
保留优先级：
2
1. 架构决策，不得摘要
3
2. 已修改文件和关键变更
4
3. 验证状态，pass/fail
5
4. 未解决的 TODO 和回滚笔记
6
5. 工具输出，可删，只保留 pass/fail 结论

ACI（Agent-Computer Interface）原则#

工具设计三阶段演进#

1. 第一代：API 封装 — 粒度过细
2. 第二代：ACI — 工具应对应 Agent 的目标
3. 第三代：Advanced Tool Use
   • Tool Search：动态工具发现，上下文保留率 95%
   • Programmatic Tool Calling：代码编排，token 从 150K 降到 ~2K
   • Tool Use Examples：示例驱动，准确率从 72% 提升到 90%

四种记忆#

记忆整合触发#

tokenUsage / maxTokens >= 0.5 时触发：

• 成功：摘要追加到 MEMORY.md
• 失败：原始消息写入 archive/ 保留完整历史

放权顺序（不能反）#

1. Harness — 验收基线、执行边界、反馈信号、回退手段
2. 回退能力 — Provider 切换、工作空间隔离、白名单、审计日志
3. 放权 — 敏感操作显式确认、关键路径加独立 LLM 复核

长任务跨 session 继续#

• Initializer Agent：生成 feature-list.json、init.sh、claude-progress.txt
• Coding Agent：从文件恢复现场，实现功能，跑测试，更新状态
• 进度放在文件里，不要放在上下文里

子 Agent 通信协议#

1
{
2
  request_id, from_agent, to_agent,
3
  content, status: 'pending' | 'approved' | 'rejected',
4
  timestamp
5
}

• 写入 .team/inbox/{agentId}.jsonl，append-only，崩溃可恢复
• 子 Agent 只回传摘要，搜索和调试细节留在自己上下文

多 Agent 下幻觉会互相放大#

Agent A 带偏 → Agent B 跟着强化 → Agent C 再叠加 → 所有 Agent 收敛到同一个高置信度的错误结论。

用交叉验证打断这条链。

关键指标#

三类评分器#

从零搭评测体系#

• 20~50 个真实失败案例就够启动
• 先评测再改 Agent — 看到分数下降先查环境，再动 Agent
• 环境隔离：每次从干净状态开始，测试之间不能共享缓存/临时文件
• 测试用例要同时覆盖正例和反例

Trace 需要记录#

1
每次 Agent 运行：
2
├── 完整 Prompt（含系统提示）
3
├── 多轮交互的完整 messages[]
4
├── 每次工具调用 + 参数 + 返回值
5
├── 推理链（如有 thinking 模式）
6
├── 最终输出
7
└── token 消耗 + 延迟

两层可观测性#

1. 人工抽样标注 — 摸清失败模式，提供校准数据
2. LLM 自动评估 — 全量覆盖，以第一层校准

在线评测采样规则#

• 负反馈触发：100% 进队列
• 高成本对话：token 超过阈值优先审查
• 时间窗口采样：每天固定时间段随机采
• 模型/Prompt 变更后：头 48 小时全量审查

五层解耦架构#

系统提示按层叠加#

SOUL.md 定义身份、约束和完成标准，再按层加载：平台信息 → 身份层 → 记忆层 → Skills 层 → 运行时注入。

安全和可用性两层兜底#

• Prompt Injection：source-sink 拆、最小权限、不可信输入显式标注
• Provider 故障切换：Anthropic → OpenAI → Sonnet 逐级 fallback