codex 如何完成一个开发任务：看懂 agent 的工具、技能与分工

让 codex 加一个接口，它为什么先读项目说明，再搜索代码、修改文件、运行测试，有时还会请另一个助手检查？

看 agent 架构图时，这些动作又会变成一串名词：tools、skills、mcp、subagents、hooks、plugins。容易记住名字，却看不清它们怎样配合。

这篇文章就沿着一个开发任务，把整个过程走一遍：

给一个 go 服务增加 GET /api/tasks/{id}，查询任务状态。沿用现有代码结构和错误格式，补齐测试，先交付改动和检查结果，得到授权后再提交推送。

这是一个简化的示例项目，不对应我的真实业务代码。本文解释的是 agent 完成任务时各组件的关系，不是 codex 全部工具或 api 的使用手册。产品说明依据截至 2026 年 10 月 6 日的官方文档整理。

先看整条流程：agent 决定下一步，工具执行操作

大语言模型，也就是 llm，负责理解需求、生成内容和提出下一步操作。codex 这样的 agent 应用，还要执行工具、接收结果、管理上下文和控制流程。

可以把 codex 想成一位开发同事：接到需求以后，他要根据已有代码和检查结果，一步步把事情做完。

明确接口目标
    ↓
读项目约定和现有代码
    ↓
按需要使用技能、取得外部资料
    ↓
用工具修改代码和测试
    ↓
查看测试与审查结果
    ├─ 有问题 → 回到相关步骤修正
    └─ 达到目标 → 交付，按授权继续提交

agent 的作用贯穿整个过程。它要判断读哪些文件、在哪里修改、失败后怎么办，以及什么时候可以交付。

图里的组件可以先这样区分：

这些东西不全是工具。 项目说明是约定，skill 是方法，mcp 是连接机制，plugin 是包装。读取文件、执行命令、查询外部文档等具体操作，属于工具调用。

下面看它们怎样参与同一个接口任务。

1 先确定要交付什么

假设服务已经有任务查询逻辑，新接口主要负责接收请求、调用已有逻辑，再返回结果。

请求示例：

GET /api/tasks/task-123

任务存在时，返回 200 和下面的 json：

{
  "id": "task-123",
  "status": "running"
}

还需要先明确错误场景：

这三项是示例项目的接口约定。真实开发时，应先与需求和已有接口对齐。

这样，“增加接口”就有了可以检查的目标：不只是生成一个函数，还要让路由、响应和错误处理符合约定。

2 读项目约定，再找已有实现

codex 不能只凭通用经验猜项目结构。先读适用的 AGENTS.md，再看现有路由、handler 和测试，才能知道这里惯用的写法。

这个示例项目的说明可以写成：

# go 服务约定

- handler 放在 internal/handler/，沿用现有路由和响应结构。
- 新接口尽量复用已有查询逻辑，不引入无关依赖。
- 错误响应沿用现有格式，补齐正常、资源不存在和内部错误的测试。
- 格式化改动文件，运行相关测试。
- 保留已有修改；未经授权，不提交或推送。

codex 可以通过工具查看文件和工作区状态，例如：

rg --files internal/handler
git status --short

AGENTS.md 告诉它应该遵守什么；工具帮助它看到实际文件；agent 再判断哪些实现值得参考。

codex 会读取适用的项目说明，个人说明与项目说明可以叠加，靠近当前工作目录的说明可以补充更具体的要求。它不会无条件读取仓库里所有同名文件。官方 AGENTS.md 说明。

说明文件也不等于执行权限。文件访问、网络和操作范围，仍由运行环境的沙箱与审批机制控制。

3 用 skill 复用开发方法

目录和规范已经清楚，接下来要按什么步骤实现接口？

如果我经常让 codex 加接口，可以把这套方法写成 skill。在本地项目中，一个支持的路径是：

.agents/skills/add-go-api/SKILL.md

简化的内容如下：

---
name: add-go-api
description: 为现有 go 服务增加 http 接口，沿用项目结构、处理错误并补齐测试。
---

1. 读取适用的 AGENTS.md、已有路由、handler 和测试。
2. 确认请求、响应和错误场景。
3. 复用现有查询逻辑，实现接口并补齐测试。
4. 格式化改动文件，运行相关检查。
5. 报告改动和检查结果，遵守当前提交授权。

skill 还可以带参考资料、模板和脚本，但 SKILL.md 是核心。它保存做事方法，不会重新训练模型。官方 skills 文档。

在 codex cli 或 IDE 扩展中，可以通过 /skills 选择技能，或用 $ 指定已发现的技能：

$add-go-api
增加 GET /api/tasks/{id}，补齐 200、404、500 场景的测试。
先交付改动与检查结果，不提交或推送。

codex 也可以根据任务和技能简介选择是否使用。它先看名称和简介，需要时再读取完整步骤和相关材料，避免把所有技能全文都塞进上下文。

三者的分工是：当前请求说明这次做什么，AGENTS.md 说明这个项目的规矩，skill 提供完成这类工作的办法。

4 调用工具，把设计落实成代码

接下来，agent 需要通过工具完成实际改动：

读取路由和 handler
    ↓
找到已有任务查询逻辑
    ↓
增加接口、注册路由
    ↓
补齐响应和错误场景的测试

tool 是能够执行的操作接口。读取工具返回文件内容，编辑工具修改文件，终端工具运行命令。调用哪些工具、怎样使用结果，由 agent 决定。

skill 提供方法，tool 执行操作。 把“运行测试”写进技能，不会自动给环境装好 go，也不会保证测试通过。

这个任务需要外部材料时，再用 mcp

