中文 | English

codex-cli-best-practice

熟能生巧，Codex 更强。

= Agents · = Commands · = Skills

🧠 概念

功能	位置	说明
Commands	interactive session / slash popup	用于控制会话的内置斜杠命令，例如 /plan、/fast、/fork、/review、/status、/mcp、/agent、/apps、/model 和 /permissions
Subagents	.codex/agents/<name>.toml	通过专用 TOML 角色配置注册在 [agents.<name>] 下的自定义 agent，支持并行 subagent 编排与 CSV 批处理 · 全局设置位于 [agents]（max_threads、max_depth、job_max_runtime_seconds）· 内置：default、worker、explorer
Skills	.agents/skills/<name>/SKILL.md	参考 可复用的指令包，要求 name 与 description 元数据，并通过 scripts/、references/、assets/ 及可选的 agents/openai.yaml 实现渐进披露 · 可通过 /skills 或 $skill-name 显式调用，也可按描述匹配隐式触发 · 内置示例：$plan、$skill-creator、$skill-installer · 通过 Plugins 分发
Plugins	.codex-plugin/plugin.json	可分发的捆绑包，组合了 skills、app 集成和 MCP servers · 支持本地/个人 marketplace 体系 · 内置：$plugin-creator · 可通过 /plugins 或 Codex App 浏览
Workflows	.codex/agents/weather-agent.toml	端到端用法模式，例如解释代码库、修 bug、写测试、根据截图做原型、迭代 UI、委派到云端、做代码评审、更新文档
MCP Servers	config.toml → [mcp_servers.*]	用于外部工具的 Model Context Protocol，支持 STDIO + Streamable HTTP server · 支持 OAuth（codex mcp login）· 也可通过 codex mcp-server 作为 MCP server 暴露 codex() + codex-reply() 工具 · CLI 管理：`codex mcp add
Config	.codex/config.toml	基于 TOML 的分层配置系统 · Profiles · Sandbox · Approval Policy · Advanced（[features]、[otel]、[shell_environment_policy]、[tui]、模型 provider、细粒度审批）· 项目配置的 Trust 机制 · developer_instructions · model_instructions_file 用于自定义 system prompt
Rules	.codex/rules/	基于 Starlark 的命令执行策略，通过 prefix_rule() 做出 allow、prompt、forbidden 判定，并使用精确前缀匹配 · 可用 codex execpolicy check 测试 · Rules 与细粒度 approval_policy 控制及用户自管审批配合工作
AGENTS.md	AGENTS.md	Codex CLI 的项目级上下文文件，按 cwd 到仓库根的层级顺序发现，大小上限为 32 KiB（project_doc_max_bytes）· AGENTS.override.md 可用于个人覆盖
Hooks	.codex/hooks.json	注入 agentic loop 的用户自定义 shell 脚本，可用于日志、扫描、安全校验和自定义自动化 · 需开启 codex_hooks = true 功能开关
Speed	config.toml → service_tier	gpt-5.4 的 Fast Mode（1.5x 速度，2x 积分）· 通过 `/fast on
Code Review	/review	可评审分支、未提交改动或特定 commit · config.toml 中可配置 review_model · 支持自定义 review 指令
AI Terms		Agentic Engineering · Context Engineering · Vibe Coding
Best Practices		官方最佳实践 · Prompt Engineering · Codex Guides

关于 Agent → Skill 模式的实现细节，请参见 orchestration-workflow。这个 agent 会从 Open-Meteo 获取温度，并调用 SVG 生成 skill。

codex
> Fetch the current weather for Dubai in Celsius and create the SVG weather card output using the repo.

注： 这个工作流与 Claude Code Best Practice 中的 orchestration workflow 还没有做到完全同步。Codex CLI 目前尚不支持自定义 commands（.codex/commands/），因此还无法实现完整的 Command → Agent → Skill 模式。Codex App Server 文档中有实验性的 tool/requestUserInput，而 codex-cli 0.115.0 中也存在受开发中功能开关限制的内部 request_user_input 能力，但它们目前都还没有公开可用。

