\documentclass[a4paper]{article}

% Basic packages
\usepackage[fontset=fandol]{ctex}
\usepackage{amsmath, amssymb}
\usepackage{graphicx}
\usepackage[margin=2.5cm]{geometry}
\usepackage[most]{tcolorbox}
\usepackage{etoolbox}
\usepackage{listings}
\usepackage{hyperref}
\usepackage{booktabs}
\usepackage{subcaption}
\usepackage{float}
\usepackage{tikz}
\usepackage{enumitem}
\IfFileExists{pgfplots.sty}{
    \usepackage{pgfplots}
    \pgfplotsset{compat=1.18}
}{}

% Highlight boxes
\newtcolorbox{knowledgebox}[1]{
    enhanced, colback=blue!5!white, colframe=blue!75!black, colbacktitle=blue!75!black,
    coltitle=white, fonttitle=\bfseries, title=#1, attach boxed title to top left={yshift=-2mm, xshift=2mm},
    boxrule=1pt, sharp corners
}

\newtcolorbox{importantbox}[1]{
    enhanced, colback=yellow!10!white, colframe=yellow!80!black, colbacktitle=yellow!80!black,
    coltitle=black, fonttitle=\bfseries, title=#1, sharp corners
}

\newtcolorbox{warningbox}[1]{
    enhanced, colback=red!5!white, colframe=red!75!black, colbacktitle=red!75!black,
    coltitle=white, fonttitle=\bfseries, title=#1, sharp corners
}

% Listings
\lstset{
    language=Python,
    basicstyle=\ttfamily\small,
    keywordstyle=\color{blue},
    stringstyle=\color{red!60!black},
    commentstyle=\color{green!60!black},
    breaklines=true,
    frame=single,
    numbers=left,
    numberstyle=\tiny\color{gray},
    captionpos=b,
    extendedchars=false
}

