小白上手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 可用的东西越多,它能做的事就越超乎想象。