团队工作流：把 Codex 用成稳定流程

团队工作流：把 Codex 用成稳定流程

这一篇不再单独讲某一个功能，而是把前面学过的能力串起来。

你已经看过：

• AGENTS.md：沉淀项目规则。
• config.toml：管理 Codex 运行配置。
• MCP：连接外部资料和工具。
• Skills：复用稳定工作流程。
• Hooks：在生命周期里做提醒或检查。
• Subagents：把只读分析、审查、专项判断拆出去。

如果这些能力分开用，只能算“会配置”。
把它们组合成稳定流程，才算真正让 vibe coding 更专业和更高效。

前置教程：第一次创建自定义 Subagent
如果你还没有完成自定义 Subagent 的低风险练习，先完成前置教程，再回到本篇。

依据来源：OpenAI Codex 官方手册中 AGENTS.md、config.toml、MCP、Skills、Hooks、Subagents、自定义 agents、项目级 .codex/ 配置和受信任项目等章节。

本篇目标

完成后，你应该得到一套可以长期复用的工作方法：

任务进入
-> Codex 先读规则和上下文
-> 必要时调用 Skill 或 MCP
-> 必要时让 Subagent 做只读评审
-> Codex 修改文件
-> Codex 自己检查结果
-> 你审查总结和 diff
-> 把重复经验沉淀回 AGENTS.md / Skill / Hook

这套流程的重点不是“自动化越多越好”，而是：

• 每一步都有明确边界。
• 每一次修改都能验收。
• 重复经验能沉淀。
• 风险能力先只读、后启用。
• 不把临时需求写进长期规则。

先分清每个能力负责什么

把 Codex 用乱，通常不是因为功能不够，而是因为职责放错了。

能力	适合放什么	不适合放什么
当前对话提示词	本次任务目标、范围、验收标准	长期项目规则
AGENTS.md	项目约定、目录说明、检查方式、汇报要求	临时需求、模型配置、密钥
config.toml	模型、provider、sandbox、MCP、Hooks、Subagents 配置	业务规则、代码风格解释
MCP	外部文档、Issue、设计稿、私有知识库、工具能力	已经在项目里的代码说明
Skill	可复用任务流程，比如教程审查、Bug 排查、发布检查	一次性提示词
Hook	生命周期提醒、固定检查、权限前置提示	复杂业务判断
Subagent	并行只读分析、专项审查、风险评估	无边界地并行改代码

你可以用一句话判断：

会不会长期重复出现？

如果不会，就留在本次提示词里。
如果会，再判断应该沉淀到哪个位置。

推荐的最小团队工作流

第一次搭团队工作流，不要同时启用所有能力。

推荐从下面这 5 件事开始：

1. 项目根目录有一份短而准的 AGENTS.md。
2. 用户级 config.toml 只放个人通用配置。
3. 项目级 .codex/config.toml 只放当前项目确实需要的配置。
4. 只保留一个低风险 Hook，用来提醒命令风险。
5. 只保留一个只读 Subagent，用来做专项评审。

第一版不要做：

• 自动提交。
• 自动发布。
• 自动删除文件。
• 自动改数据库。
• 多个 Subagent 同时改代码。
• 多个 Hook 串联执行复杂脚本。
• 把所有团队制度一次性塞进 AGENTS.md。

稳定比复杂更重要。

第 1 步：让 Codex 盘点当前项目已有能力

先不要新增文件。
先让 Codex 只读盘点现状。

复制这段：

请只读盘点当前项目的 Codex 工作流配置。

要求：
1. 不要创建、修改、删除任何文件。
2. 检查是否存在 AGENTS.md。
3. 检查是否存在 .codex/config.toml。
4. 检查是否存在 .codex/hooks.json 或 .codex/hooks/。
5. 检查是否存在 .codex/agents/。
6. 检查是否存在 .agents/skills/。
7. 如果存在 MCP、Hooks、Skills、Subagents 配置，只总结名称、来源和用途，不要执行。
8. 最后输出一张表：配置项、是否存在、作用、风险等级、是否建议保留。

预期结果：

