把 Codex 用进真实项目：入口、权限、Git、AGENTS.md 与 Prompt 模板

最近重新看了一遍 bozhouDev/codex-orange-book，也顺手对了一遍 OpenAI 的 Codex manual。这篇不是对《橙皮书》的逐章复述，而是我按自己的使用习惯重新整理的一份技术笔记。

《橙皮书》写得很像一份面向新手的操作手册：先解释 Codex 是什么，再讲 App、CLI、IDE Extension、Web / Cloud，接着讲插件、Skill、MCP、Git、AGENTS.md，最后用一个宠物零食网站的案例串起来。它的优点是覆盖面广，缺点也明显：如果只是想快速建立自己的工作流，里面的截图、安装细节、案例步骤会显得有点长。

所以我这篇会换一种组织方式：不追求把所有界面按钮都写全，而是把长期有用的部分提炼出来。

我的目标很简单：

1. 解释 Codex 应该被放在什么位置。
2. 梳理 App、CLI、IDE、Web/Cloud 这些入口怎么选。
3. 把权限、安全、Git、AGENTS.md、Skill/MCP 这些容易被忽略的基础设施讲清楚。
4. 给一套能复制到真实项目里的工作流和 Prompt 模板。

本文最后整理时间是 2026-06-27。Codex 相关功能、套餐、模型、命令参数和界面位置都可能变化；安装入口、价格、额度、可用模型，以官方页面和你账号实际显示为准。

如果你只是想快速收藏，可以先看三块：

• 开头的速查卡：判断入口、权限和任务边界。
• 中间的六步法：把需求拆成能交给 Codex 的任务。
• 后面的 30 分钟实操：照着跑一遍，基本就知道 Codex 应该怎么进入自己的项目。

Codex 实用工作流

0. 先说结论

如果只用一句话概括我对 Codex 的理解：

Codex 不是代码生成按钮，而是可以被放进工程流程里的执行型 Agent。

这句话里有三个关键词。

第一个是“工程”。Codex 的价值不是单独写一个函数，而是在一个真实项目里读文件、理解上下文、改代码、跑命令、看 diff、写总结。它处理的是项目现场，而不是孤立代码片段。

第二个是“流程”。Codex 很容易一口气改很多东西，所以必须用流程框住它：先读项目，再定计划；先小步实现，再测试；先看 diff，再提交。流程不是为了慢，而是为了让快有边界。

第三个是“执行”。ChatGPT 更像顾问，Cursor 更像编辑器里的协作者，Codex 更接近一个能被派活的工程助手。你可以交给它任务，但你仍然要负责判断、验收和风险控制。

我现在会用这套最小工作台：

这套东西看起来朴素，但比“随便让它做个东西”可靠得多。

0.1 收藏速查卡

如果把这篇文章当手册用，我建议先记下面几张表。

入口选择：

任务边界：

每次开工前的最小检查：

我最常用的 Prompt 骨架是这个：

请先不要修改代码。

目标：
【这次要解决什么】

背景：
【项目背景、用户场景、现在的问题】

约束：
1. 【哪些文件/目录不要动】
2. 【不要引入什么依赖】
3. 【不要改变什么行为】

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

请先输出：
1. 你理解的需求
2. 可能相关的文件
3. 修改计划
4. 风险点
5. 需要我确认的问题

等我确认后再开始修改。

这段 Prompt 的重点不是客气，而是把 Codex 从“自动发挥”拉回“先理解、再计划、后执行”的节奏。

1. Codex 到底解决了什么问题

《橙皮书》开头用了一个很清楚的脉络：AI 编程工具过去几年大概经历了从补全、对话、编辑器协作，到工程 Agent 的变化。

我自己的理解是：

这个变化的核心不是“模型更聪明了”这么简单，而是 AI 的工作位置变了。以前 AI 更像一个辅助输入层，现在它开始进入工程执行层。

但这也带来一个副作用：越能执行，越需要边界。

当一个工具只能回答问题时，它最多给你一个错答案。当一个工具能改文件、跑命令、联网、调用外部工具时，它的错误可能变成真实项目里的错误。所以使用 Codex 的第一课不是“怎么让它写得更多”，而是“怎么让它在正确范围里做事”。

适合 Codex 的任务，通常有几个特征：

• 目标明确：修一个可复现 bug、新增一个清楚的页面、补一组测试、整理一份 README。
• 范围可控：知道大概涉及哪些文件，知道哪些东西不能动。
• 结果可验证：有命令可跑，或有手动验收路径。
• 失败可回滚：Git 状态清楚，最好有分支或 worktree。
• 风险可接受：不是生产数据库、支付核心、权限核心这种高风险场景。

