Codex 101：它不是代码生成器，而是工程 Agent

这是 Codex 系列的第 1 篇。

这篇不讲复杂命令，也不急着比较 App、CLI、IDE、Web / Cloud。那些会放到后面慢慢展开。第一篇只解决一个更底层的问题：

我到底应该把 Codex 当成什么？

如果这个问题没想清楚，后面的技巧会很容易跑偏。你可能会把 Codex 当成一个更强的代码补全工具，只让它补函数；也可能把它当成聊天顾问，反复复制粘贴报错；还可能把它当成外包，把模糊需求丢过去，然后期待它自己负责产品判断、工程取舍和最后验收。

我现在更愿意把 Codex 当成工程 Agent。

它可以进入项目现场，读文件、改文件、运行命令、检查 diff、总结风险。但越是这样，它越需要清楚的上下文、权限边界和完成标准。换句话说，Codex 不是一个“更会写代码的聊天框”，而是一个需要被正确带进项目里的工程伙伴。

整理日期：2026-06-28。Codex 的入口、命令、权限和产品形态可能继续变化；涉及当前功能的细节，以 OpenAI 官方文档和你账号实际可用能力为准。

这篇在系列里的位置

我会把这个系列写成五段：

入门与安全 -> 项目交付 -> 从 Prompt 到系统 -> 外部连接 -> 团队和边界

这篇属于第一段：入门与安全。

读完这一篇，你应该能带走三样东西：

我不希望第一篇写成“Codex 很强”的宣传文。真正有用的是：你知道什么时候该用它，什么时候该慢一点，什么时候只让它分析而不是直接改。

1. 先把三个角色分开

我会先把常见 AI 编程体验分成三类。这个分类不严谨，但对新手非常实用。

Codex 更接近第三类。

官方文档里对 Codex 的定位也很直接：它是面向软件开发的 coding agent，可以帮助写代码、理解陌生代码库、review、debug，以及自动化开发任务。这个定位和传统“生成一段代码”的工具不太一样。

所以使用 Codex 的关键，不是写一句神奇 Prompt，而是把它放进正确的项目现场。

这里的项目现场包括：

• 当前目录和文件结构。

• Git 状态。

• 依赖、脚本、构建和测试命令。

• 现有代码风格和命名习惯。

• AGENTS.md 里的项目规则。

• 这次任务的目标、约束和完成标准。

• 你愿意给它的权限范围。

你给它的不是一句愿望，而是一项工程任务。

2. 用三个问题理解 Codex

我建议先用三个问题理解 Codex：

这三个问题会贯穿整个系列。

如果你只问“怎么让 Codex 写代码”，很快会卡在 Prompt 技巧里。更好的问题是：

我怎样给 Codex 一个可理解、可执行、可回滚、可复用的工程任务？

这句话比任何万能 Prompt 都重要。

3. 任务适配速查表

先给结论。新手不要从“让 Codex 重构整个项目”开始，先从可验证、可回滚的小任务开始。

我自己的判断标准很简单：

范围是否清楚？
结果是否可验证？
失败是否可回滚？
我是否知道哪些地方不能让它碰？

四个问题里只要有两个答不上来，就先不要让 Codex 直接改。可以让它先读项目、提问题、列方案，但不要急着进入执行。

4. 第一条 Prompt：先给边界，再让它计划

OpenAI 的 Codex 最佳实践里，一个好的任务描述通常包含四件事：Goal、Context、Constraints、Done when。

翻成我日常会用的中文，就是：

目标：
【这次要解决什么问题，或要产出什么】

背景：
【项目是什么，现在发生了什么，为什么要做】

上下文：
【相关文件、页面、报错、截图、命令输出、参考链接】

约束：
1. 【不要改哪些文件】
2. 【不要改变哪些行为】
3. 【不要新增哪些依赖】
4. 【权限、安全、风格或兼容性要求】

完成标准：
1. 【用户能看到什么变化】
2. 【哪些命令需要通过】
3. 【哪些页面或流程需要手动检查】
4. 【完成后需要总结什么】

请先阅读项目并输出计划，不要直接修改。

这个模板不是仪式感。它的作用是让你先把边界说清楚。

比如“帮我优化博客”太大了。更好的写法是：

请先不要修改代码。

目标：
找出当前博客分类页为什么会显示很多 0 篇旧分类，并给出修改方案。

上下文：
这是一个个人博客项目，分类应该收敛到 AI 与智能体、工程实践、金融投资、阅读笔记、个人随笔、工具与效率、项目记录。

约束：
1. 不要修改文章正文。
2. 不要改路由结构。
3. 不要新增依赖。

完成标准：
1. 列出相关文件和数据来源。
2. 说明为什么会显示旧分类。
3. 给出 2 个以内修改方案。
4. 说明每个方案的风险和验证方式。