• Codex 会告诉你当前项目有哪些 Codex 相关文件。
• Codex 不会修改文件。
• Codex 会区分用户级配置和项目级配置。
• Codex 会提醒哪些配置需要信任或审查。

如果 Codex 找不到某些配置，不要急着创建。
先看下一步的流程设计。

第 2 步：设计项目工作流，不写文件

让 Codex 先设计方案。

复制这段：

请基于当前项目现状，设计一套低风险 Codex 团队工作流，先不要写文件。

目标：
让 Codex 在这个项目里能稳定完成：读项目、改小任务、验收、提交前检查、文档审查。

限制：
1. 第一版只允许使用 AGENTS.md、一个低风险 Hook、一个只读 Subagent。
2. 如果当前项目没有必要，不要强行引入 MCP。
3. 如果当前项目没有重复流程，不要强行创建 Skill。
4. 不允许自动提交、自动推送、自动发布。
5. 不允许自动删除文件。
6. 所有新增配置都必须说明回滚方式。

请输出：
1. 推荐保留哪些现有配置。
2. 推荐新增哪些配置。
3. 每个配置负责什么。
4. 哪些内容继续放在每次任务提示词里。
5. 哪些内容适合沉淀到 AGENTS.md。
6. 哪些内容暂时不要做。

你要重点看 3 件事：

• Codex 有没有把临时任务写进长期规则。
• Codex 有没有建议启用过多自动化。
• Codex 有没有把密钥、账号、私有地址写进配置文件。

如果方案太复杂，直接收窄：

这个方案太复杂。请收敛到第一版最小工作流：
1. 只更新 AGENTS.md。
2. 只保留一个命令执行前提醒 Hook。
3. 只保留一个只读评审 Subagent。
4. 不新增 MCP。
5. 不新增 Skill。
6. 不做自动提交、自动发布、自动删除。

第 3 步：整理 AGENTS.md 的团队规则

团队工作流的核心通常不是 Hook，也不是 Subagent，而是 AGENTS.md。

因为它最适合写清楚项目里的长期规则。

让 Codex 先给草稿：

请为当前项目整理一版团队可用的 AGENTS.md 草稿，先不要写文件。

要求：
1. 基于当前项目真实结构和真实配置，不要编造命令。
2. 只写长期有效的规则。
3. 不要写本次临时任务。
4. 不要写 API Key、Token、账号、私有地址。
5. 不要写模型名、Base URL 等运行配置。
6. 内容控制在 120 行以内。

结构建议：
1. 项目概况。
2. 关键目录。
3. 常用检查。
4. 修改边界。
5. 安全要求。
6. Codex 任务流程。
7. 任务完成后的汇报格式。

合格的 AGENTS.md 应该像项目说明书，不像口号墙。

不要写：

代码要优雅。
必须保持高质量。
遇到问题要认真分析。

应该写：

修改前先确认影响范围。
新增页面后需要检查路由入口和导航入口。
任务结束时必须说明修改文件、验证方式和未验证原因。
没有在 package.json 中确认的脚本，不要写成可用命令。

这些规则能执行，也能检查。

第 4 步：把日常任务提示词标准化

即使有 AGENTS.md，本次任务提示词仍然很重要。

团队里可以约定一个固定任务格式：

任务目标：
把 xxx 页面里的 xxx 问题修好。

修改范围：
只允许修改 xxx 文件或 xxx 模块。

禁止事项：
不要重构无关代码。
不要修改接口协议。
不要提交 Git。
不要改动密钥、环境变量、构建配置。

执行方式：
先读相关文件并说明理解。
如果需求不清楚，先提问。
确认后再修改。

验收标准：
1. xxx 行为符合预期。
2. 没有影响 yyy。
3. Codex 需要说明做了哪些检查。

汇报要求：
最后用中文说明修改文件、修改原因、验证结果、未验证项。

这段提示词适合放在模板库或 Skill 里。
不适合全部塞进 AGENTS.md，因为不同任务的目标和范围不同。

第 5 步：决定是否需要 Skill

不要把所有提示词都做成 Skill。

