王小兵 2026-03-14T23:53:19+08:00 spencer.wong@hotmail.com Codex 使用最佳实践 2026-03-14T00:00:00+08:00 王小兵 https://peakcoder.com/codex/ai/2026/03/14/codex 英文原文链接 OpenAI Codex Best practices

最佳实践

开始使用 Codex,以及获得更好结果的已验证实践。

如果你刚开始接触 Codex,或者刚开始接触编码代理(coding agents),这份指南能帮助你更快获得更好的结果。它涵盖了让 Codex 在 CLI、IDE 扩展和 Codex App 中更有效的一些核心习惯,包括提示、规划、验证、MCP、技能和自动化。

Codex 在你把它视为一个可以持续配置和改进的“队友”时,效果最好,而不是把它当成一次性助手。一个很有用的思路是:先提供正确的任务上下文,用 AGENTS.md 存放长期有效的指导,让 Codex 配合你的工作流进行配置,通过 MCP 连接外部系统,把重复工作封装成 skills,并把稳定的流程自动化。

强有力的起步:上下文与提示词

即使你的提示词并不完美,Codex 也已经足够强大,能够真正帮上忙。很多时候,你几乎不做准备,直接把一个难题交给它,它也能给出很不错的结果。清晰的提示并不是获得价值的前提,但它确实会让结果更可靠,尤其是在大型代码库或高风险任务中。

如果你在一个大型或复杂的仓库中工作,最关键的提升点是:给 Codex 正确的任务上下文,并清楚地组织你希望它完成什么。一个很好的默认做法,是在提示词中包含四项内容:

  • 目标(Goal):你想修改什么,或者构建什么?
  • 上下文(Context):这个任务涉及哪些文件、文件夹、文档、示例或报错?你也可以用 @ 提及特定文件作为上下文。
  • 约束(Constraints):Codex 需要遵守哪些标准、架构、安全要求或约定?
  • 完成标准(Done when):任务完成前应该满足什么条件?比如测试通过、行为发生变化、某个 bug 不再复现等。

这样可以帮助 Codex 保持聚焦、减少臆测,并产出更容易评审的结果。

你还应该根据任务难度选择合适的推理等级,并测试哪种设置最适合你的工作流。不同用户和不同任务,最合适的设置都可能不同:

  • Low:适合更快、范围明确的任务
  • Medium / High:适合更复杂的修改或调试
  • Extra High:适合长流程、代理式、重推理任务

为了更快提供上下文,你也可以在 Codex App 里使用语音输入,直接口述你希望 Codex 做什么,而不是逐字打字。

对困难任务,先做计划

如果任务很复杂、含糊,或者你很难准确描述它,那么在开始写代码前,先让 Codex 做计划。

以下几种方式都很有效:

  • 使用 Plan 模式:对大多数用户来说,这是最简单也最有效的方式。Plan 模式可以让 Codex 先收集上下文、提出澄清问题、形成更扎实的方案,再开始实现。可通过 /planShift + Tab 切换。
  • 让 Codex 先“采访”你:如果你只有一个模糊想法,不知道该怎么准确描述,可以让它先向你提问。告诉它要质疑你的假设,在写代码之前先把模糊想法变得具体。
  • 使用 PLANS.md 模板:对于更高级的工作流,你可以配置 Codex 在长时任务或多步骤任务中遵循 PLANS.md 或执行计划模板。

AGENTS.md 让指导可复用

当某种提示方式已经有效,下一步就不该再靠手动重复输入。这正是 AGENTS.md 发挥作用的地方。

你可以把 AGENTS.md 理解为一个面向 agent 的开放格式 README。它会自动载入上下文,是在仓库中编码“你和你的团队希望 Codex 如何工作”的最佳位置。

一个好的 AGENTS.md 通常会包含:

  • 仓库结构和重要目录
  • 如何运行项目
  • build、test、lint 命令
  • 工程约定和 PR 期望
  • 限制条件和禁止事项
  • “完成”意味着什么,以及如何验证工作结果

CLI 中的 /init 斜杠命令可以快速在当前目录生成一个初始版 AGENTS.md。这是个很好的起点,但你应该根据团队真实的构建、测试、评审和发布方式去修改它。

