这是 Codex 系列的第 1 篇。
这篇不讲复杂命令，也不急着比较 App、CLI、IDE、Web / Cloud。那些会放到后面慢慢展开。第一篇只解决一个更底层的问题：
我到底应该把 Codex 当成什么？
如果这个问题没想清楚，后面的技巧会很容易跑偏。你可能会把 Codex 当成一个更强的代码补全工具，只让它补函数；也可能把它当成聊天顾问，反复复制粘贴报错；还可能把它当成外包，把模糊需求丢过去，然后期待它自己负责产品判断、工程取舍和最后验收。
我现在更愿意把 Codex 当成工程 Agent。
它可以进入项目现场，读文件、改文件、运行命令、检查 diff、总结风险。但越是这样，它越需要清楚的上下文、权限边界和完成标准。换句话说，Codex 不是一个“更会写代码的聊天框”，而是一个需要被正确带进项目里的工程伙伴。
整理日期：2026-06-28。Codex 的入口、命令、权限和产品形态可能继续变化；涉及当前功能的细节，以 OpenAI 官方文档和你账号实际可用能力为准。
这篇在系列里的位置
我会把这个系列写成五段：
入门与安全 -> 项目交付 -> 从 Prompt 到系统 -> 外部连接 -> 团队和边界
这篇属于第一段：入门与安全。
读完这一篇，你应该能带走三样东西：
| 产物 | 用来解决什么 |
|---|---|
| 任务适配速查表 | 判断一个任务适不适合交给 Codex |
| 第一条 Prompt 模板 | 让 Codex 先理解目标、上下文、约束和完成标准 |
| 30 分钟练习流程 | 在低风险目录里跑完一次计划、实现、diff、验收 |
Codex 工程 Agent 心智图
我不希望第一篇写成“Codex 很强”的宣传文。真正有用的是：你知道什么时候该用它，什么时候该慢一点，什么时候只让它分析而不是直接改。
1. 先把三个角色分开
我会先把常见 AI 编程体验分成三类。这个分类不严谨，但对新手非常实用。
| 角色 | 典型体验 | 适合什么 | 主要风险 |
|---|---|---|---|
| 补全工具 | 你写一半，它补后面 | 函数、样板代码、小片段 | 容易只看局部 |
| 聊天顾问 | 你贴代码和报错，它给建议 | 解释概念、分析错误、讨论方案 | 答案还要你搬回项目 |
| 工程 Agent | 它进入项目，读文件、改代码、跑命令、总结结果 | 修 bug、补测试、改页面、整理文档、做 review | 如果边界不清，会真的改坏东西 |
Codex 更接近第三类。
官方文档里对 Codex 的定位也很直接：它是面向软件开发的 coding agent，可以帮助写代码、理解陌生代码库、review、debug，以及自动化开发任务。这个定位和传统“生成一段代码”的工具不太一样。
所以使用 Codex 的关键，不是写一句神奇 Prompt，而是把它放进正确的项目现场。
这里的项目现场包括：
- 当前目录和文件结构。
- Git 状态。
- 依赖、脚本、构建和测试命令。
- 现有代码风格和命名习惯。
AGENTS.md里的项目规则。- 这次任务的目标、约束和完成标准。
- 你愿意给它的权限范围。
你给它的不是一句愿望，而是一项工程任务。
2. 用三个问题理解 Codex
我建议先用三个问题理解 Codex：
| 问题 | 新手常见误区 | 更稳的做法 |
|---|---|---|
| 怎么开始 | 打开最重要的项目，给最大权限，直接让它改 | 从低风险目录、Git 基线、小任务开始 |
| 怎么交付 | 只看 Codex 的“已完成”总结 | 写清完成标准，看 diff，跑检查，手动验收 |
| 怎么沉淀 | 每次重复写同一堆要求 | 稳定规则进 AGENTS.md，重复流程再做成 Skill |
这三个问题会贯穿整个系列。
如果你只问“怎么让 Codex 写代码”，很快会卡在 Prompt 技巧里。更好的问题是：
我怎样给 Codex 一个可理解、可执行、可回滚、可复用的工程任务？
这句话比任何万能 Prompt 都重要。
3. 任务适配速查表
先给结论。新手不要从“让 Codex 重构整个项目”开始，先从可验证、可回滚的小任务开始。
| 任务 | 是否适合新手直接交给 Codex | 原因 | 更好的第一步 |
|---|---|---|---|
| 读项目并输出结构说明 | 适合 | 主要是阅读和总结，风险低 | 要求只输出相关文件、模块关系和疑问 |
| 修一个可复现 bug | 适合 | 有现象、日志、复现步骤和验证方式 | 先让它定位原因和修改计划 |
| 补测试 | 适合 | 目标明确，结果可以通过测试验证 | 先列需要覆盖的边界条件 |
| 改一个小页面或组件 | 适合 | 范围有限，可以浏览器验收 | 明确不要改路由、数据结构或依赖 |
| 整理 README / AGENTS.md | 适合 | 需要读项目和总结规则 | 先让它读取现有结构再写草案 |
| Review 当前 diff | 适合 | 不必直接改代码，能发现风险 | 要求按 bug、回归、测试缺口排序 |
| 批量重构核心模块 | 谨慎 | 文件多，行为变化难判断 | 先让它做影响面分析和分步计划 |
| 修改生产数据库 | 不适合直接执行 | 不可逆风险高 | 只让它写方案、风险和回滚脚本草案 |
| 支付、鉴权、权限核心逻辑 | 不适合直接放手 | 安全风险高，需要人工设计和审查 | 让它做威胁建模、测试清单和 review |
| 个人经历、投资结论 | 不适合代写判断 | 它不能替你拥有经历和责任 | 让它整理资料、提出问题、做结构化草稿 |
我自己的判断标准很简单：
范围是否清楚？
结果是否可验证？
失败是否可回滚？
我是否知道哪些地方不能让它碰？
四个问题里只要有两个答不上来，就先不要让 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 给出计划后，先看三件事：
| 检查项 | 你要看什么 |
|---|---|
| 文件数量 | 是否只有必要文件，比如 index.html、styles.css、script.js |
| 依赖 | 是否遵守“不使用外部依赖” |
| 验收方式 | 是否说明如何打开页面、如何测试筛选 |
确认计划后，再让它实现。
实现完成后，不要只看总结，至少跑：
git status
git diff
然后手动打开页面，检查：
- 页面能不能打开。
- 书单是否展示正常。
- 筛选是否生效。
- 文案是否符合要求。
- 有没有多余文件。
- 有没有偷偷引入外部脚本、字体或图片。
这才是一轮完整练习：计划、执行、diff、验收、反馈。
Codex 第一次安全练习流程
6. 怎样判断这轮做得好不好
新手很容易被“完成了”的总结带过去。更稳的方式，是把结果拆成四层。
| 层级 | 你要检查什么 | 例子 |
|---|---|---|
| 文件层 | 是否只改了该改的文件 | 没有动无关配置，没有生成多余目录 |
| 行为层 | 功能是否真的符合要求 | 筛选按钮能切换阅读状态 |
| 约束层 | 是否遵守你的限制 | 没有外部依赖，没有 CDN |
| 交付层 | 是否说清怎么验证和后续风险 | 给出打开方式、检查点、未处理问题 |
如果有问题，不要急着自己手改。把反馈继续交给 Codex：
刚才的实现有两个问题：
1. 你引入了外部字体，但我的约束是不使用外部依赖。
2. 筛选后没有显示空状态。
请只修改必要文件，保留现有视觉风格。
完成后重新总结 diff 和手动验证步骤。
你不是一次性“下单”，而是在建立一套协作循环。
7. 从 Prompt 到 AGENTS.md，再到 Skill
第一天不要急着做 Skill。先把顺序记住：
一次性要求 -> Prompt
项目长期规则 -> AGENTS.md
重复出现的任务流程 -> Skill
需要外部系统或外部数据 -> MCP / connector / browser
举几个例子：
| 需求 | 更适合放在哪里 |
|---|---|
| “这次不要改路由” | Prompt |
| “这个博客每篇文章只能有一个主分类” | AGENTS.md |
| “每次写完技术文章都按读者价值、事实来源、可操作性 review” | Skill |
| “需要读取 GitHub issue、Notion 文档、浏览器页面、飞书表格” | MCP、connector 或 browser |
从 Prompt 到系统的沉淀关系
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 优化整个项目 | 拆成小任务，先让它输出计划 |
| 没有上下文 | Codex 猜文件、猜框架、猜命令 | 先让它读项目并列相关文件 |
| 没有约束 | 顺手改了无关文件或引入依赖 | 写清不要动什么、不要新增什么 |
| 没有 Git 基线 | 改坏后不知道怎么恢复 | 开始前初始化或提交当前状态 |
| 不看 diff | 只相信“已完成” | 每轮都看 git diff |
| 不跑验证 | 页面或测试实际坏了 | 把测试、构建、手动检查写进完成标准 |
| 权限太大 | 新手直接全权限跑 | 从默认权限、只读计划或练习目录开始 |
| 把 Codex 当作者 | 让它编造个人经历和判断 | 让它整理材料，不让它替你拥有经历 |
多数问题不是 Codex 不够聪明，而是任务边界太差。
收藏清单
如果只收藏这一篇，我建议记住这张表。
| 问题 | 判断 |
|---|---|
| 这个任务能不能交给 Codex？ | 看范围是否清楚、结果是否可验证、失败是否可回滚 |
| 第一条 Prompt 写什么？ | 目标、上下文、约束、完成标准 |
| 什么时候先计划？ | 复杂、模糊、高风险、多文件任务 |
| 什么时候写 AGENTS.md？ | 同一条规则重复解释两次以上 |
| 什么时候做 Skill？ | 一类任务反复出现，并且有稳定步骤 |
| 什么时候接 MCP？ | Codex 缺的是外部系统或外部数据，而不是更详细的指令 |
下一步练习：
- 建一个空白练习目录。
- 初始化 Git。
- 写一个极简
AGENTS.md。 - 让 Codex 先计划一个小页面，不直接创建。
- 确认计划后让它实现。
- 看
git diff，手动验收结果。 - 记录哪条规则应该继续留在
AGENTS.md，哪条只是本次任务临时需要。
这一步跑完，你会明显感觉到：Codex 不是一个“更会写代码的聊天框”，而是一个需要上下文、边界和验收的工程 Agent。
下一篇会进入入口选择：Codex App、CLI、IDE、Web / Cloud 分别适合什么场景，什么时候该用哪个入口。