% Front-page metadata
\newcommand{\notetitle}{OpenAI Codex 最佳实践}
\newcommand{\noteauthors}{基于公开课程资料整理}
\newcommand{\notedate}{2025}
\newcommand{\videochannel}{OpenAI}
\newcommand{\videopublishdate}{2025}
\newcommand{\videoduration}{--}
\newcommand{\videourl}{https://developers.openai.com/codex/learn/best-practices}
\newcommand{\videocoverpath}{}

\begin{document}

\begin{titlepage}
\centering
{\Large 文章笔记\par}
\vspace{1.2cm}
{\huge\bfseries \notetitle\par}
\vspace{0.8cm}
{\large \noteauthors\par}
\vspace{0.3cm}
{\large \notedate\par}
\vspace{1.5cm}

\vfill
\begin{tcolorbox}[width=0.9\textwidth, colback=black!2!white, colframe=black!60, sharp corners]
\textbf{作者/来源}：\videochannel\par
\textbf{发布日期}：\videopublishdate\par
\textbf{文章链接}：\href{\videourl}{\nolinkurl{\videourl}}
\end{tcolorbox}
\end{titlepage}

\tableofcontents
\newpage

%% --- 正文内容开始 --- %%

\section{引言}

OpenAI Codex 是一款 coding agent，支持 CLI、IDE 扩展和 Codex App 三种使用方式。本文档是 OpenAI 官方发布的 Codex 最佳实践指南，覆盖了从 prompting、规划、配置到 MCP 集成、Skills 封装和自动化调度的完整工作流。

\begin{importantbox}{核心理念}
不要把 Codex 当成一次性的助手，而应当视其为一个\textbf{需要持续配置和改进的队友}。核心路径：正确的任务上下文 $\rightarrow$ AGENTS.md 持久化指导 $\rightarrow$ 配置标准化 $\rightarrow$ MCP 外部集成 $\rightarrow$ Skills 封装 $\rightarrow$ Automations 自动化。
\end{importantbox}

\subsection{本章小结}

本文围绕六大主题展开：Prompt 编写、AGENTS.md 配置、系统配置、MCP 外部工具集成、Skills 技能封装、以及 Automations 自动化，旨在帮助用户从"能用"走向"好用"。

%% ============================================================
\section{Prompt 编写与上下文管理}
%% ============================================================

\subsection{结构化 Prompt 的四要素}

Codex 即使在 prompt 不够完善时也能给出不错的结果，但在大型代码库或高风险任务中，结构化的 prompt 能显著提升可靠性。官方推荐在每个 prompt 中包含以下四个要素：

\begin{importantbox}{Prompt 四要素}
\begin{enumerate}[nosep]
    \item \textbf{Goal}（目标）：你想要修改或构建什么？
    \item \textbf{Context}（上下文）：哪些文件、目录、文档、示例或错误与本任务相关？可用 \texttt{@} 引用文件。
    \item \textbf{Constraints}（约束）：需要遵守哪些标准、架构要求、安全规则或编码规范？
    \item \textbf{Done when}（完成条件）：任务完成时应当满足什么条件？例如测试通过、行为变更或 bug 不再复现。
\end{enumerate}
\end{importantbox}

这四个要素帮助 Codex 限定作用范围、减少假设，并产出更容易 review 的代码。

\subsection{Reasoning Level 选择}

Codex 支持多个推理等级，适配不同任务复杂度：

\begin{table}[H]
\centering
\begin{tabular}{ll}
\toprule
\textbf{推理等级} & \textbf{适用场景} \\
\midrule
Low & 边界清晰的快速任务 \\
Medium / High & 较复杂的代码变更或调试 \\
Extra High & 长链路、高推理需求的 agent 任务 \\
\bottomrule
\end{tabular}
\caption{Reasoning Level 与任务复杂度的对应关系}
\end{table}

\begin{knowledgebox}{语音输入加速上下文提供}
在 Codex App 中，可以使用语音听写（speech dictation）来口述任务需求，而不是手动打字。这对需要提供大量上下文的场景尤其高效。
\end{knowledgebox}

\subsection{复杂任务先规划再执行}

对于复杂、模糊或难以描述的任务，应当让 Codex 先做规划（planning），再进入实现阶段。官方推荐三种方式：

\begin{enumerate}
    \item \textbf{Plan mode}：通过 \texttt{/plan} 或 \texttt{Shift+Tab} 切换。Codex 会先收集上下文、提出澄清问题，再制定实施方案。这是大多数用户最简单有效的选择。
    \item \textbf{让 Codex 采访你}：当你有模糊的想法但不知如何表述时，让 Codex 主动提问、挑战你的假设，把模糊想法转化为具体方案。
    \item \textbf{PLANS.md 模板}：对于更高级的工作流，可配置 Codex 遵循 \texttt{PLANS.md} 或 execution-plan 模板，适用于长期运行或多步骤工作。
\end{enumerate}

\begin{warningbox}{常见错误：跳过规划}
在多步骤和复杂任务中跳过规划（planning）是最常见的错误之一。直接开始编码往往导致方向偏差和大量返工。
\end{warningbox}

\subsection{本章小结}

好的 prompt 包含目标、上下文、约束和完成条件四个要素。根据任务复杂度选择合适的 reasoning level。对于复杂任务，使用 Plan mode 或让 Codex 先采访你，避免直接进入实现。

%% ============================================================
\section{AGENTS.md：持久化指导}
%% ============================================================

\subsection{什么是 AGENTS.md}

\texttt{AGENTS.md} 是一个开放格式的文件，可以理解为\textbf{给 agent 看的 README}。它会被自动加载到上下文中，是编码团队标准化 Codex 行为的最佳位置。

\begin{importantbox}{AGENTS.md 应覆盖的内容}
\begin{itemize}[nosep]
    \item 仓库布局和重要目录
    \item 项目运行方式
    \item Build、test、lint 命令
    \item 工程规范和 PR 期望
    \item 约束和"不要做"规则
    \item "完成"的定义及验证方式
\end{itemize}
\end{importantbox}

\subsection{多级 AGENTS.md 体系}

Codex 支持在多个层级放置 \texttt{AGENTS.md}，形成层级覆盖机制：

\begin{itemize}
    \item \textbf{全局级}：\texttt{\textasciitilde/.codex/AGENTS.md}，存放个人默认偏好
    \item \textbf{仓库级}：项目根目录的 \texttt{AGENTS.md}，存放团队共享标准
    \item \textbf{子目录级}：特定目录中的 \texttt{AGENTS.md}，存放局部规则
\end{itemize}

\begin{knowledgebox}{就近优先原则}
当多个层级存在 \texttt{AGENTS.md} 时，离当前工作目录更近的文件优先级更高。这类似于 \texttt{.gitignore} 的覆盖逻辑。
\end{knowledgebox}

\subsection{编写原则}

\begin{itemize}
    \item \textbf{保持简洁}：短而准确的 \texttt{AGENTS.md} 比冗长模糊的规则有用得多
    \item \textbf{按需添加}：先写基础内容，只在发现重复性错误后才添加新规则
    \item \textbf{拆分引用}：当文件过大时，保持主文件精简，并引用任务级别的 markdown 文件（如 code\_review.md、architecture.md）
    \item \textbf{回顾驱动}：当 Codex 犯同样的错误两次时，让它做 retrospective 并更新 \texttt{AGENTS.md}
\end{itemize}

\begin{warningbox}{常见错误：在 Prompt 中堆积持久性规则}
把本应写在 \texttt{AGENTS.md} 中的持久性规则反复写在 prompt 里，是使用 Codex 时最常见的反模式之一。应当将经过验证的 prompting 模式迁移到 \texttt{AGENTS.md} 中。
\end{warningbox}

CLI 中可以使用 \texttt{/init} 命令快速生成一份 starter \texttt{AGENTS.md}。

\subsection{本章小结}

\texttt{AGENTS.md} 是 Codex 持久化指导的核心机制。通过多级文件体系实现全局、仓库和目录级别的规则覆盖。保持文件简洁、按需迭代，并利用 retrospective 机制持续改进。

%% ============================================================
\section{系统配置}
%% ============================================================

\subsection{config.toml 配置体系}

Codex 的配置通过 \texttt{config.toml} 文件管理，支持两个层级：

\begin{itemize}
    \item \textbf{个人默认}：\texttt{\textasciitilde/.codex/config.toml}（通过 Codex App 的 Settings $\rightarrow$ Configuration $\rightarrow$ Open config.toml 打开）
    \item \textbf{仓库特定}：\texttt{.codex/config.toml}，存放项目级别的行为配置
    \item \textbf{命令行覆盖}：仅用于一次性场景（CLI 用户）
\end{itemize}

可配置项包括：model 选择、reasoning effort、sandbox mode、approval policy、profiles、MCP setup 等。

\subsection{Sandbox 与 Approval 机制}

Codex 内置操作系统级别的沙箱机制，提供两个关键控制旋钮：

\begin{importantbox}{两个安全控制旋钮}
\begin{itemize}[nosep]
    \item \textbf{Approval mode}：决定 Codex 何时需要请求你的许可才能执行命令
    \item \textbf{Sandbox mode}：决定 Codex 能否在目录中读写，以及可以访问哪些文件
\end{itemize}
\end{importantbox}

\begin{warningbox}{新手建议：先紧后松}
如果你刚接触 coding agent，应当保持默认的严格权限。只在了解工作流、确认信任特定仓库后，才逐步放宽权限。不要一开始就给 Codex 完全的系统权限。
\end{warningbox}

\begin{knowledgebox}{CLI、IDE 和 App 共享配置}
CLI、IDE 扩展和 Codex App 共享同一套配置层级。在任一端修改配置都会影响其他端的行为。
\end{knowledgebox}

\subsection{本章小结}

通过 \texttt{config.toml} 的个人级和仓库级配置实现一致性行为。Sandbox 和 Approval 是两个核心安全旋钮，建议新手从严格权限开始，逐步放宽。

%% ============================================================
\section{测试与代码审查}
%% ============================================================

\subsection{闭环验证流程}

不要仅仅让 Codex 做代码变更就结束。应当要求它完成完整的验证闭环：

\begin{enumerate}[nosep]
    \item 为变更编写或更新测试
    \item 运行相关的测试套件
    \item 检查 lint、格式化或类型检查
    \item 确认最终行为与需求一致
    \item 检查 diff 中是否存在 bug、回归或风险模式
\end{enumerate}

\begin{importantbox}{关键前提：让 Codex 知道什么是"好"}
Codex 能够执行这个验证闭环，但前提是它知道什么算"好"。这些信息可以来自 prompt 或 \texttt{AGENTS.md}，包括测试命令、lint 配置、代码风格期望等。
\end{importantbox}

\subsection{/review 命令}

\texttt{/review} 是一个内置的代码审查命令，支持多种审查模式：

\begin{itemize}
    \item 对比 base branch 进行 PR 风格审查
    \item 审查未提交的变更
    \item 审查某个特定 commit
    \item 使用自定义审查指令
\end{itemize}

如果团队有 \texttt{code\_review.md} 文件并在 \texttt{AGENTS.md} 中引用，Codex 在审查时也会遵循该指导。

\begin{knowledgebox}{GitHub Cloud 集成}
如果使用 GitHub Cloud，可以设置 Codex 自动审查 PR。在 OpenAI 内部，Codex 审查了 100\% 的 PR。可以启用自动审查，也可以在需要时通过 \texttt{@Codex} 触发审查。
\end{knowledgebox}

\subsection{本章小结}

Codex 不仅能生成代码，还能测试、检查和审查代码。通过 \texttt{/review} 命令和 \texttt{code\_review.md} 配置，实现团队级别一致的代码审查标准。在 GitHub Cloud 上还可以实现全自动 PR 审查。

%% ============================================================
\section{MCP：外部工具集成}
%% ============================================================

\subsection{什么是 MCP}

Model Context Protocol（MCP）是一个开放标准，用于将 Codex 连接到外部工具和系统。当 Codex 所需的上下文不在代码仓库中时，MCP 就是解决方案。

\begin{importantbox}{何时使用 MCP}
\begin{itemize}[nosep]
    \item 所需上下文在仓库之外（如 issue tracker、monitoring 系统）
    \item 数据频繁变化（如实时指标、日志）
    \item 希望 Codex 使用工具而非依赖粘贴的指令
    \item 需要跨用户、跨项目的可复用集成
\end{itemize}
\end{importantbox}

\subsection{MCP 的配置方式}

Codex 支持两种 MCP server 类型：

\begin{itemize}
    \item \textbf{STDIO}：标准输入/输出通信
    \item \textbf{Streamable HTTP}：支持 OAuth 认证的 HTTP 通信
\end{itemize}

配置入口：
\begin{itemize}
    \item Codex App：Settings $\rightarrow$ MCP servers
    \item CLI：使用 \texttt{codex mcp add} 命令添加自定义 server
\end{itemize}

\begin{warningbox}{不要一次性接入所有工具}
只在工具确实能解锁某个真实工作流时才添加。不要一开始就把所有常用工具都接入。从 1--2 个明确能消除手动重复操作的工具开始，然后逐步扩展。
\end{warningbox}

\subsection{本章小结}

MCP 是 Codex 连接外部系统的标准协议，支持 STDIO 和 Streamable HTTP 两种模式。按需接入、从小处开始是正确的使用策略。

%% ============================================================
\section{Skills：技能封装}
%% ============================================================

\subsection{什么是 Skill}

当某个工作流变得可重复，就不应继续依赖长 prompt 或反复的交互。Skill 将指令（\texttt{SKILL.md} 文件）、上下文和支持逻辑封装为一个可跨 CLI、IDE 和 App 一致调用的单元。

\begin{importantbox}{Skill 设计原则}
\begin{itemize}[nosep]
    \item 每个 skill 聚焦于一个任务
    \item 从 2--3 个具体用例出发
    \item 定义清晰的输入和输出
    \item 描述（description）要说明 skill 做什么、何时使用
    \item 包含用户实际会说的触发短语
\end{itemize}
\end{importantbox}

\subsection{适用场景}

Skills 特别适合以下类型的重复性工作：

\begin{itemize}
    \item 日志分类（Log triage）
    \item Release notes 起草
    \item 按 checklist 进行 PR 审查
    \item 迁移规划（Migration planning）
    \item 遥测或事件摘要（Telemetry / incident summaries）
    \item 标准调试流程
\end{itemize}

\begin{knowledgebox}{Skill 的存储位置}
\begin{itemize}[nosep]
    \item \textbf{个人 skills}：\texttt{\$HOME/.agents/skills/}
    \item \textbf{团队共享 skills}：仓库内的 \texttt{.agents/skills/} 目录
\end{itemize}
团队共享的 skills 对新成员的 onboarding 尤其有帮助。
\end{knowledgebox}

可以使用内置的 \texttt{\$skill-creator} skill 来快速生成第一版 skill。建议在本地迭代稳定后，再打包为 plugin 进行更广泛的分享。

\begin{knowledgebox}{经验法则}
如果你发现自己反复使用同一个 prompt，或反复纠正同一个工作流，它就应该成为一个 skill。
\end{knowledgebox}

\subsection{本章小结}

Skill 是将验证过的工作流封装为可复用单元的机制。聚焦单一任务、从具体用例出发、先本地迭代后再分享。

%% ============================================================
\section{Automations：自动化调度}
%% ============================================================

\subsection{从 Skill 到 Automation}

当一个工作流已经稳定可靠，就可以用 Automation 让 Codex 在后台按计划自动执行。

\begin{importantbox}{Skills vs Automations}
\textbf{Skills 定义方法，Automations 定义调度。}如果一个工作流仍然需要大量人工干预，应当先将其封装为 skill。只有当它足够可预测时，automation 才能真正发挥乘数效应。
\end{importantbox}

\subsection{适用场景}

好的 automation 候选包括：

\begin{itemize}
    \item 汇总近期 commits
    \item 扫描潜在 bug
    \item 起草 release notes
    \item 检查 CI 失败
    \item 生成 standup 摘要
    \item 按计划运行重复性分析
\end{itemize}

在 Codex App 的 Automations 标签页中，可以选择：
\begin{itemize}
    \item 运行的项目
    \item 执行的 prompt（可调用 skills）
    \item 运行的节奏/频率
    \item 执行环境（dedicated git worktree 或本地环境）
\end{itemize}

\begin{warningbox}{先手动验证，再自动化}
在工作流手动运行已经可靠之前，不要将其转为 automation。过早自动化不可靠的任务只会放大错误。
\end{warningbox}

\begin{knowledgebox}{用 Automation 做反思和维护}
Automation 不仅仅用于执行任务。还可以用来审查近期 session、汇总重复性摩擦、改进 prompt 和工作流设置。
\end{knowledgebox}

\subsection{本章小结}

Automation 是将稳定 skill 按计划自动执行的机制。先确保手动运行可靠，再自动化。可用于执行，也可用于反思和维护。

%% ============================================================
\section{Session 管理与常用命令}
%% ============================================================

\subsection{Session 的本质}

Codex 的 session 不只是聊天记录，而是随时间累积上下文、决策和操作的\textbf{工作线程}。良好的 session 管理对输出质量有重要影响。

\subsection{常用 Slash 命令}

\begin{table}[H]
\centering
\begin{tabular}{ll}
\toprule
\textbf{命令} & \textbf{功能} \\
\midrule
\texttt{/plan} & 切换到规划模式 \\
\texttt{/review} & 代码审查 \\
\texttt{/init} & 生成 starter AGENTS.md \\
\texttt{/experimental} & 切换实验性功能 \\
\texttt{/resume} & 恢复保存的会话 \\
\texttt{/fork} & 创建新线程并保留原始记录 \\
\texttt{/compact} & 压缩/总结较早的上下文 \\
\texttt{/agent} & 切换并行 agent 线程 \\
\texttt{/theme} & 选择语法高亮主题 \\
\texttt{/apps} & 在 Codex 中使用 ChatGPT apps \\
\texttt{/status} & 查看当前 session 状态 \\
\bottomrule
\end{tabular}
\caption{Codex 常用 Slash 命令一览}
\end{table}

\begin{importantbox}{一任务一线程}
保持\textbf{一个线程对应一个连贯的工作单元}。只有当工作真正产生分支时才使用 \texttt{/fork}。使用一个线程管理整个项目（而非单个任务）会导致上下文膨胀，降低输出质量。
\end{importantbox}

\begin{knowledgebox}{Subagent 工作流}
可以使用 Codex 的 subagent 功能将有限的工作从主线程卸载出去。主 agent 保持聚焦于核心问题，subagent 处理探索、测试或分类等辅助任务。
\end{knowledgebox}

\subsection{本章小结}

Session 是积累上下文的工作线程。通过 slash 命令管理线程、压缩上下文、分叉和切换 agent。坚持"一任务一线程"的原则，使用 subagent 卸载辅助工作。

%% ============================================================
\section{常见错误}
%% ============================================================

以下是官方总结的使用 Codex 时最常见的错误：

\begin{warningbox}{八大常见错误}
\begin{enumerate}[nosep]
    \item 在 prompt 中堆积持久性规则，而不是迁移到 \texttt{AGENTS.md} 或 skill
    \item 没有告诉 agent 如何运行 build 和 test 命令，导致它看不到自己工作的结果
    \item 在多步骤复杂任务中跳过规划
    \item 在理解工作流之前就给 Codex 完全的系统权限
    \item 在同一批文件上运行多个活跃线程，而不使用 git worktree
    \item 在工作流手动运行尚不可靠时就将其转为 automation
    \item 把 Codex 当成需要逐步看管的工具，而不是与自己并行工作的队友
    \item 使用一个线程管理整个项目而非每个任务一个线程，导致上下文膨胀
\end{enumerate}
\end{warningbox}

\subsection{本章小结}

避免上述八大常见错误，核心原则是：持久化规则写入 \texttt{AGENTS.md}、复杂任务先规划、权限先紧后松、并行而非看管、一任务一线程。

%% ============================================================
\section{总结与延伸}
%% ============================================================

本文系统梳理了 OpenAI Codex 的最佳实践，核心思路可以用一条渐进路径总结：

\begin{importantbox}{Codex 使用的渐进路径}
\textbf{结构化 Prompt} $\rightarrow$ \textbf{AGENTS.md 持久化} $\rightarrow$ \textbf{config.toml 标准化} $\rightarrow$ \textbf{MCP 外部集成} $\rightarrow$ \textbf{Skills 封装} $\rightarrow$ \textbf{Automations 调度}
\end{importantbox}

几个值得深入关注的方向：

\begin{itemize}
    \item \textbf{AGENTS.md 的团队协作模式}：如何在多人团队中维护和演进 \texttt{AGENTS.md}，使其成为活的工程规范文档
    \item \textbf{MCP 生态}：随着 MCP 作为开放标准的发展，更多第三方工具将可通过 MCP 接入 Codex
    \item \textbf{Skill 的 Plugin 化}：从个人本地 skill 到团队共享 plugin 的路径，是提升组织效能的关键
    \item \textbf{Automation 的反思性用法}：不仅用 automation 执行重复任务，还可用于定期回顾和改进工作流本身
\end{itemize}

\subsection{拓展阅读}

\begin{itemize}
    \item OpenAI Codex 官方文档：\url{https://developers.openai.com/codex}
    \item Codex Prompting Guide：\url{https://developers.openai.com/codex/learn}
    \item Model Context Protocol (MCP) 规范：\url{https://modelcontextprotocol.io}
    \item Codex 配置参考：\url{https://developers.openai.com/codex/docs/configuration}
\end{itemize}

%% --- 正文内容结束 --- %%

\end{document}
