/zh/posts/codex-notes

Codex 使用心得

EN

当我不再把 Codex 当成一次性的聊天机器人，而是把它当成一个可以配置、可以验证、可以持续改进的开发队友时，它才真正变得有用。

这篇笔记基于 OpenAI 的 Codex best practices，也结合了我搭建这个博客时的实际工作流。最重要的经验是：Codex 在拥有正确任务上下文、清晰完成标准、可复用项目规则，并且被允许验证自己输出时，表现会稳定很多。

1. 从正确的任务形状开始

一个好的 Codex 请求，最好包含四件事：

  • 目标
  • 相关上下文
  • 约束
  • 什么情况算完成

我喜欢使用这样的提示结构：

Goal:
Update the Codex article with a more practical workflow.

Context:
- The post is source/_posts/codex-notes.md.
- The theme supports copyable code blocks.
- Follow .spec/content-editing.md.

Constraints:
- Keep the article in English.
- Do not change unrelated pages.
- Preserve the existing date and tags.

Done when:
- npm run clean && npm run build passes.
- The generated article contains code examples.
- The change is committed.

这个格式的价值不是仪式感，而是减少歧义。Codex 不需要随机搜索，也不需要猜测太多，可以围绕明确的验证步骤完成任务。

2. 模糊任务先规划

当任务复杂、不清晰，或者可能涉及多个文件时，我不会让 Codex 直接开始编辑。我会先让它做计划。

比较好的规划请求是：

Inspect the current implementation first.
Do not edit files yet.
Explain which files are involved and propose a short plan.
Call out risks before implementation.

这在修改布局、导航、部署或任何可能引入回归的问题时很有用。比如这个博客里的音乐播放器：如果页面导航改错了，就可能重新创建 <audio> 节点，导致音乐重置。先规划可以在写代码前发现这类风险。

对于更大的工作，我也会让 Codex 先采访我：

I have a rough idea but not a precise spec.
Ask me the minimum questions needed to turn it into an implementation plan.
Challenge unclear assumptions.

这样可以让人继续负责产品方向，同时让 Codex 帮忙把模糊想法整理成可执行任务。

3. 把长期规则放进 AGENTS.md

重复出现的指令不应该每次都写在 prompt 里，而应该沉淀到项目规则里。

在这个仓库里，AGENTS.md 记录了这些规则：

# Agent Instructions

- After each completed small feature loop, create a Git commit.
- Keep commits scoped to the completed work.
- After development, run relevant tests or checks yourself.
- If testing reveals problems, fix them and repeat verification until the checks pass.
- Before making changes in a fresh context, read `.spec/README.md` first.

这能让 Codex 在不同会话里保持一致。目标不是写一个巨大的说明文件。短而准确的规则，比一份很长但模糊的偏好清单有用得多。

我现在的结构是：

AGENTS.md
  high-level workflow rules

.spec/README.md
  progressive disclosure entry point

.spec/content-editing.md
  how to edit posts, about page, projects, music, favicon, and ICP text

.spec/theme-guidelines.md
  visual and interaction constraints

.spec/deployment.md
  Codeup Flow, Nginx, and deployment checks

这样新的 Codex 会话只需要读取相关 spec，而不需要一次读完整个仓库说明。

4. 按真实环境配置 Codex

很多糟糕结果并不是模型能力问题，而是环境问题：工作目录不对、权限不对、工具缺失、上下文缺失，或者验证命令不清楚。

我希望 Codex 知道这个项目真实使用的命令：

npm run clean
npm run build
node --check themes/kaomoji-pixel/source/js/home.js
git status --short

我也希望它清楚自己有多少自由度。对于可信任的个人项目，我可以给它更大的本地编辑权限。对于陌生代码库，我会更偏向收紧权限和缩小任务范围。

有用的配置层级是：

~/.codex/config.toml
  personal defaults

.codex/config.toml
  repo-specific settings

AGENTS.md
  human-readable project rules

重点是让 Codex 适配我真实会执行的工作流，而不是一套我之后会忘记遵守的理想流程。

5. 把测试和 review 纳入请求