⚙️ 开发工作流

所有主要工作流最终都会收敛到同一个架构模式：Research → Plan → Execute → Review → Ship

名称	★	Uniqueness	Plan
Superpowers	134k		writing-plans	5	14
Spec Kit	85k		$speckit-plan	0	0
gstack	63k		autoplan	0	31
Get Shit Done	47k		gsd-planner	21	0
oh-my-codex	23k		ralplan	19	36
Compound Engineering	13k		ce-plan	49	42

其他

• 跨模型（Claude Code + Codex）工作流

💡 技巧与窍门（47）

Prompting · Planning · AGENTS.md · Agents · Skills · Hooks · Workflows · Advanced · Git / PR · Debugging · Utilities · Daily

■ Prompting（3）

建议
挑战 Codex，例如说“prove to me this works”，并让 Codex 比较 main 与你分支之间的差异
遇到平庸修复后，可以说“knowing everything you know now, scrap this and implement the elegant solution”
Codex 自己就能修大多数 bug：把 bug 贴进去，直接说“fix”，不要过度微操

■ Planning（4）

建议
当你需要显式计划时使用 /plan；Codex 也可能会对多步骤任务自动规划
始终制定分阶段、带闸门的计划，每个阶段都配多种测试（单元、自动化、集成）
启动第二个 Codex（或使用 cross-model）以 staff engineer 的视角复审你的计划
在交接执行前写出详细 spec，减少歧义；你越具体，输出通常越好

■ AGENTS.md（5）

建议
保持 AGENTS.md 简洁；150 行是个有用的经验值，但真正限制是按字节算的（32 KiB）
使用 AGENTS.override.md 保存个人偏好，而不影响团队
任何开发者都应该能启动 Codex、说一句“run the tests”，然后第一次就跑通；如果做不到，说明你的 AGENTS.md 缺了关键的 setup/build/test 命令
保持代码库整洁并完成迁移；半迁移状态的框架会让模型误选错误模式
把 harness 级的确定性行为放进 config.toml（如 approval policy、sandbox、model）；不要把本可由配置保证的行为规则塞进 AGENTS.md

Agents（3）

建议
创建特性专属的 sub-agents 和 skills，不要只设通用 qa、backend engineer 这种宽泛角色
用 multi-agent 向问题投入更多算力，把任务外包出去，让主上下文保持干净和聚焦
利用 test-time compute：彼此独立的上下文窗口通常能带来更好的结果，一个 agent 可能引入 bug，另一个则能把它找出来

Skills（7）

建议
使用带清晰 name 与 description frontmatter 的 skills，便于自动发现
skills 是文件夹，不是单个文件；使用 references/、scripts/、examples/ 子目录实现渐进披露
给每个 skill 建一个 Gotchas 区段，沉淀最高信号内容，并逐步补充 Codex 的失误点
skill description 字段是触发器，不是摘要；要按“模型何时该触发它”来写
不要在 skill 里写显而易见的话；重点是那些能把 Codex 拉出默认行为的内容
不要在 skill 里把 Codex 轨道化；给目标和约束，不要写死按部就班的流程
使用内置 skill creator 脚手架新 skill，并在整个仓库里统一记录一种调用风格

■ Hooks（2）

建议
用 hooks 做日志、扫描、安全校验和验证；需要开启 codex_hooks = true 功能开关
用 hooks 自动格式化代码；Codex 负责生成结构正确的代码，hook 负责最后 10%，从而避免 CI 因格式问题失败

■ Workflows（4）

建议
面对更小的任务时，原生 Codex 往往比任何工作流包装都更好
使用 profiles 在项目定义的安全级别之间切换；此仓库中 conservative 和 trusted 是示例
从 on-request 审批策略起步；只有在足够有把握时再升级到 never
使用会话内的 /fork（或 codex fork）探索备选方案，同时保留当前线程；再用 /resume（或 codex resume）回到原处

