3个月457个PR|看OpenAI团队如何把Skills写代码用到极致
Source: http://x.com/i/article/2033078289603121152
大多数团队用 AI 做工程的方式是这样的:
Copilot 补全几行代码,Review 还是人一行行看。 CI 挂了,人去查日志。文档过期了,人去补。 发布前检查?人做。Changeset 验证?人做。PR 描述?还是人写。
AI 是用上了,但工作流没变。
写代码快了一点,其他所有事还是一样慢。
OpenAI Agents SDK 团队做了一件不一样的事。
他们不是让 AI 写更多代码——他们让 AI 接管了代码之外的几乎所有重复性工程劳动。
验证、审查、发布检查、文档同步、PR Review……全部系统化交给 Codex。
3个月,两个仓库合并了 457 个 PR。方案已经公开。
非常值得拆开看看。
一、先看数字
2025年12月到2026年2月,对比此前三个月:
- Python 仓库:182 → 226 个 PR
- TypeScript 仓库:134 → 231 个 PR
这两个仓库不是小项目。截至2026年3月,Python 包 30 天内约 1470 万次 PyPI 下载,TypeScript 包约 150 万次 npm 下载。
提升不是靠加人。
是靠改工作流。
怎么改的?
二、三样东西,管住整个仓库
整套方案极简,只有三个核心组件:
shell
仓库/
├── AGENTS.md # 仓库级策略:什么时候必须做什么
├── .agents/skills/ # 本地 Skills:每个是一小段可执行的知识包
│ ├── skill-a/
│ │ ├── SKILL.md
│ │ ├── scripts/
│ │ └── references/
│ └── skill-b/
│ └── ...
└── GitHub Actions # CI 中运行时接入
核心思路:给 Codex 稳定的仓库上下文,让重复性工程工作的速度和准确性都上来。
听起来简单。
但设计细节里全是讲究。
三、Skills:把「怎么干活」放在代码旁边
一个 Skill = 一个 SKILL.md 清单 + 可选的 scripts/ 和 references/。
关键设计:渐进式披露。
Codex 不会一开始就把所有上下文塞进去。流程是:
先看 name 和 description → 选中后加载 SKILL.md → 需要时才读参考资料或跑脚本。
这和大多数人用 AI 的方式正好相反。
大多数人恨不得把所有信息一股脑丢给模型,然后祈祷它能理解。
OpenAI 的做法是:先给最少的信息,让模型自己判断需要什么,再按需加载。
Python 仓库的 Skills 包括:implementation-strategy、code-change-verification、openai-knowledge、pr-draft-summary、docs-sync、test-coverage-improver 等。
JavaScript 仓库额外增加了:changeset-validation、examples-auto-run、integration-tests、release-review。
比具体列表更重要的是模式:每个 Skill 都有明确的契约、清晰的触发条件、具体的输出。
还有一个值得注意的设计:最有用的 Skills 不是硬性门禁。
docs-sync 和 test-coverage-improver 是「先报告再动手」的工作流——检查 diff 或覆盖率,排优先级,征得批准后才编辑。
这比让 AI 直接改东西安全得多。
先诊断,再下刀。这个原则不只适用于医学。
接下来是整篇文章里最实用的一个细节。
description 不是注释,是路由信号
SKILL.md frontmatter 里的 description,不是给人看的说明文字。
它是 Codex 启动时用来决定「要不要激活这个 Skill」的唯一依据。完整的 SKILL.md 和脚本只在被选中后才加载。
看 code-change-verification 的对比:
太模糊:
description: Run the mandatory verification stack in the OpenAI Agents JS monorepo.
实际使用的:
description: Run the mandatory verification stack when changes affect runtime code, tests, or build/test behavior in the OpenAI Agents JS monorepo.
短版本说了做什么,但没说什么时候触发、什么类型的变更该触发、检查是否可选。
长版本三个都回答了。
再看 pr-draft-summary:
太模糊:
description: Create a PR title and draft description for a pull request.
实际使用的:
description: Create a PR title and draft description after substantive code changes are finished. Trigger when wrapping up a moderate-or-larger change (runtime code, tests, build config, docs with behavior impact) and you need the PR-ready summary block with change summary plus PR draft text.
这告诉 Codex 三件事:这是任务结束时的 Skill;适用于实质性变更而非每次对话;输出是结构化的 PR-ready 块。
如果 Skill 触发不准,第一件事不是加代码——是改 description。
模型做判断,脚本做机械活
什么时候该用脚本,什么时候该交给模型?
判断标准很简单:
模型每次都要重新摸索同一段 shell 命令 → 变成脚本。 任务依赖上下文、权衡或解释 → 留给模型。
格式化、lint、跑测试 → 脚本。 判断 PR 影响范围、评估发布风险、分析 diff → 模型。
脚本保证可重复,模型保证有判断力。各干各擅长的活。
四、AGENTS.md:让 Skill 从「可选」变成「必须」
Skills 本身是被动的。它们只是放在那里,等着被调用。
AGENTS.md 的作用是:在正确的时机,强制调用。
这个文件随代码库分发,在 Agent 开始工作前生效。规则全是简短的 if/then:
- 编辑运行时或 API 变更前 → 必须调用 `$implementation-strategy`
- 变更影响 SDK 代码、测试、示例或构建行为 → 必须调用 `$code-change-verification`
- JS 包变更影响发布元数据 → 必须调用 `$changeset-validation`
- 涉及 API 或平台集成 → 必须调用 `$openai-knowledge`
- 工作完成准备交接 → 必须调用 `$pr-draft-summary` 精简结构:
markdown
# AGENTS.md
## Project overview
- Core SDK code lives under `src/agents/` or `packages//src/`.
- Tests live under `tests/` or `packages//test/`.
- Sample apps live under `examples/`.
## Mandatory skill usage
- Use `$implementation-strategy` before editing runtime or API changes.
- Run `$code-change-verification` when runtime code, tests, examples,
or build/test behavior changes.
- Use `$openai-knowledge` for API or platform work.
- Use `$pr-draft-summary` when substantial code work is ready for review.
## Build and test commands
- Python: `make format`, `make lint`, `make typecheck`, `make tests`
- TypeScript: `pnpm i`, `pnpm build`, `pnpm -r build-check`, `pnpm lint`, `pnpm test`
## Compatibility rules
- Preserve positional compatibility for public constructors and dataclass fields.
Python 仓库还在 AGENTS.md 里记录了公共 API 兼容性规则:保持导出构造函数参数和 dataclass 字段的位置含义,新增可选参数追加在末尾,不得不调整顺序就加兼容性测试。
把发布关键的兼容性规则和 Skill 触发条件放在同一个文件里——这个做法值得抄。
验证规则也藏着一个重要设计。
`$code-change-verification` 不是「每次都跑全套验证」。
是:代码变了才跑。但跑了没过,就不能说完成。
条件触发 → 纯文档 PR 保持轻量。 强制通过 → 代码变更不能绕过标准检查。
不该验证的,一秒都不浪费。该验证的,一步都不能跳。
Python 验证栈:
make format → make lint → make typecheck → make tests
JavaScript 验证栈(严格顺序):
pnpm i → pnpm build → pnpm -r build-check → pnpm -r -F "
@openai
/*" dist:check → pnpm lint → pnpm test
Skill 编码了「已验证」的定义。AGENTS.md 让这个定义可强制执行。
两层分离,非常干净。 JavaScript 仓库还有一个额外的强制步骤:`$changeset-validation`。
当 `packages/` 或 `.changeset/` 变更时,模型必须创建或更新正确的 changeset,验证 bump 级别,确认 changeset 匹配 diff。
不是检查文件存不存在——是让 Codex 对 git diff 做判断。
几条仓库特定策略:
- 已有分支 changeset 就复用,不新建
- 摘要一行,Conventional Commit 格式,可直接当 commit 标题
- 1.0 前避免 major bump;preview-only 新增不改变现有行为则视为 patch
- 根据实际包变更验证 bump 级别
Codex 在声称完成之前,必须先验证自己创建的发布元数据。这个约束很关键。
五、最有意思的部分:让 AI 验证 AI
如果前面是「怎么管」,这一节是「怎么验」。
这是整套方案里最精彩的设计。
第一层:examples-auto-run
以前验证示例靠人工——跑一遍,肉眼看日志,判断输出对不对。
一个示例还行,几十个不可持续。
团队先构建了非交互式执行的底层支持:auto 回复交互提示、auto 审批 HITL/MCP/apply_patch、不适合自动化的放 skip 列表、写结构化日志、生成重跑文件。
然后关键的一步:runner 只负责执行和保存日志。验证交给 Codex 逐个对照源码来做。
Codex 怎么验证?
- 读示例源码和注释
- 推断预期流程
- 打开对应日志
- 比较预期行为 vs 实际 stdout/stderr
- 每个成功的示例都做,不是抽查
为什么不在脚本层面写断言?
因为对于调用真实 API、使用工具或产生结构化输出的示例,退出码为 0 根本不够。模型能根据上下文判断「这个输出合不合理」,固定断言做不到。
脚本让运行可重复、保存证据。模型用证据做比 pass/fail 更精细的判断。这就是组合的价值。
第二层:integration-tests(JavaScript 仓库)
更进一步——把包发布到本地 Verdaccio registry,在 Node.js、Bun、Deno、Cloudflare Workers、Vite React 应用等多个环境下测试安装和运行。
捕获的是完全不同类别的问题:不是「示例在仓库里能跑吗」,而是「包在发布、安装、运行后还正常吗」。
第三层:release-review
找到上一个 release tag → 与最新 main 做 diff → 让 Codex 检查向后兼容性、回归、缺失的迁移说明 → 做出发布就绪判断。
看一个真实例子(PR #2480):
Release call: 🟢 GREEN LIGHT TO SHIP. Minor-version bump includes expected breaking change (Python 3.9 drop) with no concrete regressions found. Python 3.9 support removed - Risk: 🟡 MODERATE. Users pinned to Python 3.9 will be unable to install 0.9.0. - Evidence: pyproject.toml now sets requires-python = ">=3.10" - Action: Ensure release notes clearly call out the Python 3.9 drop.
设计原则:review 从「可安全发布」开始,仅当 diff 中有具体证据才切换为阻塞,每个阻塞必须附解除清单。
安全就说安全,不安全就指证据和后续步骤。
比泛泛的「请审查一下这个发布」有用一万倍。
PR Review 的分工
最后说一个很多人会关心的问题:Codex 做 Review,人还需要做什么?
答案是:都做,但做不同的事。
Codex 负责的审查:
- 直接的 bug、回归、缺失测试
- 反复检查相同的正确性模式
- 小修复和常规改进的审查
这些事它做得非常一致,比人可靠。
人负责的审查:
- API/架构变更——多种合理设计,需要维护者做选择
- 行为变更——影响产品预期、兼容承诺或发布策略
- 命名/迁移/发布沟通——难点在于选择对用户最清晰的方案
- 跨团队对齐——范围划定、排序、决定什么现在发什么以后发 重复性审查不再阻塞在稀缺的 reviewer 时间上。维护者专注于判断力真正有价值的审查。
这个分工本身,就是吞吐量提升的主要来源之一。
六、你可以带走的三个模式
拆完整套方案,核心就三件事:
1. 声明式控制
用 AGENTS.md 的 if/then 规则强制 Skill 调用——不是建议,是必须。
description 是路由信号,不是注释——写清楚什么时候触发、什么类型的变更、什么输出。
兼容性规则和触发条件放同一个文件,随代码分发。
2. 分层执行
脚本做机械活,模型做判断。重复摸索的 shell 命令下沉为脚本,依赖上下文的判断留给模型。
验证两层分离:条件触发(不浪费轻量 PR 的时间)+ 强制通过(代码变更不能绕过)。
3. 安全模式
最有用的 Skill 不是上来就改——检查、排序、征得同意再编辑。
release review 从「安全」开始,只在有具体证据时阻塞,阻塞必须附解除清单。
本地跑稳了再进 CI——手动使用阶段是发现边界情况的地方。
不需要一次全搞。
从一个高频重复的工作流开始。写一个 Skill,在 AGENTS.md 里加一条 if/then 规则,跑几轮看效果。
大多数团队让 AI 写代码。 少数团队让 AI 管住整个工程流程。
区别不在于用了什么模型。 在于有没有一套系统,让 AI 知道什么时候该做什么、做完怎么验证、验证没过怎么办。
这套方案的本质不是「让 AI 写更多代码」,是让 AI 接管代码之外的一切重复性工程劳动。
这才是 AI 工程化的正确打开方式。
如果这篇拆解对你有帮助,欢迎转发给你的团队一起看。
Reference: