5 min read

小白上手10大最佳实践:Codex 入门指南

Source: http://x.com/i/article/2031035684174401536

本文翻译自

@derrickcchoi

https://x.com/derrickcchoi/status/2031023512534634758

如果你刚接触 OpenAI Codex 或编码 Agent,这篇指南能帮你更快上手。涵盖 CLI、IDE 插件、Codex App 的核心用法——从 prompt、规划、验证,到 MCP、skills 和自动化。

核心理念:把 Codex 当作队友而非一次性工具长期配置它,效果最好。

心智模型:任务上下文 → AGENTS.md 持久指引 → 配置匹配工作流 → MCP 连接外部系统 → 把重复工作变成 skill → 自动化稳定流程。

1. 正确的初始设置

Codex 即使 prompt 不完美也足够强,但清晰的 prompt 能让结果更可靠,尤其是在大型代码库或高风险任务中。

Prompt 四要素:

  • Goal:你想改什么、建什么?
  • Context:哪些文件、文档、示例、错误与任务相关?(可以用 @ 提及文件)
  • Constraints:什么标准、架构、安全要求需要遵守?
  • Done when:任务完成的前提是什么?(如测试通过、行为改变、Bug 修复)

Reasoning Effort 选择:

  • Low:快速、范围明确的任务
  • Medium / High:复杂改动或调试
  • Extra High:长链路、Agentic、强推理任务
💡 新人建议:用语音输入加速迭代,先从简单问题或小修复开始。

2. 复杂任务先让它规划

如果任务复杂、模糊或难以描述清楚,让 Codex 先规划再动手。

三种方式:

  • Plan mode(/plan 或 Shift+Tab):最简单有效,让 Codex 收集上下文、提问、形成计划
  • 让它访谈你:如果你有模糊想法,让 Codex 追问你,把模糊变具体PLANS.md
  • 模板:长期或多步骤任务的执行计划模板

3. 用 AGENTS.md 复用有效经验

一旦某种 prompt 模式有效,就不要再手动重复了。

AGENTS.md = 智能体的 README。自动加载到 context,是编码团队协作标准的最佳位置。

内容包括:

  • 代码库结构
  • 如何运行项目
  • 构建、测试、lint 命令
  • 工程规范和 PR 期望
  • 约束和禁忌
  • "完成"的定义及验证方式
💡 技巧:Codex 犯同样错误两次时,让它做回顾并更新 AGENTS.md。保持实用,别搞一堆模糊规则。

4. 配置匹配你的工作流

config.toml

是定义持久偏好的地方:MCP 服务器、profiles、多 agent 设置、实验性功能。

配置分层:

  • ~/.codex/config.toml:个人默认配
  • .codex/config.toml:仓库级配置
  • CLI 命令行覆盖:仅用于一次性场景

两个关键控制:

  • Approval mode:什么时候需要你批准执行命令
  • Sandbox mode:Agent 能读写哪些文件、访问什么目录
💡 建议:新人从保守的默认权限开始,熟悉后再对可信仓库放宽。

5. 让 Codex 测试、验证、审查

不要只让 Codex 改代码。告诉它:

  • 写或更新测试
  • 运行相关测试套件
  • 检查 lint、format、type
  • 确认行为符合预期
  • 审查 diff 中的 bug、回归、风险模式

/review 命令:

  • 对比 base branch 做 PR 式审查
  • 审查未提交的改动
  • 审查某个 commit
  • 自定义审查指令
💡 OpenAI 内 100% PR 都会经过 Codex review。

6. 用 MCP 连接外部工具

当 Codex 需要的上下文在代码库之外时,用 Model Context Protocol (MCP)。

适用场景:

  • 所需上下文在仓库外
  • 数据频繁变化
  • 想让 Codex 用工具而非靠粘贴指令
  • 跨用户/项目可重复的集成

不要一开始就接一堆工具。从一个高频手动循环开始,逐步扩展。

7. 把重复工作流变成 Skill

一旦工作流可重复,就别再用长 prompt 或反复对话了。用 Skill 打包:SKILL.md + 上下文 + 逻辑。

技巧:

  • 每个 skill 专注一件事
  • 从 2-3 个具体用例开始
  • 定义清晰的 input/output
  • 描述要说明"什么时候用"
💡 常用场景:日志分类、Release note 起草、PR 检查清单、迁移规划、调试流程

8. 自动化节省重复工作

工作流稳定后,用 Automations

定时运行。

设置:项目、prompt(可以调用 skill)、执行频率、环境(git worktree 或本地)

适用场景:

  • 汇总近期 commit
  • 扫描潜在 bug
  • 起草 release note
  • 检查 CI 失败
  • 生成 standup 摘要
💡 技巧:用自动化做反思和维护——回顾近期会话、总结反复出现的问题、优化 prompt。

9. 长时间工作的会话管理

Codex session 会累积上下文、决策、行动,管理好对质量影响很大。

App UI 技巧:pin threads、创建 worktrees

CLI 常用 slash commands:

  • /resume:恢复保存的对话
  • /fork:创建新分支同时保留原对话
  • /compact:长对话时压缩早期上下文
  • /agent:多 agent 时切换活跃 thread
💡 用 multi-agent 工作流把bounded work 剥离出主线程。

10. 常见错误避免

❌ 在 prompt 里塞一堆持久规则(应该放 AGENTS.md 或 skill)

❌ 不告诉它如何运行 build/test 命令

❌ 多步骤复杂任务跳过规划

❌ 还没搞清工作流就给全权限

❌ 同一文件开多 live threads 不用 git worktrees

❌ 手动还不可靠就急于设自动化

入门检查清单

  • 给 Codex 正确的 goal、context、constraints、done-when
  • 困难任务先让它规划
  • 创建 starter AGENTS.md
  • 告诉它如何 build、test、validate、review
  • 配置匹配你工作流的默认值
  • 为高价值外部工具添加 MCP
  • 把重复工作流变成 skill
  • 工作流稳定后用自动化

你把工作流、标准、上下文变成 Codex 可用的东西越多,它能做的事就越超乎想象。