不适合直接交给 Codex 独立处理的任务：

• 真实用户数据、生产数据库、支付链路。
• 鉴权、权限、安全策略等核心模块。
• 你自己也无法判断对错的大规模重构。
• 没有备份、没有 Git、没有测试的重要项目。
• 需要组织共识的架构迁移。

Codex 可以让工程执行更快，但不能替你承担工程判断。

2. 四个入口：App、CLI、IDE、Web / Cloud

《橙皮书》把 Codex 的使用入口分成四类：App、CLI、IDE Extension、Web / Cloud。这个分类很有用，因为很多新手的问题不是“Codex 能不能做”，而是不知道应该从哪个入口开始。

我会这样选：

2.1 新手路线

如果完全从零开始，我建议顺序是：

1. 用 Codex App 打开一个练习项目。
2. 学会看它改了哪些文件、跑了哪些命令、需要什么权限。
3. 再用 CLI 进入项目目录，熟悉 codex、codex resume、codex exec。
4. 写一个项目级 AGENTS.md。
5. 熟悉 Git 后，再用 Web / Cloud 处理 GitHub 仓库。

不要一上来就让 Codex 操作你的重要工作目录。先建一个练习目录：

D:\AI-Codex-Projects\hello-codex

然后初始化 Git：

git init
git add .
git commit -m "initial commit"

这一步不是仪式感。Codex 会改文件，Git 是你最基本的检查和回滚工具。

2.2 不要把入口选择复杂化

一个很实用的判断：

• 想看着它做、想图形化 review：用 App。
• 想在终端里和项目贴得更近：用 CLI。
• 正在编辑某段代码：用 IDE Extension。
• 仓库已经在 GitHub、想异步交给云端跑：用 Web / Cloud。

入口不是信仰。真正重要的是：每个入口都要配合上下文、权限、Git 和验证流程。

3. 安装前准备：先搭一个安全的练习场

《橙皮书》在安装前准备里反复强调几件小事：账号、系统、Git、项目目录、权限。这里我不展开每个下载按钮，只保留长期有效的部分。

建议先准备：

目录选择上，我会避开这些位置：

C:\
桌面
下载文件夹
系统目录
重要资料文件夹

更好的结构：

D:\AI-Codex-Projects
├── hello-codex
├── frontend-playground
└── blog-draft-lab

每个项目开始前先做三件事：

git status
git init
git add .
git commit -m "initial commit"

如果已有 Git 仓库，就先看：

git status
git diff

确保你知道当前工作区有没有未提交改动。不要在一堆脏改动上直接开一个大任务，否则后面很难判断哪些是 Codex 改的、哪些是你原来改的。

4. 权限和安全：Sandbox 是安全围栏，不是麻烦按钮

Codex 和普通聊天工具最大的区别之一，是它能在本地运行命令、读文件、改文件。所以权限模型必须理解。

官方文档把这里分成两个概念：

• Sandbox mode：技术上允许 Codex 做什么，比如能不能写文件、能不能访问网络、能不能碰工作区外的路径。
• Approval policy：什么时候必须停下来问你，比如越界写入、联网、高风险命令。

我把它理解成：

Sandbox 决定围栏有多大。
Approval 决定什么时候要敲门问你。

4.1 新手优先用保守模式

CLI 里可以从这种思路开始：

codex --sandbox workspace-write --ask-for-approval on-request

只想读项目、不想改文件：

codex --sandbox read-only

不建议新手直接使用：

codex --sandbox danger-full-access
codex --dangerously-bypass-approvals-and-sandbox
codex --ask-for-approval never

这不是说这些模式永远不能用，而是它们不应该成为默认习惯。权限越大，越要明确任务、明确工作区、明确回滚方案。

4.2 高风险命令清单

看到这些命令或行为时，我会让 Codex 先解释，再决定是否继续：

可以这样问：

请解释这条命令会做什么、影响哪些文件、有什么风险，以及有没有更安全的替代方案。

如果你看不懂解释，就不要批准。

5. App 的任务模型：Project、Thread、Plan、Review

Codex App 的价值不只是“有图形界面”。它更像一个任务管理器：你选择一个项目，然后在项目里开多个 thread，每个 thread 处理一个具体任务。

可以这样理解：