你可以在不同层级创建 AGENTS.md 文件:比如放在 ~/.codex 中的全局 AGENTS.md 用于个人默认规则,仓库级文件用于团队共享标准,子目录中的更细粒度文件用于局部规则。如果当前目录附近存在更具体的文件,那么更具体的指导会优先生效。

保持务实。一个简短但准确的 AGENTS.md,往往比一份充满模糊规则的长文件更有价值。先写最基本的内容,只有在你发现重复错误后,再逐步增加新规则。

如果 AGENTS.md 变得太大,可以让主文件保持精简,再引用针对具体任务的 markdown 文件,比如规划、代码评审或架构文档。

当 Codex 连续两次犯同样的错误时,让它做一次复盘,然后更新 AGENTS.md。这样,指导内容会始终保持实用,并基于真实摩擦点。

配置 Codex,以保持一致性

配置是让 Codex 在不同会话和不同界面中表现更一致的主要方式之一。比如你可以设置默认模型、推理强度、沙箱模式、审批策略、profiles,以及 MCP 配置。

一个不错的起步方式是:

  • 个人默认配置放在 ~/.codex/config.toml
  • 仓库专属行为放在 .codex/config.toml
  • 命令行覆盖只用于一次性的特殊情况

config.toml 是你定义长期偏好的地方,例如 MCP servers、profiles、多 agent 配置和实验功能。你既可以直接编辑它,也可以让 Codex 帮你修改。

Codex 自带操作系统级别的沙箱能力,并且有两个关键可控项:approval mode 决定 Codex 在运行命令前何时需要你的许可;sandbox mode 决定 Codex 是否能读写目录,以及 agent 可以访问哪些文件。

如果你刚开始使用编码代理,先使用默认权限。默认情况下,把审批和沙箱权限收紧;只有当你在可信仓库或明确工作流中确实需要时,再逐步放宽。

另外,CLI、IDE 和 Codex App 共用同一套配置层。很多所谓“质量问题”,其实是配置问题,比如工作目录错了、没有写权限、默认模型不对、缺少工具或连接器等。因此,尽早按照真实环境配置 Codex 很重要。

通过测试和评审提升可靠性

不要停留在“让 Codex 做一次修改”这一步。你应该让它在需要时创建测试、运行相关检查、确认结果,并在你接受之前先做一轮自我评审。

Codex 可以帮你完成这个闭环,但前提是它知道“什么才算做好”。这些指导既可以来自提示词,也可以来自 AGENTS.md

这通常包括:

  • 为改动编写或更新测试
  • 运行正确的测试套件
  • 检查 lint、格式化或类型检查
  • 确认最终行为符合需求
  • 检查 diff 中是否存在 bug、回归或高风险模式

在 Codex App 中,你可以打开 diff 面板,直接在本地评审改动。点击具体某一行后给出的反馈,会作为上下文传给下一轮 Codex。

这里一个很有用的命令是 /review,它支持多种评审方式:

  • 以某个基线分支为参照进行 PR 风格评审
  • 评审未提交改动
  • 评审某个 commit
  • 使用自定义评审指令

如果你和团队维护了一个 code_review.md 文件,并且在 AGENTS.md 中引用它,Codex 也可以在评审时遵循这份指导。这对于想在多个仓库和贡献者之间保持一致评审行为的团队来说,是一个很强的模式。

Codex 不应该只会生成代码。在合适的指导下,它同样可以帮助测试、检查和评审代码。若你使用 GitHub Cloud,还可以设置 Codex 为你的 PR 执行代码评审。OpenAI 内部会让 Codex 评审 100% 的 PR。你可以启用自动评审,也可以在 @Codex 时触发它进行响应式评审。

用 MCP 获取外部上下文

当 Codex 需要的上下文不在仓库内部时,就该使用 MCP。它能让 Codex 连接到你已经在使用的工具和系统中,这样你就不必不断把实时信息复制粘贴进提示词里。

MCP,也就是 Model Context Protocol,是一种将 Codex 连接到外部工具和系统的开放标准。

以下情况适合使用 MCP:

  • 所需上下文位于仓库外部
  • 数据变化频繁
  • 你希望 Codex 直接使用工具,而不是依赖粘贴进来的说明
  • 你需要一个能在多个用户或多个项目之间重复使用的集成方式