■ Workflows Advanced（5）

建议
使用 multi-agent 生成 sub-agent 做并行扇出工作（GA，默认启用）
使用 codex exec 跑无头/CI 管道
组合使用 sandbox modes 与 approval policies；workspace-write + on-request 是不错的默认值
用 git worktrees 做并行开发
频繁使用 ASCII 图来理解你的架构

■ Git / PR（3）

建议	来源
保持 PR 小而聚焦，一个 PR 只做一个 feature，便于 review 和回滚
始终使用 squash merge，让历史干净线性、一个 feature 对应一个 commit，也更利于 git revert 与 git bisect
任务一完成就尽快提交，保持高频 commit

■ Debugging（5）

建议	来源
始终让 Codex 把你想观察日志的终端任务作为后台任务运行，这样更利于调试
使用 MCP（Chrome DevTools、Playwright）让 Codex 自己查看浏览器 console 日志
遇到问题时养成截图并分享给 Codex 的习惯
用不同模型做 QA，例如让 Claude Code 负责计划与实现 review
agentic search（glob + grep）优于 RAG，因为代码会漂移、权限也很复杂

■ Utilities（4）

建议	来源
用 iTerm / Ghostty / tmux 这样的终端，而不是 IDE（VS Code / Cursor）
使用 Wispr Flow 做语音提示（生产率可达 10x）
用 codex-cli-hooks 给 Codex 做反馈增强
探索 config.toml 中的功能，比如 profiles、sandbox modes 和 MCP，打造个性化体验

■ Daily（2）

建议	来源
每天更新 Codex CLI
把阅读 changelog 作为一天的开始

文章 / 推文	来源
Codex 是如何构建的：90% 由自身用 Rust 构建（Tibo，Pragmatic Engineer）| 2026-02-17
Codex 中的 Skills：在各类 agent 之间标准化 .agents/skills（Embiricos）| 2026-02
展开 Codex agent loop：Codex 内部如何工作（Bolin）| 2026-01	Tweet
与 Codex 团队 AMA：CLI、sandbox、agents（Embiricos、Fouad、Tibo + team）| 2025-05	Reddit
Codex CLI：开源本地编码 agent 的首次上手（Fouad + Romain）| 2025-04	Tweet

🎬 视频 / 播客

视频 / 播客	来源	链接
Codex 高阶用户指南：并行工作流、规划、上下文工程（Embiricos）| 2026 | How I AI		Podcast
Scaffolding is coping not scaling，以及 Codex 的其他经验（Tibo）| 2026 | Dev Interrupted		Podcast
Codex 团队如何使用他们自己的编码 agent（Tibo + Andrew）| 2026-02-18 | Every		Podcast
Dogfood：Codex 团队用 Codex 构建 Codex（Tibo）| 2026-02-24 | Stack Overflow		Podcast
为什么人类是 AI 最大的瓶颈：Codex 产品愿景（Embiricos）| 2026-02 | Lenny's Podcast		Podcast
OpenAI and Codex（Tibo + Ed Bayes）| 2026-01-29 | Software Engineering Daily		Podcast

🔔 订阅

来源	名称	Badge
	r/ChatGPT、r/OpenAI、r/Codex
	OpenAI、OpenAI Devs、Tibo、Embiricos、Jason、Romain、Dominik、Fouad、Bolin
	Jesse Kriss（Superpowers）、Garry Tan（gstack）、Kieran Klaassen（Compound Eng）、Lex Christopherson（GSD）、Yeachan Heo（oh-my-codex）、Andrej Karpathy
	OpenAI
	Lenny's Podcast、The Pragmatic Engineer、Every

其他仓库

codex-cli-hooks · claude-code-best-practice · claude-code-hooks