AI Agent 工程化实践：从 OpenAI、Anthropic 到个人助理的操作框架

2026 年 3 月，OpenAI 和 Anthropic 几乎同时发布了各自让 AI Agent 长时间自主工作的工程实践。我花了两周时间消化这些经验，结合自己运行个人 AI 助理的实战，提炼出一套可迁移的操作框架。这篇文章记录这个过程。

背景：三份关键材料

最近一周，三份材料让我重新审视了 Agent 的工程化问题：

OpenAI — Codex 团队的 Agent-first 实践

3 名工程师，5 个月，用 Codex 从零写了约 100 万行代码。没有一行人工编写。产品有真实日活用户。他们声称只用了手工编码 1/10 的时间。

Anthropic — 长时运行 Agent 的有效框架

解决了一个核心难题：Agent 的 context window 有限，复杂项目跨多个 session，每个新 session 像”新来的实习生，对之前发生了什么一无所知”。

Garry Tan — gstack

YC CEO 的 Claude Code 配置，用 AI 模拟完整工程团队（CEO/工程师/设计师/QA）。GitHub 近 2 万 stars。核心洞察不是 prompt 有多精妙，而是用组织架构思维编排 AI。

三份材料的结论高度一致：Agent 的瓶颈不是模型能力，而是环境设计。

核心洞察：OpenAI 教我们什么

AGENTS.md 是目录，不是百科全书

OpenAI 团队一开始尝试把所有规则塞进一个巨大的 AGENTS.md。失败了。原因很简单：

上下文是稀缺资源。一个巨大的指令文件会挤掉任务本身的空间
当一切都”重要”时，一切都不重要了
它会立即腐烂。没人维护的大文档就是规则的坟场

他们的解决方案：AGENTS.md 约 100 行，只是一张地图，指向更深层的文档。渐进式披露——Agent 从小入口开始，需要时才深入。

这让我想到我们日常写文档的误区：总觉得写得越多越好。对 Agent 来说恰恰相反——精准的地图比详尽的百科更有用。

代码仓库就是 Agent 的全部世界

OpenAI 团队说了一句让我印象深刻的话：

“存储在 Google Docs、聊天记录或人们头脑中的知识都无法被系统访问。”

对 Agent 来说，它在运行时无法访问的任何内容都是不存在的。那次让团队在架构上达成一致的 Slack 讨论？Agent 对它一无所知。

这意味着所有决策、原则、约定都必须沉淀到文件中。不是”最好沉淀”，是必须。否则每个新 session 都是从零开始。

约束是加速器，不是束缚

这是最反直觉的一条。

OpenAI 在项目初期就建立了严格的架构分层：Types → Config → Repo → Service → Runtime → UI，依赖方向单向，用自定义 linter 强制执行。

通常这种严格架构要等到团队有几百名工程师时才会建立。但对 Agent 来说，这是早期的先决条件。有了约束，速度才不会下降，架构才不会漂移。

他们的原则是：强制执行不变量，不微观管理实现方式。 不说”用 Zod 做校验”，而是说”在边界处解析数据形状”。约束划边界，边界内给自由。

AI 残渣需要 GC，不能靠周五清理

Agent 生成的代码会复现仓库中已有的模式——包括不够理想的。OpenAI 一开始安排每周五人工清理，很快发现不可扩展。

他们的解法：把”黄金原则”编码到仓库中，建立自动清理流程——像垃圾回收一样持续运行。技术债务就像高息贷款：持续小额偿还，总比累积后痛苦一次偿还要好。

核心洞察：Anthropic 教我们什么

两阶段解法

Anthropic 发现 Agent 在长时间项目中有两个典型失败模式：

做太多 — 尝试一口气实现整个功能，context 耗尽后留下半成品
过早宣布完成 — 看到有些进展就认为任务结束了

他们的方案是两阶段 Agent：

Initializer Agent（首次运行）：创建环境脚手架——init.sh 脚本、进度日志文件、功能清单、初始 git commit。

Coding Agent（每次后续运行）：读进度文件 → 读 git log → 跑基础测试 → 选一个未完成的功能 → 实现+测试 → commit → 更新进度 → 结束。

关键洞察：每次 session 只做一个功能，做完就提交。

Feature List 用 JSON 不用 Markdown

一个有趣的细节：功能清单用 JSON 格式，不用 Markdown。原因是模型更不容易”偷偷改”JSON 文件的结构。Markdown 太灵活，Agent 可能在”更新状态”时顺手改了功能定义。

{
  "description": "用户可以创建新对话",
  "steps": ["导航到主界面", "点击新建", "验证对话已创建"],
  "passes": false
}

规则很简单：只能改 passes 字段。删除或修改 feature 定义是不可接受的。

标记完成 ≠ 真的完成

Anthropic 观察到 Agent 经常标记一个功能为”完成”，但实际上没做 E2E 测试。它可能写了单元测试，甚至用 curl 打了 API，但没有验证端到端的用户流程。