如果需求和代码都在当前仓库，直接读文件就可以。若接口约定保存在已接入的需求系统或文档服务里，可以通过 mcp 取得材料：

codex → mcp client → 已接入的文档服务
                         ↓
                  返回字段和错误约定
                         ↓
                  codex 继续实现接口

mcp 是 model context protocol，也就是模型上下文协议。它规定连接和交流方式；“读取接口文档”则是接入后能调用的具体工具。

在 codex cli 中，可以用 codex mcp list 查看已经配置的服务。本地 codex 支持连接本地进程或远端服务；云端能否访问同一服务，需要另行确认网络、连接和认证。官方 mcp 文档。

连接成功也不代表获得所有权限。能读需求，不一定能修改需求单，更不等于能推送代码。

5 验证结果：测试、独立审查和自动触发

代码写完以后，agent 要拿实际结果和最初的目标对照。

假设改动的是下面两个文件，可以先格式化，再运行相关包和当前模块的测试：

gofmt -w internal/handler/task_status.go internal/handler/task_status_test.go
go test ./internal/handler
go test ./...

实际文件名和检查范围应以项目为准。gofmt 官方说明、go test 官方说明。

如果测试发现“任务不存在”仍返回 200，agent 应检查错误分支，修正为约定的 404，再运行检查。这就是前面流程里的反馈循环。

subagents：需要独立审查时再分工

错误处理和测试覆盖可以分别检查，因此可以明确要求 codex：

请用两个子代理审查这次改动：
1. 检查任务不存在、内部查询失败时的状态码和错误响应。
2. 检查测试是否覆盖 200、404、500，以及响应字段。

子代理只读代码并返回意见，不修改文件。
等待结果后，由主代理统一修正。

子代理承接的是一个范围清楚的小任务。主代理接收意见、判断如何修改，继续对整体结果负责。

codex 支持直接请求分工，也可以遵循适用的项目或技能分工要求。子代理可以有自己的上下文和模型设置，不要求换一种模型。官方 subagents 文档。

分工会增加模型与工具的工作量，小改动通常不必使用。让两个助手同时修改同一个 handler，也容易产生冲突。

hooks：需要固定时机触发检查时再配置

仅靠提示词提醒“记得检查”，仍可能漏掉。hook 可以在支持的事件发生时触发处理。

例如，codex 官方文档中的 PostToolUse 是工具执行后的事件，Stop 是当前回复结束时的事件。在支持且已配置的环境中，可以让匹配的事件触发相关检查，把失败结果交回 agent。官方 hooks 文档。

这不是配置文件示例。真正使用时，要确认匹配范围、脚本和目标工具的覆盖情况，不必每次工具调用都运行全套测试。

也可以用 git hook 或 ci 执行检查，它们与 codex 的生命周期 hook 是不同机制。这个接口任务，先由 codex 主动检查，再让 ci 检查提交，往往已经够用。

测试和审查各有作用：测试验证写好的场景，审查帮助发现遗漏和不必要的改动。自动触发只负责安排处理时机，不会自动证明接口设计正确。

6 按授权交付，再确认远端结果

达到目标以后，codex 应交付清楚的结果：

• 哪些文件发生了什么改动。
• 200、404、500 的实现和测试情况。
• 实际运行了哪些检查，哪些还没验证。

如果当前要求先审阅，就停在工作区改动和检查结果。获得提交推送授权后，再只提交相关文件，核对远端提交，并跟进 ci。

是否需要发布，则取决于任务约定。如果推送会触发部署，还需要确认部署结果。代码已写入、测试通过、提交已推送、部署成功，是不同阶段的结果。

plugins 和执行环境：让方法复用，也要确认入口

前面的开发流程已经可以独立完成。若接口开发 skill 和一个需求文档服务经常一起使用，可以打包成 plugin，让其他人安装。

plugin 主要解决分发与安装，不是每个开发任务都必须经过的一步。例如，一个假想的接口开发插件可以提供开发技能、检查清单和读取需求所需的 mcp 能力。

当前官方文档区分了入口：codex cli 和桌面端有插件入口，IDE 扩展不支持插件。插件可以包含 skills、mcp 能力和 hooks，但云端编排的 chatgpt work 不支持插件 hooks；安装插件也不会自动把脚本部署到执行环境。官方 plugins 文档。

同一个开发方法，换到另一个环境，还要确认能否执行：

本地项目的 .agents/skills/ 可以保存项目技能，云端是否发现并加载它，要看该入口的技能机制。云端任务也有自己的环境和文件状态，网络访问有独立设置。官方云端环境说明。

因此，本机能测试、能读需求服务，不能直接当作云端也能工作的证据。应在目标环境实际验证，缺失的能力和未运行的检查要说明。

看完以后，怎么判断需要哪一项

回到 GET /api/tasks/{id}，先让“读规范和代码 → 实现接口 → 补齐测试 → 检查与交付”这条流程可靠运行。

如果项目约定不清楚，完善 AGENTS.md；如果每次加接口都要重复交代步骤，整理 skill；如果代码读不了、测试跑不起来，先检查工具和执行环境。

对这个接口任务，需要外部需求材料时，再增加 mcp 连接；有独立审查工作时，再用 subagents；需要在指定事件后触发处理时，再配置 hooks；希望把这些能力分发给别人时，再考虑 plugin。

agent 的核心工作，是根据目标和反馈决定下一步。项目约定和技能帮助它把事情做对，工具让操作真正发生，连接、分工与自动触发则按需要补充。理解这些关系，就能看懂 codex 怎样把一句开发需求变成可以审查的代码改动。