《橙皮书》里有一个对新手很有用的提醒：复杂任务先开计划模式。不要让 Codex 一看到需求就直接动手。

我会这样开头：

请先不要修改任何代码。
先阅读项目结构，理解相关文件，然后给出修改计划。
等我确认后再开始实现。

这个习惯能避免很多问题。因为最可怕的不是 Codex 不会写代码，而是它在没理解边界时写得太快。

5.1 推理强度不要永远开最高

《橙皮书》也提到不同任务可以选择不同思考强度。我的使用习惯：

不要所有任务都开最高。高推理更慢、更贵，也不一定对简单任务有明显收益。

6. CLI：真实项目里绕不开的入口

Codex CLI 是我认为最应该掌握的入口。它适合读项目、修 bug、跑测试、做一次性自动化任务，也最容易和 Git 工作流结合。

6.1 常用命令备忘

这不是完整手册，只保留我觉得常用的：

我最常用的是：

cd 项目目录
git status
codex

进入 Codex 后常用 slash commands：

6.2 什么时候用 codex exec

交互式 codex 适合边看边改。codex exec 更适合一次性任务：

codex exec "请检查当前项目的 README 是否与 package.json 命令一致，不要修改文件，只输出问题清单。"

或者：

codex exec "请根据当前 diff 生成一份 PR 描述，包含修改内容、测试结果和风险说明。"

但新手阶段不建议一上来大量使用 exec。先用交互式模式熟悉 Codex 的行动方式，再把稳定任务自动化。

7. Web / Cloud：等 GitHub 工作流稳定后再上

Codex Web / Cloud 的核心是：Codex 在云端拉取 GitHub 仓库，在隔离环境里处理任务。它很适合：

• 项目已经在 GitHub。
• 有稳定的安装、测试、构建命令。
• 任务可以异步跑。
• 结果可以通过 PR 或 diff review。

它不适合：

• 本地临时练习。
• 没有 GitHub 仓库的项目。
• 依赖大量本地私有环境、但没有配置 setup script 的项目。
• 你还不会看 diff、不会处理分支和 PR 的阶段。

云端任务的关键不是“让 AI 在云上帮你写代码”，而是“你的仓库有没有足够清楚的环境说明”。如果没有 README、没有测试命令、没有 setup script、没有 AGENTS.md，Codex Cloud 也会猜。

所以 Web / Cloud 的前置条件其实是工程卫生：

• README 说明安装和启动。
• package.json / lockfile 清楚。
• 环境变量有 .env.example。
• 测试和构建命令可执行。
• AGENTS.md 说明项目规则。

8. 插件、Skill、MCP：不要混成一团

《橙皮书》里对这三者的区分很重要。它们不是同一种东西。

我喜欢用一句话记：

Skill 管怎么做，MCP 管连什么，Plugin 管怎么安装和分发。

8.1 什么时候做 Skill

如果一类任务你反复做，而且每次都要写一大段规则，就适合做 Skill。

适合做 Skill 的任务：

• 写 README。
• 做代码 review。
• 生成技术文章。
• 做 UI 检查。
• 整理会议纪要。
• 把某种固定格式的资料转成报告。

不太需要 Skill 的任务：

• 临时改一句文案。
• 问一个概念。
• 一次性小任务。
• 需求本身还没稳定。

一个 Skill 通常可以包含：

8.2 什么时候用 MCP

MCP 解决的是 Codex 访问外部工具的问题。

适合 MCP 的场景：

• 查最新开发文档。
• 读取 GitHub issue / PR。
• 连接 Notion 或内部知识库。
• 查询数据库结构或测试数据。
• 读取 Figma 设计稿。
• 操作浏览器或其他外部系统。

普通写代码不一定需要 MCP。只有当 Codex 缺的不是“怎么做”，而是“拿不到外部数据”时，MCP 才真正有用。

我的建议是：不要一开始装一堆插件和 MCP。先把基础工作流跑顺。等你发现某类任务反复出现，再做 Skill；等你发现缺外部数据，再接 MCP。

Codex 上下文基础设施

9. Git、GitHub 和 Worktree：让 Codex 有试错空间

《橙皮书》在 Git 这一章讲得很朴素，但非常关键：用 Codex 做真实项目，一定要懂一点 Git。

原因很简单：

没有 Git，Codex 改错了你很难回退。
有了 Git，Codex 可以大胆试，你可以随时检查和恢复。

9.1 最小 Git 工作流

我会让每次 Codex 任务都贴着这个流程走：

git status
git diff

