给全栈程序员的 Codex 实战手册：别再只会写 Prompt 了

短大纲

• Codex 的核心用法不是“写一条更长的 Prompt”，而是给它搭一套工程工作台。
• 好 Prompt 只有四件事：目标、上下文、约束、验收标准。
• AGENTS.md 是项目说明书，不是垃圾抽屉；越靠近代码，规则越具体。
• rules 管安全边界，hooks 管自动动作，memories 管长期偏好，skills/plugins 管可复用流程。
• 对 Java、Go、Python、C++、Rust、Vue、React 这样的全栈工程，最值钱的是“分层上下文 + 可验证命令 + 小任务边界”。
• 文末给一套 30 分钟升级清单、AGENTS.md 模板、Prompt 模板和日常工作流。

一、先说句不中听的：很多人把 Codex 用成了许愿池

我见过不少程序员第一次用 Codex，姿势很熟悉：

帮我重构这个项目。
帮我修一下这个 bug。
帮我把后端、前端、测试一起搞定。

这当然能跑起来。就像你把一个聪明同事拉到会议室，往他手里塞一台电脑，说：“系统有点复杂，你自己悟一下。”他也许真能悟出点东西，但你最好别把生产环境密码也交给他。

真正的问题不在 Codex 聪不聪明，而在你有没有给它一张合格的“工程地图”。全栈程序员尤其容易踩这个坑：今天改 Java 服务，明天写 Go job，后天修 Python 脚本，晚上还要看 Vue 或 React 的页面。上下文一乱，AI 再聪明也会像刚入职的实习生：很努力，偶尔离谱。

我认为 Codex 的最佳实践可以浓缩成一句话：

不要只优化 Prompt，要优化 Codex 的工作环境。

Prompt 是一次性沟通，环境是长期复利。AGENTS.md、rules、hooks、memories、skills、plugins、worktrees 这些东西，听起来像配置杂货铺，真正用顺了，它们就是给 AI agent 装上的护栏、地图、工具箱和记忆本。

这篇文章整理的是我从 OpenAI Codex 团队分享中学到的一些心得，也加上了最近反复打磨 Codex 工作流时验证过的做法。目标很朴素：让一个同时写 Java、Go、Python、C++、Rust、Vue、React 的工程师，今天读完，明天就能把 Codex 环境提一档。

二、别急着写 Prompt，先写一张“小工单”

Codex 的 Prompt Structure，我建议只抓四块。

换成工程语言，这不是 Prompt，这是工单。

一个坏请求长这样：

帮我优化一下这个接口，顺便把前端也改了。

一个更像样的请求长这样：

Goal:
把订单详情页的加载时间降下来。当前用户进入页面时会同时触发 6 个接口，
其中 `/api/orders/{id}/items` 和 `/api/orders/{id}/summary` 可以后端聚合。

Context Pointers:
- 后端入口：services/order/src/main/java/.../OrderController.java
- 聚合服务参考：services/account/.../AccountOverviewService.java
- 前端页面：web/src/pages/order/OrderDetail.tsx
- 现有请求封装：web/src/api/httpClient.ts

Constraints:
- 不改变现有 REST URL，避免影响移动端旧版本。
- Java 代码按现有 Spring service/controller 分层写。
- React 侧不引入新状态管理库。
- 先给计划，不要直接改文件。

Done When:
- 后端新增或更新单元测试。
- 前端 typecheck 通过。
- 说明哪些接口还保留，哪些调用被合并。

这段并不神秘，但它解决了一个大问题：你不再让 Codex 猜你的脑子。

老程序员都知道，需求文档里最贵的不是字数，是边界。AI 协作也是一样。你把边界写清楚，Codex 才能把精力用在解题上，而不是在仓库里考古。

三、Plan Mode：让 Codex 先当侦察兵，再当施工队

另一个关键建议是：Instead of writing a prompt, build a plan。

这句话很对。尤其是全栈项目，不要一上来就让 Codex 改代码。更稳的节奏是三步：