Codex 同时支持 STDIO 和带 OAuth 的 Streamable HTTP 服务器。

在 Codex App 中,可以进入 Settings → MCP servers 查看自定义和推荐的服务器。很多时候,Codex 本身就能帮你安装所需服务器,你只需要开口让它做。CLI 中则可以使用 codex mcp add 命令,通过名称、URL 等信息来添加自定义服务器。

只在工具真正能打通某个工作流时再接入它。不要一开始就把你所有工具都接上。先从 1 到 2 个能够明确减少手动重复步骤的工具开始,之后再逐步扩展。

把可重复工作封装成 skills

当一个工作流开始变得可重复时,就别再依赖长提示词或反复来回沟通了。应该使用 Skill,把指令、SKILL.md 文件中的上下文,以及 Codex 需要稳定应用的支持逻辑打包起来。Skills 可以同时用于 CLI、IDE 扩展和 Codex App。

每个 skill 都应该只专注于一个工作。可以先从 2 到 3 个具体用例起步,定义清楚输入和输出,并在描述中明确说明:这个 skill 是做什么的,以及在什么情况下应该使用它。还应包含用户实际可能会说出的触发短语。

不要一开始就试图覆盖所有边界情况。先挑一个有代表性的任务,把它做好;然后再把这个工作流变成 skill,并持续改进。只有在脚本或附加资源确实能提高可靠性时,再把它们加进去。

一个经验法则是:如果你总在重复使用同一个提示词,或者总在纠正同一类工作流,那它大概率就应该被做成一个 skill。

Skills 尤其适合这些重复性任务:

  • 日志分诊
  • 发布说明草稿
  • 按清单执行 PR 评审
  • 迁移规划
  • 遥测或事故总结
  • 标准化调试流程

$skill-creator skill 是创建第一个 skill 的最佳起点;随后可以用 $skill-installer 将它安装到本地。Skill 最重要的部分之一就是描述:它必须说明这个 skill 做什么,以及什么时候用。

个人 skills 存放在 $HOME/.agents/skills 中;团队共享的 skills 可以放进仓库内的 .agents/skills。这对新成员 onboarding 特别有帮助。

对重复工作使用自动化

当一个工作流已经稳定后,你就可以安排 Codex 在后台定期替你运行它。在 Codex App 中,automations 允许你为周期性任务选择项目、提示词、执行频率和执行环境。

一旦某项任务对你来说开始变得重复,你就可以在 Codex App 的 Automations 标签页中创建自动化。你可以选择它在哪个项目中运行、运行什么 prompt(也可以调用 skills),以及按什么频率运行。你还可以选择让自动化在专用的 git worktree 中运行,还是在本地环境中运行。

适合自动化的任务包括:

  • 汇总最近的 commits
  • 扫描潜在 bug
  • 起草发布说明
  • 检查 CI 失败
  • 生成 standup 总结
  • 按计划运行可重复分析流程

一个很有用的原则是:skills 定义方法,automations 定义时间表。 如果一个工作流仍然需要很多人为引导,先把它做成 skill;一旦它变得可预测,自动化就会成为真正的效率放大器。

自动化不只适合执行任务,也适合用于反思和维护。你可以回顾最近的会话,总结反复出现的摩擦点,并随着时间推移不断改进提示词、说明或工作流配置。

用会话控制来组织长期工作

Codex 的 session 不只是聊天记录。它们更像是会逐步积累上下文、决策和行动的工作线程,因此管理方式会显著影响结果质量。

Codex App 的 UI 最方便做线程管理,因为你可以 pin 线程,也可以创建 worktrees。如果你使用 CLI,以下 slash commands 特别有用:

  • /experimental:切换实验功能,并加入 config.toml
  • /resume:恢复已保存的会话
  • /fork:保留原始对话记录的同时创建一个新线程
  • /compact:当线程过长时,对早期上下文做总结压缩(Codex 也会自动压缩会话)
  • /agent:在并行 agent 之间切换当前活跃线程
  • /theme:选择语法高亮主题
  • /apps:在 Codex 中直接使用 ChatGPT apps
  • /status:查看当前 session 状态