确认当前状态后再派任务。完成后：

git status
git diff
npm test
npm run build
git add .
git commit -m "feat: ..."

不是每个项目都有 npm test 和 npm run build，但 Codex 至少应该先发现项目有哪些命令，而不是编造命令。

9.2 分支和 worktree

小改动可以直接在当前分支做。大改动、实验性方案、重构，我更倾向于开分支或 worktree。

分支适合：

• 一个任务独立开发。
• 之后要开 PR。
• 需要和主线隔离。

Worktree 适合：

• 想让 Codex 大胆试方案。
• 同时跑多个方向。
• 不想污染当前项目目录。
• 改坏了直接丢掉副本。

可以把 worktree 理解成：同一个 Git 仓库的另一个工作副本。Codex 在副本里折腾，主目录保持干净。

10. AGENTS.md：给 Codex 的项目说明书

如果说 Prompt 是“这一次任务怎么做”，那 AGENTS.md 就是“这个项目以后都怎么做”。

官方文档里把 AGENTS.md 视为给 agent 的开放格式 README。它可以写项目结构、命令、规范、测试方式、禁止事项。更靠近当前目录的 AGENTS.md 会对更局部的任务生效。

我会把这些内容放进去：

一个适合前端/博客项目的简化模板：

# AGENTS.md

## 项目说明

这是一个个人博客项目，用于发布 AI 工具实践、工程笔记、投资复盘、读书笔记和个人随笔。

## 常用命令

- 安装依赖：`npm install`
- 本地开发：`npm run dev`
- 构建检查：`npm run build`

如果项目没有这些命令，请先从 `package.json` 或 README 判断，不要编造命令。

## 内容规范

- 默认使用中文写作。
- 标题要具体，不写空泛口号。
- AI 和金融相关内容需要注明时间点。
- 不确定的信息要标注，不要装作确定。

## 工程规则

- 修改前先阅读相关文件。
- 复杂任务先制定计划，不要直接改代码。
- 一次只处理一个功能点。
- 不要顺手重构无关代码。
- 不要新增不必要依赖。
- 不要修改 `.env`、`.env.local`。
- 不确定业务逻辑时先提问。

## 验证要求

修改后根据项目情况运行：

- lint
- typecheck
- test
- build
- 浏览器或页面手动检查

如果某个命令不存在，请明确说明。

## 完成输出

每次任务结束时输出：

1. 修改了哪些文件
2. 为什么这样改
3. 运行了哪些验证
4. 是否有未验证风险
5. 是否建议更新 AGENTS.md

AGENTS.md 不要写成空泛价值观。它应该具体、短、能执行。Codex 同一个错误出现两次，就把规则补进去。

11. 标准六步法：从需求到交付

《橙皮书》最值得提取的部分，我认为是“标准六步法”。它解决的是一个核心问题：Codex 改得很快，但你怎么知道它改得对？

六步是：

下面展开讲。

11.1 第一步：需求拆解

不要直接说：

帮我优化首页。

这句话太模糊。Codex 可能改标题、改布局、改组件、改全局样式，甚至重构目录。

更好的需求拆解要回答：

需求拆解 Prompt：

请先做需求拆解，不要修改代码。

需求：
【写你的需求】

请按下面结构输出：

1. 背景是什么
2. 要解决什么问题
3. 哪些文件可能相关
4. 哪些功能不能动
5. 什么结果算完成
6. 需要哪些测试
7. 有哪些风险

最后给一个建议执行顺序。

11.2 第二步：制定计划

计划阶段最重要的一句话是：

先不要写代码，也不要修改任何文件。

让 Codex 输出计划，而不是直接执行。

原因很现实：

计划 Prompt：

先不要写代码，也不要修改任何文件。

请根据当前需求和项目结构制定修改计划，包括：

1. 计划修改哪些文件
2. 每个文件为什么需要改
3. 实现步骤
4. 验证方式
5. 风险点
6. 需要我确认的问题

等我确认后再开始执行。

11.3 第三步：小步实现

计划确认后，不要让 Codex 一次性做完所有事情。一次只改一个功能点。

比如“优化首页”可以拆成：

小步实现 Prompt：

请开始小步实现。

当前只执行第 1 步：
【写本次只做的一个功能点】

要求：
1. 只修改和当前功能直接相关的文件
2. 不要顺手重构无关代码
3. 不要修改目录结构
4. 不要新增不必要依赖
5. 不要删除已有功能
6. 不要改计划外文件