请先只输出分析和计划。

这就从“模糊愿望”变成了“工程任务”。

5. 30 分钟练习：从空白目录开始

第一次练习不要用重要项目。不要打开公司仓库，不要打开桌面、下载目录或系统盘。

先建一个低风险目录：

New-Item -ItemType Directory -Path D:\AI-Codex-Projects\codex-101-lab
Set-Location D:\AI-Codex-Projects\codex-101-lab
git init

这个目录里不要放真实数据、密钥、公司代码和不可恢复的文件。

然后写一个极简 AGENTS.md：

# AGENTS.md

## Project

This is a tiny Codex practice project.

## Rules

- Use plain HTML, CSS, and JavaScript.
- Do not add external dependencies.
- Before editing, explain the file plan first.
- After editing, summarize changed files and manual verification steps.

这个文件不需要完美。它只需要告诉 Codex：这是一个练习项目，先计划，不要加依赖，完成后说明怎么验收。

接着给 Codex 这个任务：

请创建一个极简的个人书单页面。

要求：
1. 只使用 HTML、CSS、少量 JavaScript。
2. 不使用外部依赖。
3. 页面包含书名、作者、阅读状态、笔记入口。
4. 支持按阅读状态筛选。
5. 完成后告诉我如何在浏览器中打开。

请先给出文件计划。等我确认后，再开始创建。

Codex 给出计划后，先看三件事：

确认计划后，再让它实现。

实现完成后，不要只看总结，至少跑：

git status
git diff

然后手动打开页面，检查：

• 页面能不能打开。

• 书单是否展示正常。

• 筛选是否生效。

• 文案是否符合要求。

• 有没有多余文件。

• 有没有偷偷引入外部脚本、字体或图片。

这才是一轮完整练习：计划、执行、diff、验收、反馈。

6. 怎样判断这轮做得好不好

新手很容易被“完成了”的总结带过去。更稳的方式，是把结果拆成四层。

如果有问题，不要急着自己手改。把反馈继续交给 Codex：

刚才的实现有两个问题：
1. 你引入了外部字体，但我的约束是不使用外部依赖。
2. 筛选后没有显示空状态。

请只修改必要文件，保留现有视觉风格。
完成后重新总结 diff 和手动验证步骤。

你不是一次性“下单”，而是在建立一套协作循环。

7. 从 Prompt 到 AGENTS.md，再到 Skill

第一天不要急着做 Skill。先把顺序记住：

一次性要求 -> Prompt
项目长期规则 -> AGENTS.md
重复出现的任务流程 -> Skill
需要外部系统或外部数据 -> MCP / connector / browser

举几个例子：

AGENTS.md 适合放项目长期规则。官方文档也建议把仓库结构、运行命令、构建测试、工程约定、不要做什么、怎样算完成这些信息写进去。

比如这个博客的规则就适合长期放在 AGENTS.md：

# AGENTS.md

## Blog writing rules

- Write primarily in Chinese.
- Each post must have exactly one primary category.
- Keep tags specific, usually 3-7 per post.
- For AI product posts, verify current product facts against official docs.
- For finance posts, separate facts, observation date, and personal judgment.
- Do not invent personal experience for the author.

## Delivery rules

- Before editing, inspect existing structure.
- Keep changes small and aligned with existing frontmatter.
- Do not publish drafts unless the user explicitly asks.
- After writing, check title, summary, category, tags, links, and ending.

我的经验是：同一条规则重复解释两次，就考虑写进 AGENTS.md。同一套任务流程反复跑顺了，再考虑做成 Skill。

8. 常见失败模式

多数问题不是 Codex 不够聪明，而是任务边界太差。

收藏清单

如果只收藏这一篇，我建议记住这张表。

下一步练习：

1. 建一个空白练习目录。

2. 初始化 Git。

3. 写一个极简 AGENTS.md。

4. 让 Codex 先计划一个小页面，不直接创建。

5. 确认计划后让它实现。

6. 看 git diff，手动验收结果。

7. 记录哪条规则应该继续留在 AGENTS.md，哪条只是本次任务临时需要。

这一步跑完，你会明显感觉到：Codex 不是一个“更会写代码的聊天框”，而是一个需要上下文、边界和验收的工程 Agent。

下一篇会进入入口选择：Codex App、CLI、IDE、Web / Cloud 分别适合什么场景，什么时候该用哪个入口。

参考资料

• OpenAI Codex docs

• OpenAI Codex manual

• OpenAI Codex best practices

• OpenAI Agent approvals & security

• OpenAI Custom instructions with AGENTS.md

• OpenAI Codex Skills

• CodexGuide 学习路线

• bozhouDev/codex-orange-book

• servasyy_ai 的 Codex X 教程

• SOTA Sync 转写：30 分钟搭出完整 Codex 工作流

• openai/codex