1. Research：让 Codex 先读代码、找入口、总结架构。
2. Build Plan：让它写出计划，列改哪些文件、为什么改、怎么验证。
3. Execute：确认计划靠谱后，再让它按计划执行。

这有点像我们以前带新人修线上 bug。你不会让新人 SSH 上去就改配置，而是先问：

• 你看了哪些日志？
• 请求链路在哪？
• 回滚方案是什么？
• 怎么证明你修好了？

Codex 也一样。不要因为它打字快，就允许它跳过工程纪律。

我常用这个开场：

请先进入计划模式，不要修改文件。

你要做三件事：
1. 找到相关入口、调用链、测试和构建命令；
2. 给出 2-3 个可能方案，说明取舍；
3. 推荐一个最小改动方案，并列出验证步骤。

如果上下文不足，先问我，不要猜。

这一段最值钱的是最后一句：上下文不足，先问我，不要猜。

AI 最大的问题不是不会写代码，而是它常常不好意思承认“不知道”。我们要把“先问”写进流程里。

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

如果只能先改一个东西，我建议先写 AGENTS.md。

它不是给人看的 README 的替代品，也不是把团队所有规范塞进去的垃圾抽屉。它更像给 Codex 的项目说明书：这个仓库是什么，怎么跑，怎么测，哪些地方不能乱动。

AGENTS.md 的几个实用原则很简单：

• 全局可以有一份 AGENTS.md，放通用行为习惯；
• 仓库里放项目级 AGENTS.md；
• 子目录可以放更具体的 AGENTS.override.md 或同类覆盖文件，处理特殊区域；
• AGENTS.md 要短，最好控制在 100 行以内；
• 大文档不要硬塞进去，应该作为链接或 reference。

我的理解是四个字：分层下沉。

全局规则写“我习惯怎么工作”，仓库规则写“这个项目怎么工作”，模块规则写“这个目录有什么特殊脾气”。

对于一个全栈工程，根目录可以这么写：

# AGENTS.md

## Project Map
- `backend-java/`: Java Spring services.
- `backend-go/`: Go services and background jobs.
- `scripts/`: Python automation scripts.
- `native/`: C++ libraries and bindings.
- `crates/`: Rust components.
- `web/`: Vue or React frontend.

## Working Agreements
- Read relevant code before editing.
- Prefer small, reviewable changes.
- Do not reformat unrelated files.
- Preserve public APIs unless the task explicitly asks for breaking changes.
- Ask before running destructive commands or touching generated files.

## Verification Commands
- Java: use the repo's Maven or Gradle wrapper, then run affected tests.
- Go: run `go test ./...`; use `go test -race ./...` for concurrency changes.
- Python: run `pytest`; run `ruff check` if configured.
- C++: build with the existing CMake or Bazel flow, then run affected `ctest` or unit targets.
- Rust: run `cargo fmt --check`, `cargo clippy`, and `cargo test`.
- Frontend: run `npm run lint`, `npm run typecheck`, and affected tests if configured.

## Security And Privacy
- Never print secrets, tokens, cookies, or personal data.
- Do not commit `.env`, credentials, local databases, or generated private reports.
- Use parameterized APIs for SQL and shell-safe argument handling for commands.

## Done Means
- The change is explained.
- Relevant tests or checks were run, or the reason they were not run is stated.
- Remaining risk is called out explicitly.

注意，这只是模板，不是让你原样复制。真正要填的是你仓库里的真实命令。比如 Java 项目到底是 Maven 还是 Gradle，前端是 pnpm 还是 npm，Python 是 uv 还是 Poetry，这些都应该写清楚。

如果你的仓库是 monorepo，最好继续下沉：

backend-java/AGENTS.md     # Java 分层、测试、日志、安全要求
backend-go/AGENTS.md       # context、goroutine、race test、error handling
scripts/AGENTS.md          # Python venv、ruff、pytest、CLI 参数约定
native/AGENTS.md           # C++ RAII、内存所有权、sanitizer、ABI 约束
crates/AGENTS.md           # Rust fmt/clippy/test、feature flags
web/AGENTS.md              # Vue/React 组件规范、状态管理、UI 库、typecheck