一个连贯的工作单元最好只用一个线程。如果工作仍属于同一个问题,继续留在同一线程通常更好,因为这样能保留推理轨迹。只有当工作真的分叉时,再去 fork。

你还可以使用 Codex 的 multi-agent 工作流,把边界清晰的工作从主线程中分流出去。让主 agent 专注于核心问题,而把探索、测试或分诊之类的任务交给 subagents。

常见错误

以下是刚开始使用 Codex 时常见的一些错误:

  • 把长期有效的规则都塞进 prompt,而不是迁移到 AGENTS.md 或 skill 中
  • 没有告诉 agent 如何运行 build 和 test,导致它无法“看到”自己的工作结果
  • 在多步骤或复杂任务中跳过规划
  • 在你还没理解工作流前,就给 Codex 你的电脑完全权限
  • 在没有使用 git worktrees 的情况下,让多个实时线程修改同一批文件
  • 在某个重复任务还没有被手动验证可靠之前,就急着把它自动化
  • 把 Codex 当成必须一步步盯着看的工具,而不是与你并行工作的助手
  • 按“项目”而不是按“任务”开线程,导致上下文越来越臃肿,结果也会逐渐变差

]]>
可视化线索笔记 Cluero 发布 2026-02-11T00:00:00+08:00 王小兵 https://peakcoder.com/indie/note/2026/02/11/cluero

朋友们,我最近又做了一个应用 Cluero: 可视化线索笔记

了解我的朋友都知道我以前很痴迷各类侦探和本格推理小说。一直以来都有开发一个线索墙应用的念头。二五年尾工作不是特别忙,就开发了一个。
在和 Apple Review Team 邮件 N 次斗智斗勇后,昨晚终于上架成功了。







欢迎诸君下载品鉴。

业余开发投入了很多精力和时间,部分功能需要 Pro 浅浅收一波订阅费吧。
如果有朋友还在念书实在是不宽裕,也可以发邮件问我要 Pro 的内购兑换码。

邮箱: zaijing@alu.hit.edu.cn

也欢迎朋友们关注我的小红书账号 peakcoder,我会以 build in public 的方式发布一些开发 feature 以及 bug fix 日志等。 -EOF-

]]>
现已推出:Neural Flow 3D 思维导图 2025-11-06T00:00:00+08:00 王小兵 https://peakcoder.com/indie/ai/2025/11/06/neural-flow

朋友们,我最近又做了一个 AI 应用 Neural Flow 3D 思维导图 ,可以使用 AI 自动提取文本梗要,生成思维导图。

1.AI 自动生成思维导图:通过简单的文字输入,自动生成结构化导图。
2.16 种 3D 样式:从神经流动到黑洞、霓虹灯等 16 款独特风格。
3.自由交互展示:可平移、缩放、旋转 3D 思维导图,调整光照方向。
4.iCloud 同步:在所有 Apple 设备间无缝同步思维导图。








欢迎诸君下载品鉴。

因为 LLM API 的 Token 也是要花钱买的,本应用就浅浅收点订阅费吧。
如果有朋友还在念书实在是不宽裕,也可以发邮件问我要内购兑换码。

邮箱: zaijing@alu.hit.edu.cn

也欢迎朋友们关注我的小红书账号peakcoder,我会以 build in public 的方式发布一些开发 feature 以及 bug fix 日志等。 -EOF-

]]>
CPU Wokers:CPU 核心利用率可视化 2025-06-16T00:00:00+08:00 王小兵 https://peakcoder.com/indie/ai/2025/06/16/cpu-workers 朋友们,我最近换了新电脑,Intel® Core™ Ultra 9 Processor 275HX 24 核的 CPU,为此我写了一个可视化展示 CPU 各核心利用率的工具,现在我空了都会看着这几个小人跳舞发呆。

每个工人小人代表一个 CPU 核心,他们跳舞的速度与对应核心的利用率成正比。利用率越高,跳得越快,能够比较直观地反映了系统当前的运行负载情况。

下载地址,欢迎诸君下载来玩。

-EOF-

]]>
赛博玄学:六爻起卦 2025-05-23T00:00:00+08:00 王小兵 https://peakcoder.com/indie/ai/2025/05/23/liuyao