修改完成后请停止，并输出：

1. 修改了哪些文件
2. 每个文件改了什么
3. 为什么这些修改必要
4. 有没有计划外修改
5. 有没有潜在风险
6. 下一步建议

如果不确定，请先停下来问我。

这段看起来啰嗦，但非常有效。因为它明确要求 Codex “做完就停”。

11.4 第四步：测试验证

测试阶段的核心是：

不要相信“完成了”，要相信可验证结果。

常见验证顺序：

测试 Prompt：

请对本次修改进行测试，不要继续新增功能。

请按顺序检查：

1. 项目是否有测试命令，如果有请运行
2. 是否有 typecheck 命令，如果有请运行
3. 是否有 lint 命令，如果有请运行
4. 是否有 build 命令，如果有请运行
5. 需要手动测试哪些页面和流程
6. 本次修改可能影响哪些旧功能

最后输出：
- 通过了哪些验证
- 失败了哪些验证
- 失败原因是什么
- 是否可以进入下一步
- 还有哪些未验证风险

11.5 第五步：代码审查

测试通过，不代表可以直接接受。还要看 diff。

重点看：

可以先让 Codex 自审：

请对本次修改做代码审查，不要继续写代码。

重点检查：

1. 是否只改了计划内文件
2. 是否有无关重构
3. 是否新增依赖
4. 是否删除旧逻辑
5. 是否有边界条件问题
6. 是否有安全风险
7. 测试是否充分

如果发现问题，请先输出问题和建议，等我确认后再改。

但最终审查一定要由人拍板。Codex 自审只能帮你暴露明显问题，不能替你承担责任。

11.6 第六步：提交与复盘

交付不是“能跑了”就结束。最后还要做两件事：

1. 生成清楚的 commit / PR。
2. 把经验沉淀成 Prompt 或 AGENTS.md。

好的 commit 至少能说明：

PR 描述可以这样：

## 本次修改

- ...

## 修改原因

- ...

## 测试结果

- [x] npm run build
- [x] 手动检查首页

## 风险说明

- ...

## Reviewer 重点看

- ...

复盘时重点记录：

• 哪个 Prompt 有效。
• Codex 哪一步差点越界。
• 哪个测试遗漏了。
• 哪条规则应该写进 AGENTS.md。

这一步会让 Codex 越用越顺。

12. 30 分钟实操：用 Codex 改一个博客分类问题

前面讲了很多原则，如果没有一个完整例子，读者很容易读完点头，关掉文章后还是不知道第一句该怎么问。

这里我用一个个人博客里很常见的问题做练习：

分类页里有很多旧模板留下来的 0 篇分类，需要收敛为新的博客分类体系。

这个任务不大，但很适合练 Codex，因为它同时包含项目阅读、内容规则、数据来源、页面验证和风险边界。

练习目标不是让 Codex 一次性“优化整个博客”，而是走完一条小而完整的交付链路。

12.1 准备：先把可回滚环境搭好

我会先在终端里做这几件事：

pwd
git status
git switch -c chore/blog-taxonomy-cleanup

如果当前项目还没有 Git，我不会直接让 Codex 开始改。至少先初始化并保存一个基线：

git init
git add .
git commit -m "chore: initial blog baseline"

如果是已经有很多未提交修改的项目，我会先停下来判断这些修改是不是自己要保留的。Codex 很适合帮你改代码，但不适合在一团乱的工作区里帮你猜“哪些文件是重要改动”。

12.2 第一轮：只读项目，不改代码

第一轮 Prompt：

请先不要修改代码。

这是我的个人博客项目，内容会包含：
- AI 与智能体
- 工程实践
- 金融投资
- 阅读笔记
- 个人随笔
- 工具与效率
- 项目记录

当前问题：
分类页里可能有旧模板或导入内容留下的 0 篇分类，标签也可能过于混乱。

请先阅读项目结构，输出：
1. 文章源文件放在哪里
2. frontmatter 使用什么字段
3. 分类页、标签页、系列页在哪里
4. 分类和标签是静态写死的，还是从文章生成的
5. 哪些文件可能需要修改
6. 哪些文件暂时不建议改
7. 需要运行哪些验证命令

只输出分析，不要修改任何文件。

这一轮我主要看三件事：

如果它一上来就改文件，我会打断它，并把“先分析，不修改”写进项目的 AGENTS.md。

12.3 第二轮：让它给计划，而不是给惊喜

第二轮 Prompt：

请基于刚才的项目分析，制定分类体系调整计划。

