Codex CLI 系统提示词深度解析：gpt-5.2-codex_prompt.md 的设计与加载机制

codex-rs/core/gpt-5.2-codex_prompt.md 是本项目（面向 GPT-5.2 等开放模型部署的 Codex 编码智能体）为 gpt-5.2-codex 模型预设的完整系统提示词源文件，定义了智能体在终端中编辑代码、操作 git、执行命令、输出最终回复时的全部行为准则。本文逐节解读该提示词的七大部分（编辑约束、计划工具、评审模式、前端设计、回复格式等），并结合 models-manager 与 session 的源码，说明这段提示词如何从文件变成对话历史中的 developer 消息，以及你如何用 model_instructions_file 配置替换它。

一、这份文件是什么：模型级系统提示词的“单一事实来源”

文件第一行即角色声明：

You are Codex, based on GPT-5. You are running as a coding agent in the Codex CLI on a user's computer.

它不是一段文档，而是一份运行时注入的指令集：当用户将模型配置为 gpt-5.2-codex 时，核心会话会把这份提示词渲染为 base_instructions，并在每一轮请求中作为 developer 消息置于对话历史最前面，决定模型“如何做事”而非“做什么”。

在 codex-rs/core/ 目录下存在一整套按模型划分的提示词源文件，构成模型目录的提示词体系：

文件	作用
gpt-5.2-codex_prompt.md	gpt-5.2-codex 的完整系统提示词（本文主角，独立自洽，无变量占位符）
gpt-5.1-codex-max_prompt.md	GPT-5.1-codex-max 模型的提示词变体
gpt_5_codex_prompt.md / gpt_5_1_prompt.md / gpt_5_2_prompt.md	其他 GPT-5 系列模型的提示词
prompt_with_apply_patch_instructions.md	面向原生 apply_patch 工具的提示词，由 session 测试 直接断言其被逐字注入
templates/model_instructions/	渲染用模板目录，其中的 gpt-5.2-codex_instructions_template.md 是带 {{ personality }} 占位符的等价变体

从源码结构看，gpt-5.2-codex_prompt.md 与 templates/model_instructions/gpt-5.2-codex_instructions_template.md 内容高度同源：模板版增加了 {{ personality }} 变量和更细化的 “Final answer formatting rules”，而 gpt-5.2-codex_prompt.md 是面向 Codex CLI 的定稿版本（开头为 "You are running as a coding agent in the Codex CLI on a user's computer"），并额外强调 "You are producing plain text that will later be styled by the CLI"。

二、General：工具偏好基线

提示词的第一条通用规则：

- When searching for text or files, prefer using `rg` or `rg --files` respectively because
  `rg` is much faster than alternatives like `grep`. (If the `rg` command is not found, then use alternatives.)

这条规则直接对应仓库的发布形态：CLI 分发包内置了 ripgrep，见 scripts/codex_package/ripgrep.py 与包内二进制 scripts/codex_package/rg。提示词先声明首选工具、再给出降级路径（"If the rg command is not found, then use alternatives"），这是典型的“能力探测式”指令写法——不假设环境，而是给出条件分支。

三、Editing constraints：脏工作区与破坏性操作守则

这是全文安全约束最密集的一节，核心是为“人机共享同一工作区”的场景划清边界：

• ASCII 默认原则：编辑或新建文件时默认使用 ASCII，仅当文件本身已使用且理由充分时才引入非 ASCII/Unicode 字符，避免引入编码混乱。
• 克制注释：只在代码不自解释时添加简洁注释，明确反例是 "Assigns the value to the variable" 这类空转注释；对复杂代码块前的简短导读性注释则是有价值的，但应“罕见”。
• apply_patch 的使用边界：单文件编辑优先用 apply_patch，但不适用于两类场景——自动生成的变更（如生成 package.json、运行 gofmt 等 lint/format 命令），以及脚本化更高效的操作（如全库搜索替换）。这与 prompt_with_apply_patch_instructions.md 中针对原生工具模型的更严格表述形成对照。
• 脏 git 工作区四步守则：
  1. 绝不回滚非自己所做的既有变更（那些是用户改的），除非用户明确要求；
  2. 被要求提交/编辑时，若文件中存在与任务无关的他人改动，不要回滚；
  3. 若改动落在自己刚改过的文件里，先仔细读取并理解如何与之协作，而不是撤销；
  4. 与任务无关文件中的改动直接忽略。
• 不擅自 amend：除非用户明确要求，不做 git commit --amend。
• 意外变更即停：工作中若发现自己未做的意外变更，立即停止（STOP IMMEDIATELY）并询问用户如何继续。
• 破坏性命令禁令：NEVER 使用 git reset --hard、git checkout -- 等破坏性命令，除非被明确请求或批准。

四、Plan tool：计划工具的反过度设计条款