朋友们,我最近又做了一个很玄学(中二)的独立 App,叫做六爻起卦
顾名思义,就是你可以在手机上模拟我们老祖宗用三枚钱币占卜的一种方式,即「六爻」来起卦,然后让 DeepSeek 来帮你解读卦象里的玄机。

做这个App的动念之一是之前念书的时候在图书馆里读了很多这些形而上的道学的书,比如野鹤老人所著的《增删卜易》啥的,觉得好玩。

作为一个坚定地无神论者,周易和六爻在我看来是一种宏观但又有点粗糙的经验主义,任何人都可以添加自己的解读,但这些神神鬼鬼的高术看起来很好玩,不是吗?

也许后面再不会做这类的 App 了,最近也一直在思考,我能给这个世界提供什么样的价值。

不管了,我先占一卦。



欢迎诸君下载品鉴。

因为 DeepSeek API 的 Token 也是要花钱买的,本应用就浅浅收六元钱吧。
如果有朋友实在是不宽裕,连六块都没有,也可以发邮件问我要内购兑换码。

邮箱: zaijing@alu.hit.edu.cn

也欢迎朋友们关注我的小红书账号peakcoder,我会以 build in public 的方式发布一些开发 feature 以及 bug fix 日志等。

-EOF-

]]>
Shadertoy 中文教程 2025-02-17T00:00:00+08:00 王小兵 https://peakcoder.com/shader/shadertoy/2025/02/17/shadertoy 你好!我的朋友,我最近对着色器以及它们的神奇之处很着迷。今天,我们会将讨论如何使用一个名为 Shadertoy 的出色在线工具创建像素着色器,该工具由两位非常有才华的人 Inigo QuilezPol Jeremias 创建。

我大概花了三周,翻译整理了作者 Nathan Vaughn 在他的博客上的 Shadertoy 英文教程,有兴趣的可以去观摩学习英文原版。

我翻译的中文教程,用 docusaurus 托管在 netlify
地址:shadertoy.peakcoder.com

先贴一个我自己写的 Shadertoy 是我自己头像的 Voxel Art Avatar
Shadertoy 网站至少你应该注册过了吧,Emmm..可以去给我点个赞 :)

Shader Preview

另外,本教程的代码仓库地址:github.com/iMemento/shadertoy-tutorial
如果能给个 star ✨ 我会感激不尽。

希望你看完本教程,能有所收获。

-EOF-

]]>
Unity Sentis:Runtime 使用 AI 模型 2024-05-19T00:00:00+08:00 王小兵 https://peakcoder.com/unity/ai/2024/05/19/sentis SentisUnity 推出的一个用于在 Unity 环境中运行机器学习模型的框架,可以简化将机器学习模型集成到 Unity 项目中的过程。

使用方法

1. 安装 Sentis

打开 Window > Package Manager
点击 + 选择 Add package by name
输入 com.unity.sentis 安装

2. 导入模型

Hugging Face 选择并下载你需要的模型,或者去 ModelZoo 之类下载。
Hugging Face 上,模型通常以 PyTorchTensorFlow 格式提供,需要转换为 ONNX 格式。

假设你使用的是 PyTorch 模型,可以使用 torch.onnx.export 方法来完成转换。

import torch
from transformers import AutoModel

# Load your Hugging Face model
model = AutoModel.from_pretrained("your-model-name")

# Set the model to evaluation mode
model.eval()

# Dummy input for model export
dummy_input = torch.randn(1, 3, 224, 224)  # Adjust dimensions as needed

# Export the model to ONNX format
torch.onnx.export(model, dummy_input, "model.onnx", opset_version=11)

Tips:

如果不使用 Unity 想直接在 iOS 中使用,则需要再讲 ONNX 转化为 Core Ml 格式。

3. 加载和运行模型

using UnityEngine;
using Unity.Sentis;
using System.IO;

public class SentisExample : MonoBehaviour
{
    private Model runtimeModel;
    private IWorker worker;

