Codex 进阶用法：从对话助手到项目级智能协作者

很多人使用 Codex 时，仍然沿用普通聊天机器人的方式：提出一个问题，ai将代码改好，下一次又重新提出问题描述问题再改代码。这种方式适合零散问题，却没有充分利用 Codex 能够读取项目、修改文件、运行命令、调用工具和验证结果的特点。

更合适的思路是把 Codex 当作一名受规则约束的项目协作者：先让它理解项目和任务，再让它执行、验证并汇报。本文梳理 AGENTS.md、任务提示、状态文档、Agent Skills、MCP、子 Agent、Worktree、Hooks 与 Automations 的分工，并给出一套可以逐步落地的工作流。

本文依据 Codex 官方文档核对，功能状态截至 2026 年 6 月 7 日。不同客户端和版本的功能入口可能有所差异。

一、先区分不同机制的职责

这些机制并不是同一类东西。把它们混在一起，容易出现 AGENTS.md 越写越长、Skill 数量失控或多个 Agent 相互覆盖代码的问题。

机制	主要用途	适合保存的内容
Prompt	描述当前任务	目标、上下文、约束、完成标准
AGENTS.md	提供长期项目规则	目录结构、编码规范、测试命令、禁止事项
状态文档	记录跨会话进度	当前计划、已完成内容、阻塞问题
Agent Skill	封装可重复工作流	执行步骤、参考资料、脚本和模板
MCP	连接外部工具与上下文	浏览器、Figma、文档、数据库等
子 Agent	并行处理独立子任务	探索、审查、比较和分模块分析
Worktree	隔离并行代码修改	独立检出、独立分支和后台任务
Hooks	在生命周期中执行确定性脚本	安全检查、日志、校验和规则强制
Automations	定时重复执行任务	周期检查、报告、维护和监控

可以将它们概括为：

Prompt 决定这次做什么
AGENTS.md 规定在项目中怎样做
状态文档记录做到哪里
Skill 固化一类任务的做法
MCP 提供外部工具
子 Agent 拆分认知工作
Worktree 隔离代码改动
Hooks 保证关键动作发生
Automations 定期重复执行

AGENTS.md 保存稳定的项目规则

Codex 会在开始工作前读取 AGENTS.md。规则可以分层放置：

~/.codex/AGENTS.md          个人通用规则
<项目根目录>/AGENTS.md      整个项目的共同规则
<子目录>/AGENTS.md          特定模块的局部规则
AGENTS.override.md          当前层级的覆盖规则

Codex 从项目根目录向当前工作目录逐层读取，越靠近当前目录的规则优先级越高。因此，全局文件适合保存个人习惯，项目根目录保存团队约定，特殊模块再添加局部规则。

一个科研代码项目可以这样写：

# Project Overview

这是一个多目标智能优化算法实验项目。

## Repository Structure

- `src/`：算法实现
- `experiments/`：实验入口
- `configs/`：实验配置
- `results/`：实验结果
- `docs/`：项目文档

## Development Rules

- 科研代码保持直接，不要过度工程化
- 不要擅自修改论文给出的实验参数
- 所有随机实验必须显式设置随机种子
- 未经允许不要增加生产依赖
- 不要覆盖已有实验结果和未提交修改

## Validation

完成代码修改后：

1. 运行相关测试或最小实验
2. 检查输入输出维度
3. 检查随机种子和配置来源
4. 查看 `git diff`
5. 汇报修改文件、验证结果和未验证内容

AGENTS.md 适合记录长期稳定、经常复用的要求，不适合记录某次任务的进度。下面这些内容应放到其他文件中：

• 今天修复了哪些问题；
• 某次实验运行到第几组；
• 当前任务还剩哪些步骤；
• 一次性需求和临时决定；
• 已经过期的背景说明。

一条实用原则是：只有当 Codex 在多个任务中反复犯同一种错误时，再考虑把对应规则加入 AGENTS.md。文件越短、越具体，真正重要的规则越容易生效。