这样做的好处很明显：Codex 改 web/ 时，不需要背 C++ ABI 兼容要求；改 native/ 时，也不需要读一堆 React 组件规范。上下文越准，输出越稳。

五、全栈程序员最该写的不是长文档，而是“验证矩阵”

AGENTS.md 里最容易写虚的是“代码质量要求”。比如：

代码要优雅、健壮、可维护。

这句话正确，但是没什么用。就像体检报告写“建议健康生活”，没人反对，也没人知道明天早上该干什么。

更有用的是验证矩阵：

这张表的重点不是“命令大全”，而是告诉 Codex：不同语言的风险点不一样。

Java 容易把 service 写胖；Go 容易 goroutine 跑飞；Python 容易脚本路径和环境变量搞乱；C++ 的问题常常是生命周期；Rust 的问题常常是过度抽象或类型绕晕；前端则经常在状态、组件边界和异步请求上摔跤。

你把这些写进模块级 AGENTS.md，Codex 才会在正确地方小心。

六、Rules：别把菜谱塞进门禁系统

这里要特别小心一个概念坑。

在很多工具里，“rules”听起来像“写作规范”或“编码规范”。但 Codex 语境里的 rules，更偏向命令权限和安全边界：哪些命令可以直接跑，哪些命令要问，哪些命令应该拒绝。

所以，别把“中文写作风格”“Java 命名规范”“React 组件风格”塞进 rules。那更适合放在 AGENTS.md、skills 或项目文档里。

Rules 更适合管这些东西：

• git push --force、git reset --hard 这类高风险 Git 操作；
• rm -rf、批量删除、覆盖生成文件；
• 会访问生产环境、下载敏感数据、修改远端资源的命令；
• 安装依赖、升级锁文件、触发部署这类有副作用动作；
• 需要突破 sandbox 的本地命令。

一个实用原则：

Rules 的价值不是让 Codex 更会写代码，而是让它不在凌晨两点帮你制造“职业生涯难忘瞬间”。

七、Hooks：把无聊但重要的动作自动化

Hooks 是我很喜欢的一类能力。它不负责“聪明”，它负责“纪律”。

Hooks 常见的注入点包括：PreToolUse、PostToolUse、SessionStart、PermissionRequest、UserPromptSubmit、Stop。名字已经很直白了：工具执行前、执行后、会话开始、权限请求、用户提交、停止时做点事。

对全栈工程，hooks 可以先做四类小事。

1. SessionStart：启动时提醒工作边界

比如进入仓库时自动提示：

• 当前分支是什么；
• 工作区是否有未提交修改；
• 这个项目的主要验证命令是什么；
• 哪些目录有模块级 AGENTS.md。

这不是形式主义。AI agent 最怕一上来不知道自己站在哪个地板上。

2. PreToolUse：危险动作前先拦一下

比如检测到下面动作就要求确认：

• 删除大量文件；
• 改 lockfile；
• 执行数据库迁移；
• 访问生产环境；
• 使用 sudo；
• 覆盖 AGENTS.md、rules、hooks 配置。

这类 hook 像安全员，不需要每天讲话，但关键时刻要敢吹哨。

3. PostToolUse：改完以后跑便宜检查

不是每次都跑全量测试，那会把人等成化石。更合理的是按文件类型跑便宜检查：

注意这里说“可以”，不是必须。hooks 一旦太重，大家会绕开它。工程纪律也讲用户体验，别把安全带做成铁链子。

4. Stop：结束前做复盘

在 Codex 准备停下来时，让它输出：

• 改了哪些文件；
• 跑了哪些验证；
• 哪些验证没跑，为什么；
• 哪些风险还需要人看；
• 有没有新增依赖、配置或隐私风险。

这一步很像 code review 前的自查。不是为了好看，是为了避免“我以为你跑了测试”的经典误会。

八、Memories：只记长期偏好，别记项目秘密

Memories 的作用，是把跨会话的偏好和经验带下去。说白了，memories create context that is injected into Codex across sessions。

这很有用，但也很容易滥用。

我建议 memory 只记三类东西：