目标分类只保留：
- AI 与智能体
- 工程实践
- 金融投资
- 阅读笔记
- 个人随笔
- 工具与效率
- 项目记录

约束：
1. 不删除任何文章
2. 不修改文章正文
3. 不改变 URL 路由结构，除非你先说明必要性
4. 不处理首页视觉
5. 不新增依赖
6. 如果涉及旧分类迁移，请先列映射表

请输出：
1. 计划修改哪些文件
2. 每个文件为什么要改
3. 旧分类到新分类的映射建议
4. 标签保留和清理规则
5. 验证方式
6. 风险点

仍然不要修改文件。

这里最重要的是“映射表”。比如：

我不会让 Codex 根据标题直接批量改所有旧文章分类。文章分类是信息架构，不只是字符串替换。比较稳的做法是：先处理 0 篇分类和明显模板项，再逐篇处理真实文章。

12.4 第三轮：只执行一个小改动

第三轮 Prompt：

开始执行，但这次只处理分类页显示逻辑。

本轮目标：
1. 隐藏或移除 0 篇分类
2. 保留已有真实文章分类
3. 如果项目有固定分类配置，改为新的受控分类集合

禁止事项：
1. 不修改文章正文
2. 不批量改 frontmatter
3. 不改首页、不改关于页、不改路由
4. 不新增依赖

完成后停止，并输出：
1. 修改了哪些文件
2. 每个文件改了什么
3. 是否有计划外修改
4. 需要我手动检查哪些页面

这一步只做一个小改动，是为了保留判断空间。比如分类页有两种可能：

如果 Codex 想顺手改标签、首页、导航文案，我会让它停下。一个常见误区是觉得“既然都看到了，就顺便优化一下”。真实项目里，很多问题就是顺手改出来的。

12.5 第四轮：验证不是走形式

第四轮 Prompt：

请验证刚才的修改，不要继续新增功能。

请按顺序执行：
1. 找出项目里的 package manager 和可用脚本
2. 如果有 lint，运行 lint
3. 如果有 typecheck，运行 typecheck
4. 如果有 build，运行 build
5. 如果能本地预览，请说明需要检查哪些页面

最后输出：
1. 通过的验证
2. 失败的验证
3. 失败是否和本次修改有关
4. 仍需要手动检查的地方
5. 是否建议进入下一步

我会手动看这些页面：

如果 build 失败，先判断是不是历史问题。不要让 Codex 为了让 build 变绿，顺手修一大堆和本次任务无关的东西。

12.6 第五轮：把经验写回 AGENTS.md

如果这次改完发现某些规则以后一定会反复出现，就应该沉淀下来。比如博客项目可以加入：

## 内容分类规则

- 每篇文章只能有一个 primary category。
- 一级分类控制在 7 个以内：AI 与智能体、工程实践、金融投资、阅读笔记、个人随笔、工具与效率、项目记录。
- 技术栈名称优先作为 tag，不轻易提升为 category。
- 不展示 0 篇分类，除非这是即将发布的专题入口。
- 不要批量修改文章 frontmatter，除非用户明确要求并给出映射表。

这一步的价值不在这次任务，而在下一次。你不需要每次都从零解释“我的博客分类不想像模板站一样散”。规则写进去，Codex 才会越来越像一个熟悉你项目的协作者。

这个 30 分钟练习跑完后，你至少会形成四个直觉：

1. Codex 先读项目，再改代码。
2. 一个任务必须有清楚边界。
3. 验证要提前设计，而不是最后补一句。
4. AGENTS.md 不是摆设，是把经验固化下来的地方。

13. 常用任务模板

下面这些模板不是为了“优雅”，而是为了减少遗漏。

13.1 读项目模板

请先不要修改任何代码。

请阅读当前项目，并输出一份项目理解报告，包括：

1. 技术栈
- 项目使用了哪些主要技术
- 前端、后端、数据库、构建工具分别是什么
- 是否使用 TypeScript、Tailwind、框架或组件库

2. 目录结构
- 主要目录分别负责什么
- 页面、组件、工具函数、接口、配置文件在哪里
- 哪些目录是核心目录，哪些不建议随便改

3. 启动方式
- 如何安装依赖
- 如何本地启动
- 是否需要环境变量
- 如果 README 里有说明，请优先参考 README

4. 测试命令
- 是否有 test、lint、typecheck、build 命令
- 如果没有相关命令，请明确说明