三、把任务写成可验证的目标

AGENTS.md 不能代替当前任务说明。一个有效的 Prompt 通常包含四部分：

1. 目标：最终要得到什么；
2. 上下文：相关文件、入口、错误现象和现有实现；
3. 约束：不能修改什么，必须保留什么；
4. 完成标准：怎样判断任务已经完成。

例如：

任务目标：
为当前 NSGA-II 实现增加并行种群评价。

相关上下文：
入口文件是 `main_optimization.m`；
评价函数是 `evaluate_layout.m`；
配置位于 `config_optimization.m`。

约束：
不要修改目标函数；
保留串行模式；
使用 `use_parallel` 控制；
不要改变已有输出格式。

完成标准：
串行和并行模式均能运行；
固定随机种子时，两种模式的结果一致；
最后汇报修改文件和测试结果。

Codex 官方提示指南强调两点：任务应拆成较小、聚焦的步骤，并尽量提供可执行的验证方法。对于范围较大的任务，可以先使用 /plan 让 Codex分析方案，再开始实现。

Codex 还提供 Goal mode，用于在较长任务中持续保留目标和完成标准。可以通过 /goal 启动；如果命令未出现，需要在 config.toml 中启用：

[features]
goals = true

目标本身仍应可检查，例如“迁移到 TypeScript，并在严格模式下通过编译”，而不是笼统地写“优化一下项目”。

四、用状态文档承接跨会话任务

聊天上下文不应成为项目状态的唯一来源。对于持续数天或涉及多个阶段的工作，可以在仓库中自行维护以下文件：

文件	建议用途
PLANS.md	当前复杂任务的阶段、步骤和验收条件
TASKS.md	尚未完成的待办事项
HANDOFF.md	当前进度、阻塞问题和下一步
docs/DECISIONS.md	重要设计决策及其原因
docs/EXPERIMENTS.md	实验配置、随机种子、结果和结论

这些文件不是 Codex 强制规定的标准，而是一种实用的项目约定。例如：

# 当前任务

实现 SPEA2 并接入统一优化框架。

## 已完成

- [x] 分析现有 NSGA-II 接口
- [x] 统一个体数据结构
- [x] 实现强度适应度

## 待完成

- [ ] 实现环境选择
- [ ] 接入主程序
- [ ] 增加并行评价
- [ ] 与 NSGA-II 对比

## 当前阻塞

SPEA2 档案结构与现有结果输出接口不一致。

## 下一步

先增加档案到统一种群结构的转换函数，再修改输出模块。

新会话开始时，只需让 Codex 先阅读 AGENTS.md 和这些状态文件，再继续当前任务。这样比重新复述全部背景更可靠，也方便人工检查项目实际进度。

五、用 Agent Skills 固化重复工作流

当一类任务反复出现时，不应每次重新编写长 Prompt。Agent Skill 用于封装可重复的工作流程，可以包含：

my-skill/
├── SKILL.md
├── scripts/
├── references/
└── assets/

其中只有 SKILL.md 是必需的。Codex 最初只读取 Skill 的名称、描述和路径，真正选中它后才加载完整内容，因此 Skill 比把所有流程都塞进 AGENTS.md 更适合管理任务级知识。

例如，为个人博客创建写作 Skill：

---
name: write-blog-article
description: Write, revise, review, or reorganize Markdown articles for this VuePress Theme Hope personal blog. Use for article content under src/. Do not use for site-configuration-only changes.
---

1. 阅读目标目录的 `README.md`、相邻文章和导航配置。
2. 判断文章属于教程、理论笔记、速查表还是经验文章。
3. 对时效性事实进行核验，只引用实际阅读的来源。
4. 按项目既有 Frontmatter、标题和代码块规范写作。
5. 运行构建并检查生成页面、链接和 Git 差异。
6. 汇报构建结果、警告和无法完成的验证。