1. 长期工作偏好
   比如“我喜欢先计划再改代码”“默认不要强推”“最终回答要说明验证结果”。

2. 稳定技术偏好
   比如“Python 项目优先用 uv”“Go 改并发代码时提醒 race test”“前端改组件后关注 typecheck”。

3. 重复踩坑经验
   比如“这个团队的 lockfile 只能由指定命令更新”“不要把本地生成的数据库文件提交”。

不要把这些放进 memory：

• token、cookie、密码、证书路径；
• 生产环境地址和临时访问方式；
• 一次性任务的细节；
• 还没验证过的猜测；
• 某个 bug 的敏感用户数据。

Memory 是记事本，不是保险柜。全栈程序员经常接触后端密钥、前端埋点、数据库样本、日志片段，更要小心。AI 记性好是优点，记了不该记的东西就是事故。

一个可用的 memory 模板：

# Codex Memory

## Working Preference
- For non-trivial code changes, ask Codex to research and plan before editing.
- Prefer small diffs and focused commits.
- Never run destructive Git commands without explicit approval.

## Verification Preference
- Go concurrency changes should mention race-test coverage.
- Rust changes should run or recommend fmt, clippy, and tests.
- Frontend changes should mention lint/typecheck/build status.

## Privacy Preference
- Do not include secrets, tokens, cookies, or personal data in prompts, logs, or final summaries.

这几行看起来普通，但它们会降低很多重复沟通成本。

九、Skills 和 Plugins：把团队经验封装起来

AGENTS.md 适合放稳定、高频、短规则。那复杂流程怎么办？

比如：

• 生成 Java 服务设计文档；
• 根据 Jira 写验收用例；
• 给 Vue 页面生成组件骨架；
• 做 C++ 崩溃分析；
• 扫描日志隐私风险；
• 修 CVE 并准备 MR；
• 写博客并生成思维导图。

这些就更适合做成 skill。skill 的定义也很清楚：skills bundle full workflows，包括 instructions、resources、scripts。MCP 负责连外部系统，skill 负责把“怎么做事”说清楚。

我的判断标准很简单：

全栈团队特别适合沉淀这些 skills：

• java-service-change：读 controller/service/repository，列事务和权限风险，生成测试计划；
• go-race-review：重点看 goroutine、channel、context、锁；
• python-cli-hardening：检查路径、参数、日志、异常；
• cpp-lifetime-review：检查所有权、RAII、线程和 ABI；
• rust-api-review：检查错误类型、feature flags、public API；
• frontend-component-review：检查 props、状态、hooks、typecheck 和可访问性。

注意，skill 不是为了炫技。它的价值是让团队里“做得好的人”把经验打包，下一次每个人都能复用。

十、Worktrees：让多个 agent 并行，但别互相踩脚

Worktrees 可以让多个 agent 在同一个项目里并行工作，而不互相覆盖本地修改。

这个功能对全栈项目很香。比如你可以同时开三条线：

• 一个 agent 修后端 Java bug；
• 一个 agent 补 React 测试；
• 一个 agent 做 Python 脚本清理。

如果都在同一个工作区里改，冲突概率很高。尤其是 lockfile、生成文件、共享类型定义，一不小心就像三个人同时在一张白板上写字，最后谁也看不清。

Worktree 的原则也很简单：

• 一个 worktree 一个原子任务；
• 每个任务有清楚输入和输出；
• 不要让两个 agent 同时改同一组核心文件；
• 合并前看 diff，不要闭眼相信；
• 大重构不要并行拆太碎，否则协调成本比收益还高。

我会把 worktree 当成“并行实验室”，不是“自动合并机器”。AI 可以帮你跑得快，但方向盘还在你手里。

十一、Context 管理：别让一个会话从早聊到晚

Context management knobs 这件事，对长期使用很关键。

一个线程应该聚焦一个 atomic task，并且有预先约定的输入和输出。别在一个会话里先问 Rust 生命周期，再修 Vue 页面，再让它总结会议纪要，最后回头改 Java 事务。人都会串台，AI 更会。

