先确认 Codex CLI 能运行
Codex 真正有用的地方，不是回答问题，而是能读项目、改文件、跑命令、看报错，再按结果改第二轮。
先确认当前机器上的 Codex CLI 能启动，再进入项目根目录使用。不要在任意目录里打开 Codex 后让它猜项目位置。
codex --version
codex --help
cd your-project
codex第一次只让 Codex 读项目
第一次不要直接丢一句“帮我优化这个项目”。范围太大，Codex 会读很多文件，也会做很多假设，后面 review 会很痛苦。
先让它读项目，不改文件。你要它输出模块边界、启动命令、测试命令和风险区域。
先阅读路由、鉴权和用户配置相关代码，不要改文件。
列出你看到的模块边界、启动命令、测试命令，以及你认为最容易出问题的地方。写一个最小 AGENTS.md
`AGENTS.md` 是给 Codex 看的项目说明。它适合放项目怎么构建、怎么测试、哪些规则不能破。这样你不用每次在 prompt 里重复“改完要跑测试”“不要乱改接口”。
先在项目根目录放一个最小版。命令按你的项目替换。
# AGENTS.md
Commands:
- npm run lint
- npm run typecheck
- npm test
Rules:
- Keep edits scoped to the requested task.
- Do not rename public APIs without asking.
- Do not change package versions unless the task requires it.
- Run relevant checks before reporting done.
Review focus:
- Check behavioral regressions.
- Check missing tests.
- Mention commands that failed or were not run.按目录拆 AGENTS.md
如果项目有前端、后端、脚本和文档几个区域，可以放多个 `AGENTS.md`。根目录写通用规则，子目录写局部规则。
不要把所有规则塞进一个大文件。越靠近当前目录的规则越适合写具体约束。
AGENTS.md
apps/web/AGENTS.md
packages/api/AGENTS.md
docs/AGENTS.md配好默认权限
Codex 能读文件、改文件、跑命令。新项目不要一上来给全权限。先用工作区写权限加按需审批，让它在当前项目里干活，需要访问网络、改工作区外文件或执行高风险动作时再问你。
OpenAI Codex 配置参考里，`approval_policy` 控制什么时候暂停询问，`sandbox_mode` 控制文件系统和命令沙箱。
model = "gpt-5.5"
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"
approval_policy = "on-request"
web_search = "cached"不要长期开全权限
不要把全权限当默认配置。只有在你明确要安装依赖、访问外部目录、跑部署命令或处理系统级文件时，再临时打开。
长期使用全权限时，出事很难定位：你不知道是模型判断错、命令写错，还是权限给得太大。
codex --dangerously-bypass-approvals-and-sandbox大任务先要计划
Codex 擅长明确任务。越早让它“直接改”，越容易把不确定性写进代码。大任务先让它读代码和给计划。
你可以用这个模板处理登录、权限、支付、迁移这类高风险改动。
先阅读登录、session、权限校验相关代码。不要改文件。
输出：
1. 当前登录流程
2. 权限校验发生在哪些文件
3. 你认为最小修复范围
4. 需要我确认的问题执行时限制修改范围
确认计划后，再让 Codex 执行。要写清楚允许改哪些文件、要跑哪个验证命令、哪些边界不能碰。
“谨慎一点”没有用。具体边界更有用。
按你列出的最小修复范围执行。
只修改 auth.ts、session.ts 和对应测试文件。
不要改数据库 schema。
不要升级依赖。
不要重命名导出的函数。
改完后运行 npm test -- auth。改完要求验证证据
不要接受一句“已完成”。让 Codex 交代改了哪些文件、为什么这样改、跑了哪些验证命令、结果是什么。
如果命令失败，它需要先解释失败原因，再判断是否和本次修改有关。
改完后运行：
npm run lint
npm run typecheck
npm test
最后报告：
1. 改了哪些文件
2. 为什么这样改
3. 每条验证命令的结果
4. 没有运行的命令和原因没有测试时给最小验证
如果项目没有现成测试，不要让 Codex 空口保证“应该没问题”。让它给最小验证方法。
最小验证可以是脚本、手动步骤或临时命令。没有必要为了一个小改动马上引入完整测试框架。
这个项目没有现成测试。
请给出一个最小验证方法，可以是脚本、手动步骤或临时命令。
先不要新增测试框架。用 review 检查当前 diff
“再检查一下”太松，容易得到一段自我确认。用 review 视角看当前 diff，更接近 PR 审查。
如果你们团队有固定 review 标准，把它写成 `code_review.md`，再在 `AGENTS.md` 里引用。
请 review 当前未提交 diff。重点看：
1. 行为回归
2. 边界条件
3. 安全问题
4. 缺失测试
5. 是否改了任务外的文件把重复要求沉淀成 Skill
如果你每天都对 Codex 说同一句话，就不要继续复制 prompt。重复任务做成 Skill。
适合沉淀成 Skill 的任务包括安全 review、SEO 检查、公众号去 AI 味、PDF 渲染校验和发布前检查。Skill 的价值不是把提示词写得更长，而是让可复用流程有固定触发条件和固定步骤。
| 个人默认偏好 | ~/.codex/config.toml |
| 项目长期规则 | AGENTS.md |
| 重复工作流 | Skill |
| 外部系统和实时数据 | MCP |
接 MCP 前先确认使用场景
MCP 的价值不是更酷，而是少复制粘贴。Codex 能直接读 issue、看 PR、查设计稿、拿内部文档时，你就不用把上下文一段段搬进聊天框。
先接最常用的，不要为了热闹全装上。MCP 会扩大 Codex 能看到、能做的范围。
/mcp
codex mcp --help新机器按这套流程配置
一台新机器上，不要先塞一堆 MCP 和 Skill。先确认 CLI、写最小配置、进项目写 `AGENTS.md`，再用一个小任务试手。
小任务能稳定跑通，再交给 Codex 做更大的修改。
1. 运行 codex --version 和 codex --help
2. 写 ~/.codex/config.toml
3. 在项目根目录写 AGENTS.md
4. 让 Codex 只读项目，不改文件
5. 用一个 lint 或小 bug 修复任务试手记录当前可用配置
Codex CLI、模型、权限策略和项目命令都会变化。把你当前可用的配置记录下来，下次换机器或升级版本时先对比。
不要记录 API Key。只记录能复现工作流的配置。
日期：2026-06-05
Codex CLI：填当前版本
模型：gpt-5.5
reasoning：medium
sandbox：workspace-write
approval：on-request
项目命令：lint / typecheck / test
第一次验证任务：填任务名和结果