从 Vibe Coding 到 Agentic Coding，OpenAI 自己是怎么做的

仓库地址：https://github.com/openai/openai-agents-python

前段时间 Andrej Karpathy 提了个 Vibe Coding 的概念，大意就是别管代码细节了，跟着感觉让 AI 写就完了。这个词火了一阵，但越来越多人发现：光靠 vibe 写出来的东西，demo 能跑，上生产就炸。最近社区开始聊一个新词叫 Agentic Coding——不是让你对着 AI 许愿，而是把 AI 当成一个有流程、有边界、能被审计的工程角色来用。OpenAI 自己的一个开源仓库，刚好就是这个思路的完整样板。

很多人把 AI 写代码这件事，仅仅理解为一个更聪明的“代码补全工具”：你丢一个需求，它处理一段代码，然后你再祈祷它测试能过。甚至有的人的代码里面连测试都没有接入，需要人肉来完成这个测试。

但在 OpenAI 的这个项目仓库里，它展示了另一种更为工程化的用法。他们把 Codex 当作一个有明确工作边界、产物可审计、且能嵌入 CI 的工具。

更重要的是，他们把这一套如何让 AI 可靠地维护项目的方法，直接写到了这个仓库结构里。所以今天我们来看一看，OpenAI 的这个仓库是如何把一个代码仓库改造成对 AI Coding Agent 友好的。

1）三类“说明书”

在这个仓库里面，它的这套方案设计可以拆成三层，每一层都有一些明确的落点文件：