Skill 的 description 不只是说明文字，也是 Codex 判断是否调用该 Skill 的触发条件。因此应明确写出：

• 它处理什么任务；
• 用户可能使用哪些表达；
• 什么情况下不应调用；
• 输入和输出分别是什么。

仓库级 Skill 通常放在 .agents/skills/，个人通用 Skill 可以放在 $HOME/.agents/skills/。在 CLI 或 IDE 中可以显式提及 $skill-name，也可以让 Codex 根据描述自动选择。

当 Skill 需要分发给其他项目或成员时，可以进一步打包为 Plugin。Plugin 可以组合 Skills、应用集成和 MCP 配置；本地项目中的单个工作流则没有必要一开始就做成 Plugin。

六、用 MCP 连接项目之外的工具

模型上下文协议（Model Context Protocol，MCP）用于给 Codex 接入外部工具和数据。Codex 可以通过 MCP 访问第三方文档，也可以操作浏览器、Figma 等开发工具。

常见场景包括：

MCP 类型	适合的任务
浏览器或 Playwright	复现页面问题、点击交互、验证响应式布局
Figma	读取设计信息并对照前端实现
文档或知识库	查询内部规范、API 文档和项目说明
GitHub	读取 Issue、PR 和提交记录
数据库	检查数据结构和查询结果

MCP 解决的是“Codex 能访问什么”，Skill 解决的是“拿到工具后按什么流程工作”。二者可以组合，例如让一个前端验收 Skill 调用浏览器 MCP，依次检查桌面端、平板端和移动端。

不要为了“看起来完整”而接入大量 MCP。每增加一个工具，都会增加权限范围、配置成本和工具选择负担。更稳妥的做法是：

1. 只接入高频工具；
2. 限制工具权限和可访问范围；
3. 明确哪些操作需要人工批准；
4. 不在配置中保存明文密钥；
5. 定期删除已经不用的连接。

七、用子 Agent 拆分工作，用 Worktree 隔离修改

子 Agent 和 Worktree 经常一起出现，但它们解决的问题不同：

• 子 Agent隔离上下文和职责，适合并行分析；
• Worktree隔离文件和 Git 状态，适合并行修改。

例如，对当前分支进行多角度审查：

请为以下方向分别启动一个只读子 Agent：

1. 逻辑错误和边界情况；
2. 性能、并行和资源问题；
3. 测试覆盖与可复现性；
4. 代码结构与可维护性。

等待所有子 Agent 完成后，合并并去重结果，
按严重程度列出文件位置、问题原因和修改建议。
不要修改代码。

Codex 只会在被明确要求时启动子 Agent。每个子 Agent 都会独立使用模型和工具，因此并行并不等于节省 Token。它更适合以下情况：

• 大型代码库探索；
• 多角度代码审查；
• 论文、代码和实验配置的并行比对；
• 文件边界清晰的独立模块；
• 多种方案的并行研究。

多个 Agent 不应同时直接修改同一组文件。需要并行编码时，可以在 Codex App 中为不同线程使用 Git Worktree。每个 Worktree 拥有独立检出，可以避免后台任务干扰当前工作区；完成后再检查差异、创建分支或将线程移交回本地工作区。

Worktree 仍然依赖 Git。未提交文件、被 .gitignore 忽略的内容和本地依赖不会自动等同于主工作区，因此开始任务前应确认环境初始化和数据路径。

八、用 Hooks 强制执行确定性检查

自然语言规则只能表达“应该做什么”，不能保证每次都执行。Hooks 可以在 Codex 生命周期的指定事件中运行脚本，例如：

• 提交 Prompt 前扫描意外粘贴的 API Key；
• 工具调用后记录日志；
• 一个回合结束时运行自定义校验；
• 会话开始时加载项目状态；
• 子 Agent 停止时收集结果；
• 根据当前目录补充特定提示。

Hook 可以配置在用户级或项目级的 hooks.json、config.toml 中。项目 Hook 本质上是可执行代码，使用前应检查脚本内容并完成信任确认，不应直接启用来源不明的配置。

