定制 Codex 行为

Customization 的目标，是让 Codex 按你和团队的工作方式运行。它不是多装功能，而是把长期规则、重复流程、外部系统和角色分工放到正确层级。

行为定制先从 AGENTS.md 和验证命令开始。不要在项目规则还不清楚时先堆 MCP、skills 和 subagents。

Customization

官方定制能力总览。

AGENTS.md

长期项目规则应该先写进 AGENTS.md。

Skills and MCP

区分可复用流程、外部工具和角色分工。

五层地图

flowchart LR
    Agents["AGENTS.md"] --> Behavior["Codex behavior"]
    Memories["Memories"] --> Behavior
    Skills["Skills"] --> Behavior
    MCP["MCP"] --> Behavior
    Subagents["Subagents"] --> Behavior

这几层互补，不竞争：

AGENTS.md：持久项目指导。
Memories：从过去工作中延续有用上下文。
Skills：可复用 workflow 和 domain expertise。
MCP：连接外部工具和 shared systems。
Subagents：把工作委派给 specialized agents。

先问“这个需求应该放哪层”，再动配置。

AGENTS.md：稳定规则

AGENTS.md 给 Codex 提供 durable project guidance，会在 agent 开始工作前生效。它适合写：

build and test commands。
review expectations。
repo-specific conventions。
directory-specific instructions。
受保护路径。
文档和测试同步规则。

当 agent 对 codebase 做出错误假设时，把正确规则补进 AGENTS.md。这应该是反馈循环，不是一次性文档工程。

更新原则：

从真正重要的 instructions 开始。
把反复出现的 review feedback codify。
把 guidance 放到离适用目录最近的位置。
全局文件塑造个人工作习惯，repo 文件聚焦团队和 codebase rules。

AGENTS.md 应该和 pre-commit hooks、linters、type checkers 配合。规则只靠模型遵守不够，能自动验证的就交给工具。

Skills：重复流程

Skills 适合封装重复 workflows。它们通常比单纯写进 prompt 更适合复用，因为 skill 可以包含 instructions、scripts、references 和 assets。

常见结构：

my-skill/
  SKILL.md
  scripts/
  references/
  assets/

适合做 skill 的情况：

release steps。
review routines。
docs updates。
migration checklist。
需要 examples、references 或 helper scripts 的流程。

不要把还没跑稳的想法直接做成 skill。先用普通 prompt 跑通，重复出现后再沉淀。

MCP：外部系统

MCP 是把 Codex 连接到 external tools 和 context providers 的方式。它适合：

issue trackers。
design tools。
browsers。
shared documentation systems。
internal knowledge services。

MCP server 可以暴露 tools、resources 和 prompts。区别要清楚：

context 型 MCP 主要提供信息。
action 型 MCP 可能改外部系统。
带写权限的 MCP 必须考虑审批、日志和回滚。

实践中，MCP 和 skills 搭配最有价值：skill 定义 workflow，并说明什么时候调用哪些 MCP tools。

Memories：延续上下文

Memories 适合保存跨任务仍然有价值的偏好、项目习惯和历史经验。

不要把敏感信息、临时任务细节、过期路径、一次性结论写进 memory。Memory 是长期注入上下文，错误内容会持续影响后续任务。

Subagents：角色分工

Subagents 适合把 noisy 或 specialized tasks 拆出去。例如：

一个 agent 专门跑测试和复现。
一个 agent 专门审查 diff。
一个 agent 专门查询日志或外部系统。

不要把 subagent 当成“更多模型就更强”。角色、输入、输出、权限和验收要写清，否则只是把混乱并行化。

建设顺序

推荐顺序：

写清 AGENTS.md，让 Codex 遵守 repo conventions。
用 lint、type check、test、pre-commit 强制可验证规则。
重复流程跑稳后创建 skill。
需要外部系统时接 MCP。
准备好角色边界后再用 subagents。
需要分发给团队时，把 skill 和配置打包成 plugin。

常见坑

项目规则没写清，却先装很多 MCP。
把一次性 prompt 做成 skill。
把个人偏好写进团队 repo AGENTS.md。
把 action 型 MCP 当成只读上下文。
subagent 职责重叠，最后没人负责验收。
Memory 里保存敏感信息或过期事实。

验收清单

任何定制项都能说清属于哪一层。
AGENTS.md 小而具体，包含验证方式。
skill 有真实触发词、步骤和验收。
MCP 权限和数据来源可审计。
memory 不含 secret、token 或临时结论。
subagent 的输入、输出、权限和复核人明确。