仓库级作战手册：AGENTS.md
复杂任务的执行模板：PLANS.md（ExecPlan）
可复用的技能库：.agents/skills/*

它们共同解决同一个问题：让 AI 不只会写代码，还会按你的工程习惯工作。

2）用 `AGENTS.md` 把“项目潜规则”显式化

你可以把 AGENTS.md 理解为给 AI Agent 的系统提示词。它不应该是一个空泛的文件，而是一个用来防止仓库被“搞炸”、变成“屎山”的规则文件。

什么时候必须跑完整验证（format/lint/typecheck/tests），什么时候可以跳过。
哪些目录是“核心运行时”，改动要格外谨慎。
哪些东西算“兼容性边界”（比如公共 API 的参数顺序、序列化 RunState 等），不要随意破坏。
推荐的开发命令（统一 make + uv run），让人和 AI 都能按同一套入口做事。

这件事的价值在于：把隐性的“团队共识”变成显性的“仓库契约”。AI 再聪明，也不可能凭空猜到你们团队对“完成”的定义是什么。

3）用 `PLANS.md` 让 AI 先写“可执行计划”，再动手

PLANS.md 定义了一个叫 ExecPlan（Codex Execution Plan） 的东西。

它本质上是一份“活的规格说明书”，要求做到：

自包含：新人只看这份计划就能把活干完（不依赖口口相传）。
可验证：每个阶段都要写清楚“怎么证明它真的能工作”。
可追溯：必须维护 Progress / Decision Log / Surprises / Outcomes。

这非常反直觉：很多人觉得“计划”会拖慢 AI 写代码的速度。

但真正的工程效率，往往在以下三件事上面会踩坑：

需求没写清，AI（或人）做错方向
做到一半发现兼容性/边界问题，被迫返工
缺少验证步骤，最后靠祈祷合并

ExecPlan 的设计，等于把“AI 的思考过程”外化成可审阅的文档，让它从“黑箱输出”变成“可协作的执行过程”。

4）沉淀 `.agents/skills`，让 AI 有“工具箱”

那接下来讲的就是 .agents/skills 这个目录，这也是前一段时间非常火的关于 skills 的这套东西。

它不是一句“请跑测试”那么简单，而是把我们高频的这些动作封装成标准的流程，也就是我们常说的 SOP。例如它这边这个仓库有这些 skills：

code-change-verification：规定必须按顺序跑 make format → make lint → make typecheck → make tests，并提供跨平台脚本入口。
implementation-strategy：在改公共 API / 运行时行为前，先用“最新 release tag”作为兼容性边界做判断：哪些要兼容，哪些可以直接重写。
final-release-review：给出一套确定性的发版审查清单（什么时候 Green light，什么时候 Blocked），避免“凭感觉卡发布”。
pr-draft-summary：改完后自动产出 PR title + PR 描述模板，减少“最后写 PR 文案”的摩擦。
docs-sync：把“代码变了但文档没变”的痛点流程化，而且明确要求：只改英文 docs，翻译目录不要碰（降低误伤）。
examples-auto-run：把 examples 的自动运行、日志收集、失败重跑做成一套脚本化流程，甚至连“通过了也要人工核对日志”都写进规范里。

你会发现他们在做一件事：把“仓库维护”拆成一组可组合的子任务，然后给每个子任务一个确定输入/输出/步骤。

这比“让 AI 自己想怎么做”靠谱得多。

5）把 Codex 接进 CI：让它输出结构化结果，再交给脚本落地

仓库里面还有一个很关键的实现，就是他们不只是在本地教 AI 怎么干活，还要把 Codex 直接接入 GitHub Actions。

你能在这些文件里看到完整链路：

PR 自动打标签：.github/workflows/pr-labels.yml + .github/codex/prompts/pr-labels.md
- CI 收集 PR diff 和改动文件列表
- Codex 只负责输出一个严格 JSON：{"labels":[...]}
- 后续由脚本把标签真正应用到 PR
发版审查报告：.github/workflows/release-pr.yml / .github/workflows/release-pr-update.yml + .github/codex/prompts/release-review.md
- Codex 按固定格式输出 release readiness report
- 报告直接作为 release PR 的 body（而不是散落在聊天记录里）

这一步的核心思想是：

让 Codex 做“判断与总结”，让脚本做“执行与落地”。

它把 AI 的不确定性关在“可审阅文本/结构化 JSON”里，把真正危险的写操作交给可控脚本。

6）安全细节很值得学：他们默认不信任“带 secrets 的 CI”

把 AI 接进 CI，很多团队第一反应是担心安全。

这个仓库给了几个很实操的安全姿势（你都能在 workflow 里看到）：

运行 Codex 时用 read-only sandbox，并配 drop-sudo（降权）。
PR 自动标注用 pull_request_target，但会检测是否 fork；fork PR 会跳过 Codex，避免在有 secrets 的上下文执行不可信代码。
任务设计“偏保守”：比如打标签明确要求 宁可漏标也不要错标（prefer false negatives）。

这套思路其实可以总结成一句话：

宁可让 AI 少做点，也不要让它做错后难以察觉。

7）准备抄作业了吗？

当然，这一套方法肯定不是万能的，也不是适应所有仓库的，但仍然是一个很好的学习案例。

你可以去尝试着调整自己仓库里的这些 AI 交流和协作规范的 Markdown 文件，然后自己去测试。你可以从最简单的一步开始，写好你的 AGENTS.md，然后在项目中再去验证。

看到 AI 是不是真的变聪明了，我觉得这个过程你会有调教 AI 让他变聪明的那种成就感。

彩蛋：他们不仅用 Codex 维护仓库，还把 Codex 变成 SDK 里的一个 Tool

更有意思的是，这个 SDK 里还有一个实验功能：codex_tool，把 Codex CLI 包成一个 tool，让 agent 在一次 run 里把“限定范围的代码工作”委托给 Codex 去做（例如跑命令、改文件、用 MCP 拉资料），然后把结果带回来继续推理。

你能在 docs/tools.md 里看到完整说明，也能在 examples/tools/codex.py、examples/tools/codex_same_thread.py 里看到可运行示例。

我把它当成一个信号：OpenAI 在“吃自己的狗粮”——Codex 不只是写 SDK 的工具，也被他们当成 Agents SDK 生态里的一个可组合模块。

结语：AI agent 不是“写代码的魔法”，而是一套可被工程化的流程

我一直觉得 AI Coding Agent 真正的门槛不在于模型能力（当然这也很重要），不过团队有没有把它当作一个真正的工程角色去设计，我觉得这会更重要。

openai/openai-agents-python 这个仓库给了我们一个示范：

用 AGENTS.md 把规则写清楚
用 ExecPlan 把复杂任务做成可执行、可验收的计划
用 skills 把高频动作封装成可复用的工作流
用 CI + sandbox 把 AI 的输出变成可落地、可控的自动化

如果你今天只想从最小的一件事开始：先给自己的仓库写一份 AGENTS.md。