5. 核心模块
- 项目的核心功能模块有哪些
- 后续修改应该优先查看哪些文件

6. 后续修改风险
- 哪些文件或目录风险较高
- 是否存在全局样式、鉴权、接口、数据库等高风险区域

请只输出项目理解报告，不要修改代码。

13.2 修 Bug 模板

我遇到一个 bug：

- 现象：
- 复现步骤：
- 期望结果：
- 实际结果：
- 相关文件或页面：
- 报错日志：

请先定位原因，不要直接修改。

先给出：
1. 可能原因
2. 需要查看的文件
3. 修复方案
4. 风险点
5. 修复后验证方式

等我确认后再改代码。

13.3 加功能模板

我想新增一个功能：

- 功能描述：
- 入口位置：
- 交互流程：
- 视觉要求：
- 数据来源：
- 不在本次范围内：
- 验收标准：

请先阅读相关代码，给出实现计划。

要求：
1. 不改无关文件
2. 不新增不必要依赖
3. 如果需要修改公共组件，先说明影响范围
4. 实现后运行测试并总结 diff

13.4 前端页面模板

请根据下面要求实现一个页面：

- 页面用途：
- 目标用户：
- 视觉风格：
- 模块结构：
- 中文文案：
- 响应式要求：
- 不要出现的问题：

请先给出组件拆分方案，再开始实现。
不要引入无关依赖，不要改全局配置。

13.5 代码审查模板

请审查当前分支相对 main 的 diff。

重点检查：
1. 潜在 bug
2. 边界条件
3. 安全风险
4. 类型问题
5. 性能问题
6. 是否有无关修改
7. 测试是否充分

请不要直接修改代码，先输出 review 报告。

13.6 重构模板

请重构以下模块：

【模块路径】

目标：
1. 提高可读性
2. 减少重复代码
3. 保持现有行为不变
4. 不改变公共 API
5. 不引入新依赖

请先写重构计划，并说明如何验证行为一致。

14. 从《橙皮书》的实战案例里能提炼什么

《橙皮书》最后用宠物零食网站做了几个案例：先做静态页面，再加登录注册和分类购物车，再做管理后台，后面还尝试 PPT Skill 和视频插件。

我不太关心宠物零食这个主题本身，更关心案例背后的工作模式。

把它抽象出来，其实是一条很清楚的练习路线：

所以不要照搬“宠物零食”这个主题。真正值得学的是任务梯度：先做低风险静态产物，再逐步加入交互、数据、后台和交付物。

14.1 案例一：从一个静态网站开始

案例一的模式是：

1. 创建本地文件夹。
2. 打开 Codex App。
3. 用计划模式生成页面。
4. 打开 HTML 预览。
5. 初始化 Git。
6. 逐步优化细节。
7. 推到 GitHub。
8. 用 GitHub Pages 发布。

这其实是一条很适合新手的练习路线。因为静态网页风险低、反馈快、可视化强，不涉及数据库、支付、权限，很适合熟悉 Codex 怎么改文件、怎么预览、怎么提交。

但要注意：GitHub Pages 只适合静态站点。需要后端、数据库、登录态、支付、敏感交易的业务，不应该直接当静态页面托管。

14.2 案例二和三：从页面到功能，再到后台

后续案例开始增加登录注册、分类、购物车、管理后台。这时任务已经不是“生成页面”，而是“逐步扩展系统”。

这里最值得学的是顺序：

• 先有页面。
• 再加功能。
• 再加数据结构和管理后台。
• 每一步都保存到 Git。

不要一开始就说：

帮我做一个完整电商网站。

这类任务太大，需求边界太多。更好的方式是拆成多个小任务：

第一步：只做商品列表静态页面。
第二步：只做商品分类筛选。
第三步：只做购物车本地状态。
第四步：只做结算确认弹窗。
第五步：只做后台商品列表。

Codex 很适合连续完成小任务，不适合一次吞下整个系统。

14.3 案例四和五：Skill / 插件适合交付型任务

PPT 和视频案例说明了另一个方向：Codex 不只是写代码，也可以通过 Skill 或插件完成交付物。

比如：

• PPT Skill：把内容整理成演示文稿。
• HyperFrames：用 HTML/动画生成视频。
• 浏览器插件：检查页面效果。
• 文档插件：整理正式文档。

这里的关键不是“装哪个插件”，而是看任务是不是有稳定产物。如果有稳定产物，就值得找对应 Skill 或插件；如果只是临时问一句，不必复杂化。

我会用一个很朴素的判断标准：