Codex 不应该在编辑文件后就停止。它应该验证改动。

对于这个博客，普通内容修改通常应该以这个命令结束：

npm run clean && npm run build

如果改的是 JavaScript 行为，还应该运行：

node --check themes/kaomoji-pixel/source/js/home.js

如果改的是部署流程，我希望它尽量做本地模拟，或者运行等价的命令级验证。

我也喜欢让 Codex 在提交前 review 自己的 diff：

Before committing, review the diff for:
- unrelated changes
- broken responsive layout
- missing verification
- stale documentation

这不能替代人的 review，但可以抓住很多简单错误。

6. 用 MCP 获取仓库外上下文

有些上下文变化很快，不适合每次复制到 prompt 里，比如文档、看板、工单、部署系统、外部 API 和内部工具。MCP 适合用来让 Codex 可重复地连接这些上下文。

一个简单的 CLI 形式是：

codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp

我不想一开始就连接所有工具。更好的规则是：只有当 MCP 能消除一个真实的手工循环时，才添加它。

适合 MCP 的场景包括：

  • 当前产品文档
  • issue tracker
  • CI 状态
  • 部署元数据
  • 内部搜索
  • 可观测性工具

不适合的场景，是那些只用一次就不会再碰的工具。

7. 把重复工作变成 Skills

如果我一直给 Codex 同一段很长的 prompt，那这个工作流可能应该变成一个 skill。

适合变成 skill 的任务通常范围窄、重复性强：

  • 写 release notes
  • 按 checklist review PR
  • 排查日志
  • 规划迁移
  • 总结最近提交
  • 执行标准调试流程

一个好的 skill 应该有清晰触发方式、较小范围和具体输出。我更愿意维护三个可靠的小 skill，而不是一个试图覆盖所有情况的巨大 skill。

我喜欢的步骤是：

1. Repeat the workflow manually.
2. Notice which instructions keep coming back.
3. Extract those instructions into a skill.
4. Test it on one real task.
5. Improve only after it proves useful.

8. 只自动化稳定流程

自动化只有在手动流程已经可靠时才有价值。如果一个流程仍然需要我大量干预，那它还不适合自动化。

适合自动化的任务包括：

  • 检查 CI 失败
  • 起草 release notes
  • 总结最近提交
  • 扫描常见 bug
  • 生成维护报告

我喜欢这样区分：

skills define the method
automations define the schedule

如果方法本身还不稳定，那么把它定时运行只会制造重复噪音。

9. 有意识地管理会话

长时间的 Codex 会话会积累上下文、决策和错误。这有时有帮助，但也可能变得混乱。

我的实用规则是：一个连贯任务一个 thread。如果任务方向变了，我更倾向于新开会话或者 fork 当前会话。

有用的会话命令包括：

/status
/resume
/compact
/fork
/plan

当上下文变长但任务仍然相同时，我会用 /compact。当工作分叉到另一个方向时，我会用 /fork。

10. 我想避免的常见错误

我需要警惕的问题其实很固定：

  • 给 Codex 一个模糊目标，却期待精确输出
  • 把长期规则留在 prompt 里，而不是写进 AGENTS.md
  • 多文件修改时跳过规划
  • 不告诉 Codex 如何验证工作
  • 在没理解流程前给过大的权限
  • 多个 agent 同时修改同一批文件却没有协调
  • 手动流程还不稳定就开始自动化
  • 一个项目只开一个永不结束的超长会话

这些问题大多和“聪明程度”无关，更多是流程问题。

我当前的 Codex 工作流

对于这个博客，我希望 Codex 遵循的流程是：

1. Read .spec/README.md.
2. Read only the relevant spec files.
3. Inspect the existing code before editing.
4. Make a narrow change.
5. Run the relevant checks.
6. Fix failures.
7. Commit the completed loop.
8. Push when the task should deploy.

这个流程让 Codex 更像一个有纪律的开发循环，而不是单纯的文本生成器。

来源

这篇文章总结并改写自 OpenAI 的 Codex best practices：

https://developers.openai.com/codex/learn/best-practices