只有满足下面条件，才适合创建 Skill：

• 同一类任务每周都会重复。
• 每次流程基本一样。
• 输出格式有固定要求。
• 需要附带参考资料或检查清单。
• 普通提示词已经反复复制粘贴。

例如这个站点适合做 Skill 的任务：

• 审查喂饭级教程。
• 改写 AI 味较重的文档。
• 检查教程是否有跳步。
• 检查教程是否缺少前置链接。

不适合做 Skill 的任务：

• 今天临时改一个标题。
• 只改一个按钮颜色。
• 一次性的页面文案讨论。

如果决定创建 Skill，先让 Codex 只设计：

请判断当前项目是否需要把“喂饭级教程审查”沉淀成 Skill。

要求：
1. 不要创建或修改文件。
2. 说明为什么普通提示词不够。
3. 说明 Skill 的触发场景。
4. 说明 Skill 应该检查哪些内容。
5. 说明第一版不应该包含哪些复杂能力。
6. 如果不建议创建，也要说明理由。

如果 Codex 给出的理由不充分，就继续用普通提示词。

第 6 步：决定是否需要 MCP

MCP 的作用是连接外部资料和工具。

如果任务只需要读当前项目代码，不需要 MCP。

适合用 MCP 的情况：

• Codex 需要查内部文档。
• Codex 需要读 Issue 或 PR。
• Codex 需要访问设计稿信息。
• Codex 需要查询外部 API 文档。
• Codex 需要连接团队知识库。

不适合用 MCP 的情况：

• 只是修改本地页面。
• 只是读当前仓库代码。
• 只是检查构建失败。
• 只是写 README。
• 只是补充教程文字。

判断提示词：

请判断当前任务是否需要 MCP。

任务背景：
【粘贴你的任务】

要求：
1. 先说明仅靠当前仓库是否足够。
2. 如果需要 MCP，说明需要连接什么资料或工具。
3. 如果不需要 MCP，明确说不需要。
4. 不要为了高级而强行建议 MCP。

只有当外部资料是完成任务的必要条件时，才配 MCP。

第 7 步：让 Subagent 做只读专项评审

Subagent 最适合先做只读评审。

团队工作流里可以把它放在两个位置：

1. 修改前：让 Subagent 分析风险。
2. 修改后：让 Subagent 审查结果。

推荐从修改后审查开始。

复制这段：

请在本次修改完成后，使用只读 Subagent 做一次专项评审。

评审目标：
检查本次修改是否符合任务目标和 AGENTS.md 规则。

要求：
1. Subagent 只读，不修改文件。
2. 不运行破坏性命令。
3. 优先检查本次 diff。
4. 检查是否有无关修改。
5. 检查是否遗漏验收标准。
6. 检查是否需要补充测试或说明。
7. 最后由主会话汇总 Subagent 结论，并给出是否可以交付。

如果项目已经有自定义 Subagent，比如 tutorial-reviewer，可以更具体：

请使用 tutorial-reviewer 只读审查本次新增或修改的教程文档。

重点检查：
1. 是否有前置教程链接。
2. 是否存在跳步。
3. 是否有无法验证的断言。
4. 是否存在需要额外素材才能理解的步骤。
5. 是否有明显 AI 化话术。
6. 是否有验收标准。

不要修改文件，只输出问题和建议。

注意：第一版团队工作流不建议让多个 Subagent 并行改代码。
先让它们只读，稳定后再考虑更复杂的分工。

第 8 步：Hook 只做提醒，不做复杂判断

Hook 可以让流程更稳定，但也容易让系统变复杂。

第一版只建议保留一个低风险 Hook：

命令执行前提醒用户检查风险。

它可以提醒：

• 是否会删除文件。
• 是否会移动或覆盖文件。
• 是否会提交或推送。
• 是否会读取密钥。
• 是否会联网下载或上传。

不建议第一版 Hook 做：

• 自动拦截所有危险命令。
• 自动运行测试。
• 自动格式化全部代码。
• 自动提交 Git。
• 自动发布。

原因很简单：这些行为都有误伤成本。

更稳的做法是：