解法：强制 Agent 使用浏览器自动化工具做真实用户测试。截图证据让 Agent 能发现代码层面看不出来的 bug。

核心洞察：gstack 教我们什么

Garry Tan 的 gstack 本质上是用组织架构思维编排 AI。13 个 Skill 模拟了一个完整团队：

CEO 模式：质疑需求本质（不是实现需求，是问”这真的是对的吗”）
工程师模式：架构、数据流、状态机
设计师模式：80 项审计 + AI Slop 检测
QA 模式：真实浏览器测试
文档模式：自动同步所有文档

核心原则是认知模式分离：CEO 模式不该看代码，Code Review 模式不该质疑产品方向。每种模式有自己的关注点和盲区，分开使用反而更高效。

另一个实用贡献是 AI Slop 检测——10 个反模式清单，专门识别 AI 生成的”看起来对但没有灵魂”的设计（蓝到紫渐变、3 列 icon grid、统一 border-radius…）。

我的框架：10 层 Agent 操作系统

综合以上经验，加上运行个人 AI 助理两周的实战，我提炼了一套 10 层框架。完整版本在 GitHub 的 system/agent-operating-framework.md，这里是精华版。

第 1 层：身份系统

三个文件定义一个 Agent：

SOUL.md — 人格、边界、语气。Agent 可以演化，但必须报告变更
USER.md — 服务对象信息。只有人类能改
IDENTITY.md — 名片（名字、角色、定位）

为什么需要这个？因为 Agent 每次启动都是空白的。身份文件是它的”出厂设置”，确保每次醒来都知道自己是谁、在为谁工作。

第 2 层：双层记忆

memory/YYYY-MM-DD.md  ← 日志（原始记录，只追加）
MEMORY.md              ← 长期记忆（定期从日志提炼，保持精炼）

日志是”发生了什么”，MEMORY.md 是”什么值得记住”。就像人类的日记和长期记忆的关系。

Session Startup 协议：每次启动，不问直接做——读 SOUL → 读 USER → 读今天和昨天的日志 → 读 MEMORY → 开始工作。

第 3 层：行为边界

简单的规则：读和写自由做；对外发布、花钱、删除必须先确认。

第 4 层：认知模式分离

从 gstack 提炼，加上 Anthropic 的测试和提交模式：

产品模式（30秒质疑需求）
→ 架构模式（10行方案）
→ 实现模式（每次只做一个功能）
→ 测试模式（E2E 验证）
→ 审计模式（找生产会炸的 bug）
→ 文档模式（同步受影响的文档）
→ 提交模式（commit + 更新 progress）

第 5 层：知识管理

AGENTS.md 是 100 行的目录，不是 3000 行的百科。指向 docs/、skills/、frameworks/ 中的深层文档。

第 6 层：工程约束

强制执行不变量，不微观管理。架构分层严格单向，用 lint 强制执行。

第 7 层：任务调度策略

这是实战中学到的成本优化：

能用 shell 命令？→ exec，$0
机械性批量操作？→ subagent (sonnet)，~$0.10-0.30
需要判断力？→ opus，~$0.50-2.00

主 session 是最贵的资源。大文件操作外包给子 Agent，主 session 专注于对话和决策。

第 8-10 层：迭代、协作、安全

迭代：每次工程任务后记录效果，积累数据后回顾。低分模式标记但不自动删除——由人类判断是模式问题还是评价体系问题
协作：Agent 间通过文件传递上下文，不越界，冲突升级给人类
安全：红线明确，绝不模糊

还没验证的部分

诚实地说，这个框架才跑了两周。有些部分还需要时间验证：

Feature List JSON — 还没在大型项目中实测。我们的项目规模目前不需要 200 个 feature 的清单。

Agent 审 Agent — OpenAI 声称把大部分 code review 交给了 Agent 互审。我们目前只有两个 Agent（VPS + Mac），还没试过互审。

自动文档清理 — OpenAI 有专门的 doc-gardening Agent。我们还是手动维护。

架构强制执行 — 我们的项目用了分层，但还没到用 lint 强制执行的程度。

计划是跑一个月后回来复盘，看哪些模式真的有效、哪些只是理论上好看。

可以直接用的东西

如果你也在用 AI Agent 做工程化工作，以下是我建议立刻采用的：

AGENTS.md 精简到 100 行以内，多余的拆到独立文档
每次 session 只做一个功能，做完就 commit
所有决策沉淀到文件，不依赖聊天记录
用 JSON 管理功能清单，不用 Markdown
区分 shell/sonnet/opus 三档任务，别什么都用最贵的模型

这些不需要复杂的基础设施，今天就能开始做。

后续

一个月后我会写后续文章，回顾这套框架的实际效果。到时候会有具体的数据：哪些模式用了、效果如何、改了什么。

框架的完整版本和所有变更历史都在 GitHub 上。如果你有自己的 Agent 工程化实践，欢迎交流。

参考来源：