- Skip using the planning tool for straightforward tasks (roughly the easiest 25%).
- Do not make single-step plans.
- When you made a plan, update it after having performed one of the sub-tasks that you shared on the plan.

三条规则共同压制两类常见智能体坏行为：用单步“假计划”凑数、以及计划陈旧不更新。结合仓库中同源的 GPT-5.2 提示词（内嵌于 models-manager/models.json 的 instructions_template），可以看到同一意图的展开版：update_plan 工具要求"exactly one item in_progress at a time"、禁止把 pending 直接跳到 completed、调用 update_plan 后不要复述计划全文（harness 已展示）、并给出了高/低质量计划的对照示例。gpt-5.2-codex_prompt.md 是这一大段的精简定稿。

五、Special user requests：命令式小请求与 Review 心智模型

• 能用终端命令直接满足的简单请求（例如问时间 → 跑 date）应直接执行，而不是口头回答。
• 用户说 "review" 时默认进入代码评审心智模型：优先找 bug、风险、行为回归、缺失测试。输出顺序被严格规定——
  1. 先列发现（按严重度排序，带 file/line 引用）；
  2. 再列开放问题或假设；
  3. 变更摘要只作为次要内容放在最后；
  4. 若无发现，必须明确说明，并指出残留风险或测试缺口。

仓库中还有针对“自动评审”的独立文档 docs/auto-review.md，提示词里的评审输出契约与该功能的呈现逻辑一致。

六、Frontend tasks：反 “AI slop” 设计守则

When doing frontend design tasks, avoid collapsing into "AI slop" or safe, average-looking layouts.
Aim for interfaces that feel intentional, bold, and a bit surprising.

随后给出五个维度的硬约束：

• Typography：用有表现力、有目的的字体，避开 Inter/Roboto/Arial/system 等默认栈；
• Color & Look：确立明确视觉方向、定义 CSS 变量、拒绝紫底白字的默认审美（"No purple bias or dark mode bias"）；
• Motion：少量有意义的动画（页面加载、错峰揭示），拒绝无差别微动效；
• Background：不要平铺单色背景，用渐变、形状或细纹理营造氛围；
• Overall：拒绝模板化布局与可互换的 UI 套路，跨输出变化主题、字体族与视觉语言，并确保桌面与移动端均可正常加载。

例外条款同样明确：若工作在既有网站或设计系统内，必须保留既有模式、结构与视觉语言。这一节是系统提示词中少见的“审美治理”内容，目的不是提高正确率，而是消除生成界面的同质化。

七、Presenting your work：面向 CLI 渲染的纯文本回复契约

该节的前提假设非常关键：模型产出的纯文本会被 CLI 二次排版（"You are producing plain text that will later be styled by the CLI"），因此格式规范服务于可扫描性而非 Markdown 渲染。要点：

• 默认极度简洁，语气是“友好的编码队友”；只在必要时提问，镜像用户风格；
• 简单确认不要重格式；不倾倒已写好的大文件，只引用路径；
• 不说 "save/copy this file"——用户就在同一台机器上；
• 简要给出合乎逻辑的下一步（测试、提交、构建）；做不到的事要补验证步骤；
• 代码变更说明：先一句话解释变更本身，再给上下文（哪里、为什么），不要用 "summary" 开头；有自然下一步就放在结尾，没有就不硬凑；给多个选项时用数字编号列表，方便用户回一个数字。

Final answer 结构与风格指南

原文在此节给出了一份完整的“排版宪法”，逐条继承如下：

• 纯文本，CLI 负责样式；结构仅在提升可扫描性时使用；
• Headers：可选；短 Title Case（1–3 词）包裹在 **…**；首个 bullet 前不留空行；仅在真正有帮助时添加；
• Bullets：用 -；合并相关点；尽量单行；每组 4–6 条并按重要性排序；措辞保持一致；
• Monospace：反引号包裹命令/路径/环境变量/代码 id 与行内示例；字面量关键词 bullet 同样适用；禁止与 ** 混用；
• 代码块用围栏包裹，尽量带 info string；
• Structure：相关 bullet 归组；章节顺序 general → specific → supporting；子节先以粗体关键词 bullet 引入；复杂度与任务匹配；
• Tone：协作、简洁、事实性；现在时、主动语态；自包含，禁止 "above/below"；句式平行；
• Don'ts：禁止嵌套 bullet/层级；禁止 ANSI 转义码；不要把无关关键词塞进同一条 bullet；关键词列表过长时换行重排；不要在回复里命名格式样式本身。

文件引用规范

- File References:
  * Use inline code to make file paths clickable.
  * Each reference should have a stand alone path. Even if it's the same file.
  * Accepted: absolute, workspace-relative, a/ or b/ diff prefixes, or bare filename/suffix.
  * Optionally include line/column (1-based): :line[:column] or #Lline[Ccolumn] (column defaults to 1).
  * Do not use URIs like file://, vscode://, or https://.
  * Do not provide range of lines
  * Examples: src/app.ts, src/app.ts:42, b/server/index.js#L10, C:\repo\project\main.rs:12:5