    void Start()
    {
        // 加载 ONNX 模型文件
        var modelFilePath = Application.dataPath + "/model.onnx";
        var modelData = File.ReadAllBytes(modelFilePath);

        // 加载模型到 Sentis
        runtimeModel = ModelLoader.Load(modelData);
        worker = WorkerFactory.CreateWorker(WorkerFactory.Type.ComputePrecompiled, runtimeModel);

        // 准备输入数据(示例)
        // 根据模型调整维度
        var inputTensor = new Tensor(1, 3, 224, 224); 

        // 执行推理
        worker.Execute(inputTensor);
        var outputTensor = worker.PeekOutput();

        // 处理输出数据
        Debug.Log(outputTensor);

        // 清理资源
        inputTensor.Dispose();
        outputTensor.Dispose();
        worker.Dispose();
    }
}

模型优化技术

为了在移动设备上高效运行,模型通常需要经过优化,包括:

1. 量化(Quantization)

将模型从32位浮点数表示转换为8位整数表示,可以显著减少模型的大小和计算需求。

2. 模型剪枝(Pruning)

移除模型中冗余的权重和节点,减少计算复杂度。

3. 知识蒸馏(Knowledge Distillation)

将复杂模型的知识转移到一个较小的模型中。

最新的iPhone能够运行包含数百万到数千万参数的优化模型。例如,MobileNetTinyBERT 等模型经过量化和其他优化技术处理后,可以在iPhone上高效地运行。

–EOF–

]]>
分花:愿你有无数的鲜花与浪漫 2024-04-22T00:00:00+08:00 王小兵 https://peakcoder.com/indie/2024/04/22/petals

发一个年初做的 APP「分花」 凑一篇 Blog 吧。
大概这辈子再也不会做这种类型的软件了…



有人要内购兑换码吗:)
可以邮件: zaijing@alu.hit.edu.cn
小红书: peakcoder
愿你有无数的鲜花与浪漫

–EOF–

]]>
Git .gitattributes 使用指北 2024-01-05T00:00:00+08:00 王小兵 https://peakcoder.com/git/2024/01/05/gitattributes .gitattributes 文件在 Git 仓库中用于定义各种属性,以指定 Git 如何处理仓库中的文件。
这个文件可以用于多种用途,包括但不限于以下几种:

1. 行尾转换 (End-of-Line Conversion)

指定文件的行尾风格,例如,强制在 Windows 和 UNIX 系统之间一致地使用 LF 或 CRLF。

*.txt text eol=lf
*.bat text eol=crlf

2. 合并策略 (Merge Strategies)

为特定文件或路径指定合并策略,比如使用文本方式合并或使用特定的合并驱动。

*.png merge=theirs

3. 大文件存储 (Large File Storage, LFS)

将大文件如视频、音频或大型二进制文件交给 Git LFS 管理。

*.mp4 filter=lfs diff=lfs merge=lfs -text

4. 导出忽略 (Export Ignore)

指定在使用 git archive 时应该忽略的文件。

*.log export-ignore

5. 语言统计 (Language Statistics)

控制 git 命令如何统计语言使用情况,可以用于排除某些文件。

*.md linguist-documentation

6. 差异展示 (Diff)

指定文件的差异展示方式,如是否应该被 Git 识别为文本,并如何显示差异。

*.jpg binary
*.html diff=html

7. 禁用压缩 (Disable Compression)

禁用对特定文件的 Git 压缩。

*.jpg -filter

8. 自定义过滤器 (Custom Filters)

为文件设置自定义的清理(clean)和还原(smudge)过滤器。

*.json filter=jsonFilter

9. 核对属性 (Check Attributes)

在提交前检查文件是否符合特定的属性要求。

*.py check=python

10. 文本属性 (Text Attributes)

指定文件是否应被视为文本,对行尾进行规范化,或者被视为二进制文件。

*.txt text
*.bin binary

–EOF–

]]>
Open Source a Pixel-Art Game 'PuppyTouch' 2023-03-06T00:00:00+08:00 王小兵 https://peakcoder.com/cocos2d-x/2023/03/06/puppy-touch 开源一个游戏 PuppyTouch 这是我在大学刚毕业时候做的,是一个2d像素风的小游戏,使用cocos2d-x引擎开发的。手写识别使用的是华盛顿大学的 $1 Unistroke Recognizer 算法。

之前在AppStore上架过,长久不更新现已下架。
代码不多,大量的时间都在美术上消耗掉了,年少时的我是真的很爱画像素画 :)

–EOF–

]]>