Subagents、AGENTS.md、Skills 与 MCP

版本说明：本文基于 OpenAI 官方 Codex 文档于 2026-03-22 核对。

1. 先分清这 5 个概念

概念	它解决什么问题	最适合什么时候用
`AGENTS.md`	让 Codex 记住你的长期规则和项目约束	每个仓库都应该有
`Skills`	把一类经验、流程、模板打包复用	团队有重复工作时
`MCP`	给 Codex 接外部工具和数据源	需要 Figma、数据库、浏览器、内部系统时
`Subagents`	把一个复杂任务拆给多个代理并行处理	并行探索、并行审查、分工实现
`Automations`	让 Codex 定时、后台、重复地跑任务	巡检、日报、变更总结、批量处理

把它们放在一起看，关系其实很清楚：

flowchart LR
  A["AGENTS.md<br/>长期规则"] --> B["主线程 Codex"]
  C["Skills<br/>可复用流程"] --> B
  D["MCP<br/>外部工具能力"] --> B
  B --> E["Subagents<br/>并行分工"]
  C --> F["Automations<br/>定时任务"]
  D --> F

2. Subagents 是什么

OpenAI 官方 Subagents 文档给出的核心意思很直接：

Codex 可以并行启动多个专门代理，再把结果汇总回主线程
这对“高并行复杂任务”尤其有用，例如 代码库探索、多步骤特性实现、分维度代码审查

同时，官方也明确提示了 3 个现实约束：

Subagents 只有在你明确要求时才会启动。
每个 subagent 都会独立消耗模型与工具资源，所以成本会更高。
当前可见性主要在 Codex App 和 CLI，IDE 扩展的可见性还在完善中。

3. 什么时候值得用 Subagents

适合：

一个 PR 想分开看 安全 / 代码质量 / Bug / 测试
一个大仓库需要并行探索多个目录
一个任务天然能拆成 实现 / 文档 / 测试 / 验证

不适合：

只是改一个按钮文案
只是修一个已知小 bug
当前上下文和验收标准本身还不清楚

4. 如何定义自定义 Subagents

官方文档说明，自定义代理要放在：

个人级：~/.codex/agents/
项目级：.codex/agents/

每个自定义代理都是一个独立的 TOML 文件，至少要定义：

name
description
developer_instructions

你还可以继续补：

model
model_reasoning_effort
sandbox_mode
mcp_servers
skills.config

一个最小示例如下：

toml

name = "reviewer"
description = "PR reviewer focused on correctness, security, and missing tests."
developer_instructions = """
Review code like an owner.
Prioritize correctness, security, behavior regressions, and missing test coverage.
"""
nickname_candidates = ["Atlas", "Delta", "Echo"]

如果你要给课程或团队做分工，推荐先做 3 个最基础的代理：

reviewer：审查正确性、安全和测试缺口
frontend-explorer：只读探索前端结构与交互链路
backend-implementer：专注接口、数据库和服务端实现

5. AGENTS.md 是长期规则，不是临时提示词

官方 AGENTS.md 文档强调了两个关键点：

Codex 在开始工作前会先读 AGENTS.md
它会按 全局 -> 项目 -> 当前子目录 的顺序逐层拼接规则

这意味着 AGENTS.md 很适合放下面这些内容：

修改代码后必须跑哪些命令
团队默认用什么包管理器
新增依赖前是否必须确认
哪些目录不要碰
哪些文档改动必须同步更新

一个非常实用的仓库级示例：

# AGENTS.md

## Repository expectations

- Run `npm run lint` before opening a pull request.
- Document public utilities in `docs/` when you change behavior.
- Do not hardcode API keys.
- Prefer small, reviewable diffs over large rewrites.

6. Skills 与 MCP 怎么配

最容易搞混的是 Skills 和 MCP：

Skills 更像“做事的方法”
MCP 更像“做事时能用的外部工具”

举个例子：

Figma 到代码 这件事里
- Skill 可以规定你先读设计、再拆组件、再验收
- MCP 则负责真正连到 Figma 拿设计数据

所以更实用的理解是：

Skill = 工作流模板

MCP = 能力接口

7. Automations 适合什么场景

官方 App 文档明确说明，Automations 可以和 Skills 组合，去完成常规巡检、报表、修复或变更总结。

在教学和团队里，特别适合这几类任务：

每天总结仓库最近改动
定时检查错误日志并输出待处理列表
生成课程项目的进度摘要
扫描指定目录是否缺少文档或测试

8. 给课程体系的落地建议

如果你是拿这套站点去做培训，我建议这样教：

初学阶段先只教 AGENTS.md
学会稳定协作后再教 Skills
需要外部工具时再引入 MCP
最后才上 Subagents 和 Automations

这样顺序最稳，因为它符合学习成本从低到高的节奏。

Subagents、AGENTS.md、Skills 与 MCP ​

1. 先分清这 5 个概念 ​

2. Subagents 是什么 ​

3. 什么时候值得用 Subagents ​

4. 如何定义自定义 Subagents ​

5. AGENTS.md 是长期规则，不是临时提示词 ​

6. Skills 与 MCP 怎么配 ​

7. Automations 适合什么场景 ​

8. 给课程体系的落地建议 ​

官方参考 ​