这一条为 TUI 的文件点击跳转能力服务：每条引用必须独立成路径、行号从 1 开始、禁止行区间，TUI 端才能解析为可点击目标（相关渲染与点击逻辑位于 codex-rs/tui/src）。

八、源码追踪：提示词如何进入对话历史

理解了文件的静态内容，再看它在运行时链路中的位置（以下均为仓库内可直接验证的实现事实）：

1. 模型目录承载模板：ModelInfo 的 model_messages.instructions_template 字段存放按模型划分的系统提示词模板，models-manager/models.json 即为捆绑目录；其中 GPT-5.2 条目的模板首句正是 "You are GPT-5.2 running in the Codex CLI, a terminal-based coding assistant"，与 gpt-5.2-codex_prompt.md 的开头同源。
2. 配置覆盖与变量渲染：model_info.rs 的 with_config_overrides 负责三件事——若用户配置了 base_instructions 则整体替换 instructions_template；若人格（personality）功能关闭且模型属于 "gpt-5.2-codex" | "exp-codex-personality" 的回退元数据，则改用以 prompt.md 为源的 BASE_INSTRUCTIONS（见 第 78–98 行）；否则把 {{ personality }} 占位符替换为默认人格消息（第 22 行 定义占位符常量）。
3. 会话装配 base_instructions：session/mod.rs 第 635–693 行 按优先级取指令：先 config.base_instructions 覆盖，其次从会话历史恢复，最后回落到模型指令；get_base_instructions（第 1259 行）返回的 BaseInstructions 会参与 token 估算（estimate_token_count_with_base_instructions），直接影响自动压缩的触发阈值。
4. 模型切换追加 developer 消息：运行中切换模型时，新模型的指令以 developer 消息追加进历史，由测试 model_change_appends_model_instructions_developer_message 与 model_and_personality_change_only_appends_model_instructions 锁定该行为。
5. 注入方式被测试逐字断言：session/tests.rs 的 get_base_instructions_no_user_content 对 gpt-5.2 等 slug 逐一验证 session.get_base_instructions().await 的文本与模型目录指令完全一致，说明“目录 → 会话 → 历史”链路上没有隐式改写。

用户侧覆盖：model_instructions_file

你不需要修改仓库即可替换整套系统提示词。配置项 model_instructions_file 指定一个本地 Markdown 文件，其内容将作为 base_instructions 覆盖模型自带模板：

# config.toml
model_instructions_file = "/path/to/my_prompt.md"

该链路有三层测试保护：exec_cli_applies_model_instructions_file 验证 -c model_instructions_file=... 命令行覆盖真正作用于外发请求；config_loader_tests 第 2955 行起 验证加载器将其写入 base_instructions，且第 3287 行注明该键允许从项目级配置提供（即团队可随仓库分发统一提示词）。config/mod.rs 第 3912 行附近 是路径解析的实现位置。

九、工程借鉴：把这份提示词当作 Agent 行为规范的参照系

读完全文，gpt-5.2-codex_prompt.md 的写法本身有复用价值，可以归纳出五条可迁移到自研编码智能体的设计模式：

1. 角色 + 环境双声明：一句话同时锚定“你是谁”与“你在哪运行”（CLI、用户电脑），后续所有规则都以此为语境。
2. 条件式能力假设："If the rg command is not found, then use alternatives"——对工具可用性写 if 分支而不是硬依赖。
3. 破坏性操作分级：可回滚操作自由、需审批操作列举（amend、reset --hard）、未知变更先停后问（STOP IMMEDIATELY），把安全边界写成可执行决策而非口号。
4. 输出契约与渲染器解耦：模型只产出纯文本 + 受限标记（**…** 标题、反引号、围栏代码块），样式由 CLI 负责，避免模型输出 ANSI/Markdown 重样式带来的渲染冲突。
5. 反同质化条款：前端设计一节显式命名要消灭的坏模式（"AI slop"、紫色偏置、模板布局），说明审美约束同样可以用提示词工程治理。

十、小结

codex-rs/core/gpt-5.2-codex_prompt.md 是本项目为 gpt-5.2-codex 模型定稿的系统提示词：它规定了搜索工具偏好、脏工作区下的编辑纪律、计划工具的使用时机、Review 请求的输出契约、反同质化的前端设计守则，以及一套完整服务于 CLI 渲染的最终回复排版规范。从源码看，这类提示词经 models-manager 的模板渲染与 session 的指令装配进入每轮请求，并可通过 model_instructions_file 配置在不改代码的前提下整体替换——这为基于该仓库定制自有模型行为（例如替换人格、追加团队规范）提供了现成的工程入口。