这也是《橙皮书》案例给我的最大提醒：Codex 的学习路线最好从“低风险、可回滚、有反馈”的项目开始。静态网页不是因为高级，而是因为它能让你快速看见 Codex 的工作方式。

15. 常见失败模式

我把使用 Codex 时最容易踩的坑整理一下。

我的经验是：多数失败不是模型能力问题，而是任务边界问题。

16. 我会怎么在自己的博客项目里用 Codex

以这个博客为例，我不会直接说：

帮我优化博客。

我会先让它读项目：

请先不要修改代码。

这是我的个人博客项目，内容会包含 AI 工具实践、金融投资、读书笔记、工程实践和个人随笔。

请先阅读项目结构，输出：
1. 文章内容放在哪里
2. 分类和标签从哪里生成
3. 首页、分类页、标签页、关于页在哪里
4. 当前有哪些模板遗留内容
5. 哪些地方不建议直接改
6. 后续优化建议

只输出分析，不修改文件。

然后只处理一个点，比如分类：

请只处理分类体系。

目标：
把分类收敛为：
- AI 与智能体
- 工程实践
- 金融投资
- 阅读笔记
- 个人随笔
- 工具与效率
- 项目记录

约束：
1. 不删除文章内容
2. 不修改路由结构
3. 不改首页视觉
4. 如果旧分类来自数据文件，请先说明路径和修改方案
5. 修改后运行构建

完成后输出 diff 摘要、验证结果和风险说明。

如果继续做，我会把博客任务拆成这样的顺序：

我会交给 Codex 的事：

• 读项目结构，整理内容生成链路。
• 找出模板残留的分类、标签和页面文案。
• 起草 AGENTS.md、文章 frontmatter 规范和发布 checklist。
• 补构建、lint、页面检查流程。
• 根据我的草稿做结构编辑和标题优化。

我不会直接交给 Codex 的事：

• 自动批量改所有旧文章分类。
• 代替我写个人经历和判断。
• 直接生成投资结论，尤其是“该买什么、该卖什么”。
• 在没有确认数据来源的情况下写金融事实。
• 为了页面好看大改整个视觉系统。

特别是金融投资相关内容，我会把事实、观察日期和个人判断分开写。比如一篇定投复盘，Codex 可以帮我整理结构、检查表述是否像投资建议、补风险提示，但不能替我决定观点。

我也会把下面这些规则写进博客项目的 AGENTS.md：

## 博客写作规则

- 默认使用中文写作，除非文章主题需要英文。
- 标题要具体，优先说明问题、变化或结论。
- 每篇文章只能有一个 primary category。
- tags 用具体线索，不用过宽的词。
- 金融投资内容必须写明观察日期，并区分事实和个人判断。
- AI 工具文章涉及当前产品、模型、API 时，要核对官方信息。
- 不要把草稿改成营销文案，不要替作者编造个人经历。

这才是我觉得 Codex 最舒服的用法：不是让它自由发挥，而是让它在清楚边界里持续推进。博客看起来是内容项目，但背后也有工程流程：信息架构、模板约束、发布检查、长期维护。Codex 的价值不是帮我“多写几篇”，而是让我少在重复性整理里消耗耐心。

17. 最后：把 Codex 当成流程，而不是工具

这篇文章写得比较长，但核心其实很短：

1. Codex 是工程执行者，不是代码生成按钮。
2. App、CLI、IDE、Web/Cloud 是不同入口，不是互相替代。
3. 权限、Git、AGENTS.md 是基础设施，不是可选装饰。
4. Skill 解决“怎么做”，MCP 解决“连什么”。
5. 复杂任务一定要先计划、小步改、跑验证、看 diff。
6. 同一个规则重复出现，就沉淀到 AGENTS.md 或 Skill。

我现在更愿意把 Codex 看成一种工作流能力。真正提高效率的不是“让 AI 多写一点代码”，而是把需求拆解、上下文整理、验证、审查、文档和复盘这些环节变得更便宜。

如果以后回来看这篇，可以按问题查：

如果只保留一句提醒：

让 Codex 快，但不要让它失控。

参考资料

• bozhouDev/codex-orange-book：非官方中文长教程，本文主要参考其章节组织、工作流、Prompt 模板和实战案例思路，并重新整理为个人技术笔记。
• OpenAI Codex manual：用于校准 Codex 的官方概念，包括 Prompt 结构、AGENTS.md、sandbox、approval、Skill、MCP、CLI、App、Cloud 等。