# Codex 最佳实践：入门指南与提升效果的经验法则
**作者**: 爆裂队长NEXT
**日期**: 2026-05-31T14:17:32.000Z
**来源**: [https://x.com/thinkszyg/status/2061089701860352025](https://x.com/thinkszyg/status/2061089701860352025)
---
> Codex 不难上手，难的是让它每次都稳定干活。这份指南面向刚开始使用 Codex，或者刚接触 coding agent 的用户，重点讲一件事：怎么用更清楚的上下文、更合理的计划和更可靠的验证流程，拿到更好的结果。
*(视频内容)*
我不会给你讲，存在一个牛逼的提示词或者有啥神奇的魔法。无论如何，一开始都要遵循一组核心习惯和方法，即：怎么给 Codex 写任务，怎么先做计划，怎么验证结果，怎么接 MCP，怎么把重复流程做成 Skill，最后怎么把稳定任务交给 Automations。
这些方法适用于 Codex CLI、IDE Extension 和 Codex App。
Codex 最适合的用法，是把它当成一个可以长期配置、长期改进的队友，而不是一个临时问答助手。
可以这样理解整套流程：
先给对任务上下文。
再用 AGENTS.md 沉淀长期规则。
然后把 Codex 配成适合自己工作流的样子。
外部系统用 MCP 接进来。
重复工作做成 Skills。
稳定流程再交给 Automations。
## 第一次用好 Codex：上下文和提示词
Codex 本身已经很强。即使你的提示词不完美，它也经常能处理复杂问题，给出不错结果。
所以，清晰提示词不是使用 Codex 的门槛。
但它能让结果更稳定，尤其是面对大型代码库，或者风险比较高的任务。
如果你在一个复杂仓库里工作，真正能提升效果的点，是给 Codex 足够清楚的任务上下文，以及明确的任务结构。
一个默认好用的提示词，最好包含四件事：
1. 目标
你想改什么？想新增什么？想构建什么？
2. 上下文
哪些文件、目录、文档、示例、错误日志和这个任务有关？
在 Codex 里，你可以用 @ 提到具体文件，把它们作为上下文。
3. 约束
Codex 需要遵守哪些标准、架构、安全要求或项目约定？
4. 完成条件
什么状态才算完成？
比如测试通过、行为变化符合预期，或者某个 bug 不再复现。
这四件事能让 Codex 更容易守住任务边界，少做猜测，产出的结果也更方便人类 review。
以下是一个举例：
弱 prompt：“优化下单流程”。
强 prompt：
```
在 src/checkout/ 中，减少重复的支付校验逻辑。
保持公开 API 响应格式不变。
按照 src/orders/validation.ts 的模式来写。
补充或更新单元测试，跑通 checkout 测试套件，然后总结 diff。
```
差别在哪里？强 prompt 告诉 Codex：范围（src/checkout/）、约束（API 格式不变）、参考（validation.ts）、验收标准（测试通过 + diff）。
推理强度也要按任务难度来选。
官方建议大致是：
1. Low
适合速度优先、边界清楚的小任务。
2. Medium 或 High
适合更复杂的修改或调试。
3. Extra High
适合长时间运行、需要大量推理、Agent 自主性更强的任务。
不同用户、不同任务，最合适的设置可能不同。最好的办法还是自己测试，找到适合当前工作流的配置。
如果想更快给上下文，可以在 Codex App 里用语音输入，把任务直接说给 Codex，而不是慢慢打字。
## 难任务先做计划
如果任务复杂、模糊，或者很难一句话讲清楚，先让 Codex 做计划，再让它写代码。
几个方法都可以用。
使用 Plan mode
对大多数用户来说，这是最简单也最有效的方法。
Plan mode 会让 Codex 先收集上下文，提出澄清问题，形成更好的计划，然后再开始实现。
可以用 /plan 开启，也可以用 Shift 加 Tab 切换。
让 Codex 先采访你
如果你只有一个粗略想法，但还没想清楚怎么表达，可以先让 Codex 问你问题。
让它挑战你的假设，把模糊想法整理成具体需求，然后再开始写代码。
这对早期产品想法、复杂重构、模糊 bug 都很有用。
使用 PLANS.md 模板
如果你的工作流更高级，或者任务会持续比较久，可以配置 Codex 遵循 PLANS.md 或执行计划模板。
这样它在处理多步骤任务时，会按固定结构推进。
## 用 AGENTS.md 复用你的长期规则
当一个提示方式已经反复有效，下一步就别每次手动复制了。
这就是 AGENTS.md 的价值。
可以把 AGENTS.md 理解成写给 Agent 看的开放格式 README。
它会自动加载到上下文里，适合记录你和团队希望 Codex 在这个仓库里怎么工作。
一个好的 AGENTS.md 通常包括：
1. 仓库结构和重要目录。
2. 项目怎么运行。
3. build、test、lint 命令。
4. 工程约定和 PR 要求。
5. 约束条件和禁止事项。
6. 什么叫完成，以及怎么验证。
以下为举例 （Next.js SaaS 项目）：
```
# AGENTS.md — Acme SaaS
> Codex 启动时自动读取。写得越具体，Codex 输出质量越高。
---
## 1. 仓库结构
/
├── src/
│ ├── app/ # Next.js App Router（路由 + 页面）
│ ├── components/ # 共享 UI 组件
│ ├── lib/ # 工具函数、API 客户端、类型定义
│ ├── server/ # Server Actions、数据库查询
│ └── styles/ # 全局样式
├── prisma/ # Schema + 迁移文件
├── tests/
│ ├── unit/ # Vitest 单元测试
│ └── e2e/ # Playwright E2E 测试
├── docs/ # 项目文档
└── public/ # 静态资源
**关键规则**：
- `src/app/` 只放路由和页面，不要放业务逻辑
- 业务逻辑放 `src/server/`，通过 Server Actions 调用
- 组件放 `src/components/`，按功能分文件夹
---
## 2. 运行项目
bash
# 安装依赖（用 pnpm，不要用 npm 或 yarn）
pnpm install
# 启动开发服务器（http://localhost:3000）
pnpm dev
# 初始化数据库（首次运行）
pnpm db:setup # 等价于：prisma generate + prisma db push + prisma db seed
**前置条件**：
- Node.js 22+
- PostgreSQL 16+（本地或 Docker）
- `.env` 文件已配置 `DATABASE_URL`
---
## 3. 构建 / 测试 / Lint
bash
pnpm build # next build
pnpm test # vitest run
pnpm test:e2e # playwright test
pnpm lint # eslint . --ext .ts,.tsx
pnpm typecheck # tsc --noEmit
**CI 通过的硬性标准**：`pnpm lint && pnpm typecheck && pnpm test && pnpm build` 全部通过。
---
## 4. 工程约定
### 命名
- 变量 / 函数：`camelCase`
- React 组件：`PascalCase`
- 数据库字段：`snake_case`（Prisma 自动映射到 camelCase）
- 文件名：`kebab-case`（如 `user-settings.tsx`）
### TypeScript
- 禁止 `any`，用 `unknown` + 类型守卫
- 数据库查询返回值必须显式类型标注
- 导出的函数必须有返回类型
### Git
- 分支：`feature/xxx`、`fix/xxx`、`chore/xxx`
- Commit：遵循 Conventional Commits（`feat:` `fix:` `chore:`）
- PR 标题用中文描述实际改动，不要写 "fix bug"
### PR 要求
- 改动超过 200 行拆成多个 PR
- 新增接口必须有单元测试
- 数据库迁移单独一个 PR，不和业务逻辑混在一起
- PR 描述写清楚：改了什么、为什么改、怎么验证
---
## 5. 约束 & 禁止项
- **禁止**直接改 `prisma/schema.prisma` 后不生成迁移文件，必须跑 `pnpm db:migrate`
- **禁止**在组件里直接调 Prisma，必须通过 Server Actions 或 API Route
- **禁止**引入新的 npm 包不经过讨论（特别是体积 > 50KB 的包）
- **禁止**修改 `.env` 文件的内容，只能参考它的格式
- **禁止**删除或修改 `docs/` 下的任何文件
- **禁止**用 `console.log` 调试，用 `logger.info` / `logger.error`（已封装在 `src/lib/logger.ts`）
---
## 6. 完成标准 & 验证方式
### 什么叫"完成了"
- 代码通过所有 lint / typecheck / test / build
- 新功能有对应的单元测试（覆盖核心逻辑）
- 数据库变更附带迁移文件 + 回滚说明
- PR 描述完整，reviewer 不需要额外问"这是什么"
### 验证命令
bash
pnpm lint && pnpm typecheck && pnpm test && pnpm build
### Codex 自检流程（改动后必须跑）
1. `pnpm lint` — 风格检查
2. `pnpm typecheck` — 类型检查
3. `pnpm test` — 单元测试
4. `pnpm build` — 确认能构建成功
5. 检查 diff：确认只改了该改的文件
```
在 CLI 里，/init 是快速启动命令。
它会在当前目录生成一个初始版 AGENTS.md。
这个文件适合当起点，但生成之后要继续修改，让它符合团队真实的开发、测试、review 和发布方式。
AGENTS.md 可以放在不同层级。
个人默认规则可以放在 ~/.codex。
仓库共享规则可以放在项目根目录。
更具体的子目录，也可以有自己的 AGENTS.md。
如果当前目录附近有更具体的规则，Codex 会优先采用更靠近当前目录的那份规则。
这个文件要保持实用。
一份短而准确的 AGENTS.md，比一份写满空话的长文件有用得多。
可以先从基础内容开始，等发现 Codex 反复犯同类错误，再追加新规则。
如果 AGENTS.md 变得太长，可以让主文件保持简洁，再引用任务相关的 Markdown 文件，比如计划模板、代码 review 规则、架构说明。
当 Codex 第二次犯同一个错误时，可以让它做一次复盘，然后把真正有用的规则更新到 AGENTS.md。
这样规则会一直来自真实摩擦，而不是拍脑袋写出来。
## 配好 Codex，让它每次表现更一致
配置是让 Codex 在不同 session 和不同入口里保持一致的重要手段。
你可以配置默认模型、推理强度、sandbox mode、approval policy、profiles、MCP 等。
一个比较好的起点是：
1. 个人默认配置放在 ~/.codex/config.toml。
在 Codex App 里，可以从 Settings 进入 Configuration，再打开 config.toml。
2. 仓库专属配置放在 .codex/config.toml。
3. 命令行覆盖参数只用于一次性场景。
如果你用 CLI，这点尤其重要。
config.toml 适合放长期偏好，比如 MCP servers、多 Agent 设置、功能开关。
如果有不同 profile，可以放在单独的 $CODEX_HOME/profile-name.config.toml 文件里。
Codex 自带操作级别的 sandboxing，有两个关键开关：
1. Approval mode
决定 Codex 什么时候需要请求你的许可，才能运行某个命令。
2. Sandbox mode
决定 Codex 能不能读写目录，以及能访问哪些文件。
如果你刚开始用 coding agent，先用默认权限就好。
默认把 approval 和 sandboxing 收紧一点。
等你信任某个仓库，或者某条工作流真的需要更多权限，再逐步放开。
CLI、IDE 和 Codex App 共用同一套配置层。
所以，尽早按真实环境配置 Codex 很重要。
很多质量问题，其实是环境问题。
比如工作目录错了，缺少写权限，默认模型不对，工具或连接器没装好。
## 用测试和 review 提升可靠性
不要只让 Codex 改代码。
还要让它在需要时创建测试，运行相关检查，确认结果，并在你接受之前 review 它自己的改动。
Codex 可以自己完成这套循环，但前提是它知道什么叫“好”。
这些标准可以写在当前提示词里，也可以写进 AGENTS.md。
常见要求包括：
1. 为本次改动新增或更新测试。
2. 运行正确的测试集。
3. 检查 lint、格式化、类型检查。
4. 确认最终行为符合任务要求。
5. review diff，检查 bug、回归风险和危险模式。
在 Codex App 里，可以打开 diff panel，直接在本地 review 修改。
点击某一行就能给反馈，这些反馈会作为上下文进入 Codex 的下一轮。
这里还有一个很有用的 slash command：/review。
它支持几种 review 方式：
1. 基于某个 base branch 做类似 PR 的 review。
2. review 未提交改动。
3. review 某个 commit。
4. 使用自定义 review 指令。
如果团队有 code_review.md，并且在 AGENTS.md 里引用它，Codex 在 review 时也能跟着这套规则走。
这对团队保持跨仓库、跨贡献者的一致 review 行为很有帮助。
Codex 不该只负责生成代码。
给对指令之后，它也能帮你测试代码、检查代码、review 代码。
如果你使用 GitHub Cloud，还可以设置 Codex 给 PR 做代码审查。
OpenAI 内部的 PR 会由 Codex 进行 100% review。
你可以开启自动 review，也可以在 PR 里 @Codex，让它按需 review。
## 用 MCP 接入仓库外部的上下文
当 Codex 需要的上下文不在代码仓库里，就该考虑 MCP。
MCP 可以让 Codex 连接你已经在用的工具和系统，减少反复复制粘贴实时信息的麻烦。
MCP，全称 Model Context Protocol，是一种开放标准，用来把 Codex 连接到外部工具和系统。
这些情况适合使用 MCP：
1. Codex 需要的上下文在仓库外。
2. 数据经常变化。
3. 你希望 Codex 直接使用工具，而不是依赖你复制粘贴说明。
4. 你需要一个能跨用户、跨项目复用的集成。
Codex 支持两类 MCP server：
1. STDIO。
2. 带 OAuth 的 Streamable HTTP server。
在 Codex App 里，可以进入 Settings，再进入 MCP servers，查看自定义和推荐 servers。
很多时候，你可以直接让 Codex 帮你安装需要的 server。
CLI 里也可以使用 codex mcp add 命令，给自定义 server 添加名称、URL 和其他细节。
但工具不要一口气全接上。
只有当某个工具真的能打通一条真实工作流时，再加它。
先从一两个能明显减少手动循环的工具开始，然后再逐步扩展。
## 把重复工作做成 Skills
当某个工作流已经会反复出现，就不要继续依赖长提示词和反复对话了。
可以用 Skill 把说明、上下文和支持逻辑打包进 SKILL.md，让 Codex 在合适场景里稳定使用。
Skills 可以在 CLI、IDE Extension 和 Codex App 里使用。
每个 Skill 最好只负责一件事。
先从 2 到 3 个具体用例开始，定义清楚输入和输出，再写明这个 Skill 做什么、什么时候该用。
描述里要包含用户真实会说的触发语。
不要一开始就试图覆盖所有边界情况。
先选一个有代表性的任务，把它跑顺，再把这条流程变成 Skill，后面慢慢改进。
脚本和额外资源也不要乱加。
只有它们能提升可靠性时，再放进去。
一个简单判断是：
如果你一直复用同一段提示词，或者一直纠正同一套流程，那它大概率该变成 Skill。
Skills 特别适合这些重复任务：
1. 日志分诊。
2. 起草 release notes。
3. 按 checklist 做 PR review。
4. 迁移计划。
5. 遥测数据或事故总结。
6. 标准调试流程。
$skill-creator 是创建 Skill 初版的好起点。
第一版建议先留在本地迭代。
等它足够成熟，再打包成 plugin，分享给更多人使用。
Skill 最重要的部分之一是 description。
它要清楚说明这个 Skill 做什么，什么时候使用。
个人 Skills 存放在 $HOME/.agents/skills。
团队共享 Skills 可以放进仓库里的 .agents/skills。
这对新成员入门尤其有帮助。
## 用 Automations 处理重复任务
当一条工作流已经稳定，就可以安排 Codex 在后台定时运行。
在 Codex App 里，Automations 可以让你为重复任务选择项目、提示词、执行频率和运行环境。
当某个任务开始反复出现，就可以在 Codex App 的 Automations tab 里创建自动化。
你可以选择它在哪个项目里运行，运行什么提示词，也可以在提示词中调用 Skills。
还可以选择运行频率。
执行环境也可以选：
1. 在专用 git worktree 里运行。
2. 在本地环境里运行。
适合自动化的任务包括：
1. 总结最近 commits。
2. 扫描可能存在的 bug。
3. 起草 release notes。
4. 检查 CI failures。
5. 生成 standup summaries。
6. 定期运行重复分析流程。
一个好用的判断是：
Skills 定义方法，Automations 定义时间。
如果一条流程还需要大量人工引导，先把它做成 Skill。
等它足够可预测，再交给 Automation。
Automation 不只适合执行任务，也适合反思和维护。
比如回顾最近 sessions，总结重复摩擦，再持续改进 prompts、instructions 或工作流配置。
## 用 session controls 管理长期任务
Codex sessions 不只是聊天历史。
它们是工作线程，会随着时间积累上下文、决策和操作记录。
所以，管理 sessions 的方式，会直接影响 Codex 的工作质量。
Codex App 的 UI 最方便管理线程，因为可以 pin threads，也可以创建 worktrees。
如果你使用 CLI，这些 slash commands 很有用：
1. /experimental
开启实验功能，并写入 config.toml。
2. /resume
恢复一个保存过的对话。
3. /fork
在保留原始 transcript 的同时，创建一个新线程。
4. /compact
当线程变长时，把早期上下文压缩成摘要。
Codex 也会自动做 conversation compaction。
5. /agent
运行并行 agents 时，用它切换当前活跃的 agent thread。
6. /theme
选择语法高亮主题。
7. /apps
在 Codex 里直接使用 ChatGPT apps。
8. /status
查看当前 session 状态。
官方建议是一条原则：
一个线程对应一个连贯任务。
如果工作仍然属于同一个问题，留在同一个线程通常更好，因为它保留了推理轨迹。
只有当工作真的分叉时，再 fork。
Codex 的 subagent workflows 适合把有边界的工作从主线程里拆出去。
主 Agent 继续专注核心问题。
Subagents 可以负责探索、测试、分诊这类局部任务。
## 常见错误
刚开始用 Codex 时，官方提醒要避开这些坑：
1. 把长期规则全塞进提示词，没有迁移到 AGENTS.md 或 Skill。
2. 没有告诉 Agent 怎么运行 build 和 test，导致它看不到自己的工作结果。
3. 多步骤、复杂任务跳过计划阶段。
4. 还没理解工作流，就给 Codex 开放整台电脑的完整权限。
5. 多个 live threads 同时改同一批文件，却不使用 git worktrees。
6. 手动流程还不稳定，就急着做成 Automation。
7. 把 Codex 当成一个必须全程盯着看的东西，而不是让它和自己的工作并行。
8. 按项目开线程，而不是按任务开线程。
最后一个坑很常见。
一个项目只用一条线程，时间久了上下文会变得越来越臃肿，结果质量也会下降。
更好的方式是：一个任务，一条线程。
本文主要参考来源：https://developers.openai.com/codex/learn/best-practices
📚历史文章
1. 超级虚拟团队：多Agent协作实战指南
2. 我手搓了一个 Chrome 插件，把 X 收藏夹批量整理成 Obsidian 知识库
3. DeepSeek 一张 JD，就是 2026 年 AI 入行说明书
4. 别把 Codex 只当代码助手，它正在变成工作流系统
5. Codex 的 Pinned Threads，到底该怎么用？
6. Codex App 不折腾上手指南：先会这几个命令就够了
7. 保姆级：用AI搭建你的选题流水线，从信息源到选题入库全流程
8. 选题有了然后呢？从文案公式到去AI味，AI辅助写作全流程
9. 10 分钟搭一个会自己进化的知识库：Obsidian + Claude Code 实操
10. AnySearch：给 AI Agent 装上一双会搜索的眼睛
11. PICCO：一个学术验证的提示词框架，五个要素填完即用
12. Claude Code Sub-Agents 实战：如何让 5 个调研任务同时跑
13. AGENTS.md 完全指南 2026：规范、工具、示例
如果这篇对你有帮助，欢迎 关注 + 收藏 + 转发 👏🏻
关注 @thinkszyg，持续分享真实战，生产级，AI真干货。
## 相关链接
- [爆裂队长NEXT](https://x.com/thinkszyg)
- [@thinkszyg](https://x.com/thinkszyg)
- [196](https://x.com/thinkszyg/status/2061089701860352025/analytics)
- [$CODEX_HOME](https://x.com/search?q=%24CODEX_HOME&src=cashtag_click)
- [@Codex](https://x.com/@Codex)
- [$skill-creator](https://x.com/search?q=%24skill-creator&src=cashtag_click)
- [$HOME](https://x.com/search?q=%24HOME&src=cashtag_click)
- [https://developers.openai.com/codex/learn/best-practices](https://developers.openai.com/codex/learn/best-practices)
- [超级虚拟团队：多Agent协作实战指南](https://x.com/thinkszyg/status/2055586218973491708?s=20)
- [我手搓了一个 Chrome 插件，把 X 收藏夹批量整理成 Obsidian 知识库](https://x.com/thinkszyg/status/2055882529849344342?s=20)
- [DeepSeek 一张 JD，就是 2026 年 AI 入行说明书](https://x.com/thinkszyg/status/2056532044809990215?s=20)
- [别把 Codex 只当代码助手，它正在变成工作流系统](https://x.com/thinkszyg/status/2057427584909291987?s=20)
- [Codex 的 Pinned Threads，到底该怎么用？](https://x.com/thinkszyg/status/2057736054657130695?s=20)
- [Codex App 不折腾上手指南：先会这几个命令就够了](https://x.com/thinkszyg/status/2058004216904564747?s=20)
- [保姆级：用AI搭建你的选题流水线，从信息源到选题入库全流程](https://x.com/thinkszyg/status/2058411489908973679?s=20)
- [选题有了然后呢？从文案公式到去AI味，AI辅助写作全流程](https://x.com/thinkszyg/status/2058740603450806527?s=20)
- [10 分钟搭一个会自己进化的知识库：Obsidian + Claude Code 实操](https://x.com/thinkszyg/status/2059208197206868248?s=20)
- [AnySearch：给 AI Agent 装上一双会搜索的眼睛](https://x.com/thinkszyg/status/2059289301775741411?s=20)
- [PICCO：一个学术验证的提示词框架，五个要素填完即用](https://x.com/thinkszyg/status/2059568031513424020?s=20)
- [Claude Code Sub-Agents 实战：如何让 5 个调研任务同时跑](https://x.com/thinkszyg/status/2059839454588829707?s=20)
- [AGENTS.md 完全指南 2026：规范、工具、示例](https://x.com/thinkszyg/status/2060295182864814569?s=20)
- [@thinkszyg](https://x.com/@thinkszyg)
- [Upgrade to Premium](https://x.com/i/premium_sign_up)
- [10:17 PM · May 31, 2026](https://x.com/thinkszyg/status/2061089701860352025)
- [196 Views](https://x.com/thinkszyg/status/2061089701860352025/analytics)
---
*导出时间: 2026/5/31 23:21:54*