几个习惯可以立刻改善体验：

• 用 /new 或 /clear 开新任务，别让上下文带着旧包袱；
• 用 /fork 在已有上下文上换方向，但保留必要历史；
• 用 /side 问临时问题，不污染主线；
• 大任务先让 Codex 生成计划，再按计划拆成小任务；
• 每个任务结束后，让 Codex 输出“下一步可接续上下文”。

还有一个很实用的原则：Progressive Disclosure，渐进披露。

也就是说，不要一上来把全仓库、所有文档、所有背景都喂给 Codex。先给入口，让它用 rg、文件路径和测试命令自己找。你要做的是给路线图，而不是把整个城市搬进会议室。

一个好的 AGENTS.md 应该像地图索引：

## Context Pointers
- Architecture overview: `docs/architecture.md`
- API contracts: `docs/api/`
- Database schema: `db/schema/`
- Frontend routing: `web/src/router/`
- Test guide: `docs/testing.md`

它不需要把所有内容复制进去，只要告诉 Codex 去哪里找。

十二、成本效率：贵的不只是 token，还有人的注意力

成本效率可以从 intelligence、speed、smaller scopes、ask for plan、batch smaller requests 这几个旋钮来调。

很多人一听成本，只想到模型价格。其实对工程师来说，更贵的是注意力。Codex 生成一大坨 diff，你要 review；跑错方向，你要回滚；上下文弄乱，你要解释半天。token 费还没上来，人先烦了。

几个省钱也省心的做法：

1. 按任务选 intelligence
2. 改文案、补小测试，不一定需要最高档；

3. 架构判断、跨语言重构、安全敏感变更，再上高档。

4. 小范围请求

5. “重构我的 UI”太大；

6. “把这个组件的 props 拆清楚，并保持现有行为不变”更可控。

7. 先计划再改

8. 计划错了，几十行就能纠正；

9. 代码错了，可能要读几百行 diff。

10. 批量合并小请求

11. “重命名函数、更新测试、跑相关检查”可以一次说清；

12. 不要拆成五条互相缺上下文的请求。

13. 保留可复用上下文

14. AGENTS.md、skills、memories 写好了，后面每次都省解释。

一句话：别让 Codex 用高配模型做低质量输入的擦屁股工作。

十三、30 分钟把你的 Codex 环境提一档

下面这套流程，我建议直接照着做一遍。

第 0-5 分钟：写根目录 AGENTS.md

只写四块：

• 项目地图；
• 常用命令；
• 工作约定；
• 完成标准。

先别追求完美，100 行以内。太长的内容先链接出去。

第 5-10 分钟：给每个技术栈补模块说明

至少给这些目录各写一份短说明：

• 后端服务；
• 前端应用；
• 脚本工具；
• 原生模块；
• 文档或发布目录。

每份只回答三个问题：

• 这个目录负责什么；
• 改这里最容易踩什么坑；
• 改完怎么验证。

第 10-15 分钟：整理一张验证命令表

不要写“运行测试”。写真实命令。

## Verification
- Java: `./gradlew test` or `./mvnw test`
- Go: `go test ./...`
- Python: `uv run pytest` and `uv run ruff check .`
- Rust: `cargo fmt --check && cargo clippy && cargo test`
- Frontend: `npm run lint && npm run typecheck && npm test`

如果仓库没有某个命令，也写出来：

- Frontend: no component test suite yet; run `npm run typecheck` and manually verify affected page.

这比装作有测试诚实得多。

第 15-20 分钟：加三条安全 rules

先别搞复杂，先管住最危险的：

• 强推、hard reset、大规模删除前必须确认；
• 修改生产环境、部署、数据库迁移前必须确认；
• 读取或输出 secrets、tokens、cookies 默认拒绝。

这三条足以挡掉很多“手快一时爽，复盘两行泪”。

第 20-25 分钟：配置两个 hooks

先从轻量级开始：

• SessionStart：提醒分支、未提交修改、验证命令；
• Stop：输出修改摘要、验证结果、未跑检查、剩余风险。