Hooks 适合强制执行少量关键规则，而不是把整个开发流程写成复杂脚本。例如，“修改完成后必须检查是否存在明文密钥”适合 Hook；“如何复现一篇论文”则更适合 Skill。

九、用 Automations 处理周期性任务

Codex App 的 Automations 用于定时执行重复任务，并将有结果的运行放入待处理列表。可以与 Skills 组合，例如：

• 每周扫描依赖更新和弃用警告；
• 每天检查构建失败或测试波动；
• 定期整理项目中的待办注释；
• 周期性生成实验状态报告；
• 检查文档链接是否失效。

项目级 Automation 运行时，本机需要开机、Codex App 需要保持运行，并且目标项目仍可访问。对于 Git 仓库，可以让 Automation 在独立 Worktree 中运行，避免直接改动正在编辑的工作区。

自动化任务应优先使用只读权限。需要写文件或使用完整权限时，应限制命令范围，并把修改放入 Worktree 后人工审查。周期执行会放大错误配置的影响，因此不适合直接执行未经验证的发布、删除或覆盖操作。

十、建立“执行—验证—审查”的闭环

Codex 的价值不只是生成修改，而是完成一个可检查的任务闭环：

理解目标
  ↓
读取规则和相关文件
  ↓
提出计划
  ↓
实施最小修改
  ↓
运行测试、构建或最小实验
  ↓
检查 Git 差异
  ↓
进行第二遍审查
  ↓
更新状态文档
  ↓
汇报结果与剩余风险

可以将下面的模板用于大多数代码任务：

请先阅读 `AGENTS.md`、项目结构和与任务相关的文件。

任务目标：
<需要实现的结果>

相关上下文：
<入口文件、错误信息、需求来源和现有行为>

约束：
<不能修改的内容、兼容性要求和代码风格>

完成标准：
<测试、构建、输出或性能指标>

执行要求：

1. 先检查现有实现，并给出简短计划。
2. 不要修改与任务无关的文件。
3. 不要覆盖已有的未提交修改。
4. 优先进行最小范围修改。
5. 修改完成后运行相关验证。
6. 检查 `git diff` 和 `git status --short`。
7. 对最终修改进行一次独立审查。
8. 汇报修改文件、验证结果、警告和未验证内容。

对于 Bug，可以再增加“先复现、定位根因、添加回归测试”；对于重构，可以增加“保持外部接口和行为不变”；对于科研实验，则应增加“固定随机种子、保存配置、记录失败实验”。

十一、推荐的渐进式使用顺序

不需要一开始就配置完整的多 Agent 系统。更稳妥的顺序是：

1. 先写 AGENTS.md：解决项目规则反复解释的问题；
2. 固定任务模板和验证流程：让每次执行都有完成标准；
3. 增加状态文档：承接跨会话任务；
4. 制作少量高频 Skills：固化重复且稳定的流程；
5. 按需接入 MCP：只连接真正需要的外部工具；
6. 复杂任务使用子 Agent 和 Worktree：分别处理并行分析与修改隔离；
7. 关键规则加入 Hooks：把必须发生的检查改为确定性执行；
8. 稳定任务再做 Automations：自动化已经验证过的周期流程。

对于个人开发者，最先产生明显收益的通常不是更多工具，而是：

准确的 AGENTS.md
+ 清晰的任务目标
+ 可执行的完成标准
+ 测试与 Git 检查
+ 2～5 个高频 Skills

当这套基础稳定后，Codex 才会从一次性回答问题的助手，转变为能够理解项目、遵守规则、执行任务并接受验证的项目级协作者。

参考资料

• Codex Prompting：任务拆分、验证与 Goal mode
• Codex 自定义项目指令：AGENTS.md
• Codex Agent Skills
• Codex Model Context Protocol
• Codex Subagents
• Codex Hooks
• Codex App Worktrees
• Codex App Automations