• 在任务提示词里写验收标准。
• 在 AGENTS.md 里写常用检查方式。
• 让 Codex 根据任务主动检查。
• Hook 先只负责提醒。

第 9 步：任务结束后做一次沉淀判断

每次任务结束后，不要马上结束会话。

让 Codex 判断有没有值得沉淀的经验：

请复盘本次任务是否有值得沉淀到项目工作流里的内容。

要求：
1. 不要修改文件，先只给建议。
2. 判断是否需要更新 AGENTS.md。
3. 判断是否需要新增或调整 Skill。
4. 判断是否需要新增或调整 Hook。
5. 判断是否需要新增或调整 Subagent。
6. 只推荐长期重复出现的问题。
7. 不要把本次临时需求写进长期规则。
8. 如果没有值得沉淀的内容，明确说不需要沉淀。

推荐判断标准：

情况	处理方式
Codex 又一次猜错项目命令	更新 AGENTS.md
同类教程反复缺少前置链接	更新教程审查 Skill 或 Subagent
每次执行命令前都需要提醒风险	保留低风险 Hook
只是本次页面的特殊需求	留在本次提示词，不沉淀
只是用户临时偏好	不写进项目规则

沉淀不是越多越好。
能长期减少重复沟通，才值得沉淀。

第 10 步：形成团队日常使用节奏

以后每个任务可以按这个节奏走：

1. 说清楚任务目标、范围、禁止事项和验收标准。
2. 要求 Codex 先读相关文件和 AGENTS.md。
3. Codex 说明理解和计划。
4. 你确认后再让 Codex 修改。
5. Codex 修改后主动检查。
6. 必要时使用只读 Subagent 做专项评审。
7. 你看总结、diff 和验证结果。
8. 任务结束后判断是否需要沉淀经验。

这套节奏适合个人，也适合小团队。

团队里真正需要统一的是：

• 什么信息必须写进任务。
• Codex 修改前必须先说明什么。
• 哪些文件不能碰。
• 哪些检查必须跑。
• 什么情况下可以交付。
• 什么经验值得沉淀。

一个完整任务示例

假设任务是修复一个前端页面 bug。

可以这样发给 Codex：

任务目标：
修复课程详情页在移动端标题换行异常的问题。

修改范围：
优先检查课程详情页组件和相关样式文件。
不要修改接口、鉴权、数据库、支付逻辑。

执行方式：
1. 先读取 AGENTS.md 和相关页面文件。
2. 先说明你理解的问题和计划。
3. 我确认后再修改。
4. 修改后检查 diff，确认没有无关改动。
5. 如果项目有可用构建或检查命令，请按 AGENTS.md 中确认过的方式执行。
6. 如果不能执行检查，请说明原因。

验收标准：
1. 移动端标题不会溢出容器。
2. 桌面端布局不变形。
3. 不影响课程内容渲染。
4. 最后用中文说明修改文件、修改原因、验证结果和未验证项。

如果 Codex 直接动手，没有先说明计划，就打断：

先暂停修改。
本项目要求修改前先说明理解和计划。
请先只读相关文件，说明问题原因、计划修改文件和预计风险。
等我确认后再改。

如果 Codex 修改范围变大，也打断：

请收窄范围。
本次只解决移动端标题换行异常，不做重构，不调整无关样式，不修改接口逻辑。
请说明当前 diff 中哪些改动和任务直接相关。

本篇验收标准

完成本篇后，你应该能判断：

• 当前任务限制放在提示词里。
• 长期项目规则放在 AGENTS.md。
• 模型、MCP、Hook、Subagent 等运行配置放在 config.toml 或 .codex/。
• 重复流程可以考虑 Skill。
• 外部资料访问才考虑 MCP。
• 生命周期提醒才考虑 Hook。
• 只读专项审查才优先考虑 Subagent。
• 每次任务结束后都要判断是否值得沉淀。

如果这些边界清楚，团队工作流就已经成型。

下一步可以继续写更具体的高阶实战：用 Codex 建立“提交前审查工作流”，把任务验收、Subagent 评审和 Git diff 检查组合起来。