别一开始就让 hooks 跑全量构建。重武器要慎用，不然大家会关掉它。

第 25-30 分钟：写一份 memory

只写长期偏好：

• 先计划，再改代码；
• 小 diff；
• 不碰 secrets；
• 最终回答必须说明验证；
• 重要风险要明说。

然后开一个新会话，用一个真实小任务试跑。不要用“hello world”骗自己。找一个你最近真的要改的小 bug，看看 Codex 有没有少问你三遍废话。

十四、我自己的 Codex 任务模板

最后给一个可以直接复制的模板。

请先不要改文件。先做 research 和 plan。

Goal:
【我要达成的结果，以及为什么要做】

Context Pointers:
- 【相关入口文件】
- 【相似实现】
- 【测试文件】
- 【文档或接口约定】

Constraints:
- 【不能破坏的兼容性】
- 【不能碰的文件或目录】
- 【必须遵守的语言/框架约定】
- 【安全、隐私、日志要求】

Done When:
- 【必须通过的测试或检查】
- 【需要人工验证的场景】
- 【最终回答需要说明的内容】

请输出：
1. 你找到的相关代码路径；
2. 你对当前实现的理解；
3. 2-3 个方案和取舍；
4. 推荐的最小改动计划；
5. 验证步骤和风险。

如果 Codex 的计划靠谱，再补一句：

按这个计划执行。保持 diff 尽量小，不要改无关格式。
每完成一个阶段，说明改了什么、还剩什么、如何验证。

这个模板不花哨，但它有一个优点：不容易把事情聊飞。

十五、安全小卡片：全栈程序员别把 AI 用成泄密工具

Codex 能读文件、跑命令、整理日志，也就意味着它可能接触敏感信息。全栈工程师更要警惕，因为你经常横跨前端、后端、数据库、脚本、CI/CD。

每次配置 Codex 环境，至少过一遍这张卡：

AI 工具越强，边界越要清楚。没有护栏的自动化，不叫生产力，叫赌运气。

总结：Codex 不是神笔，是一套工程系统

如果只记三句话，我希望是这三句：

1. 好 Prompt 是小工单，不是咒语。
2. AGENTS.md、rules、hooks、memories、skills、worktrees 合起来，才是 Codex 的真实生产力。
3. 全栈工程的关键不是让 AI 什么都懂，而是让它在正确上下文里做小而可验证的事。

思维导图

@startmindmap
* Codex 全栈实战手册
** Prompt Structure
*** Goal
*** Context Pointers
*** Constraints
*** Done When
** Plan Mode
*** Research
*** Build Plan
*** Execute
** AGENTS.md
*** Global preference
*** Repo map
*** Module rules
*** Verification matrix
** Guardrails
*** Rules: command boundary
*** Hooks: automatic discipline
*** Memories: long-term preferences
*** Security: no secrets
** Reuse
*** Skills
*** Plugins
*** MCP
** Scale
*** Worktrees
*** Atomic tasks
*** Progressive disclosure
*** Cost knobs
@endmindmap

明天就能做的行动清单

• [ ] 给当前最常用的仓库写一份 100 行以内的 AGENTS.md。
• [ ] 把 Java、Go、Python、C++、Rust、Vue/React 的真实验证命令写成表。
• [ ] 加三条 rules：危险 Git、删除/覆盖、生产/秘密访问。
• [ ] 加两个 hooks：SessionStart 和 Stop。
• [ ] 写一份只包含长期偏好的 memory，不放任何秘密。
• [ ] 下次让 Codex 改代码前，先要求它 research and plan。
• [ ] 对重复三次以上的工作流，考虑沉淀成 skill。

最后还是那句老话：工具会越来越聪明，但工程纪律不会自动长出来。你给 Codex 的环境越像一个成熟团队，它就越像一个靠谱同事；你给它的环境越像一张许愿纸，它就越像一个热心但不太懂业务的临时工。

那么问题来了：你的 AGENTS.md 现在是项目地图，还是另一个没人敢删的杂物间？

本作品采用知识共享署名-非商业性使用-禁止演绎 4.0 国际许可协议进行许可。