📚 最佳实践

一、写清楚你要什么

Codex 不需要完美提示词也能给出不错结果，但交代清楚后结果会更稳 —— 尤其大型项目或重要任务。

一个好的提示词包含四件事：

推理强度怎么选：

二、复杂任务先规划，再动手

任务模糊、步骤多的时候，先让 Codex 规划，比直接让它写代码效果好很多。

方式一：Plan 模式（最推荐）

用 /plan 命令或 Shift + Tab 切换。Codex 会先收集上下文、问几个关键问题，再开始实现，而不是直接动手乱改。

方式二：让 Codex 先问你问题

如果你自己思路还不清晰：

> 先问我问题，把我的想法梳理清楚，再开始写代码。

它会帮你把模糊想法变成具体实现方向。

方式三：PLANS.md 执行计划（进阶）

对于超长流程任务，可以配合 PLANS.md 执行计划模板，让 Codex 跑几个小时的连续任务。

# PLANS.md
## 阶段 1：拆解 / 完成标准
- [ ] ...
## 阶段 2：实现 / 完成标准
- [ ] ...
## 阶段 3：测试 / 完成标准
- [ ] ...

跑的时候让 Codex 跟着 PLANS.md 走，每完成一项更新 checkbox。

三、用 AGENTS.md 存下你的规则

每次都在提示词里重复同样的要求很麻烦。AGENTS.md 就是解决这个问题 —— 把规范写进去，Codex 每次启动自动读取，不需要你再重复。

写进 AGENTS.md 的内容

• 项目结构和重要目录说明
• 怎么运行项目（dev / test / build 命令）
• 代码规范和 PR 要求
• 哪些地方不能改、不能碰
• 什么算「做完了」、怎么验收

快速创建

在 CLI 里运行：

> /init

它会自动扫描项目结构、package.json、README 生成起始版本，你再按实际情况修改。

文件放在哪里

越靠近当前目录的规则优先级越高。

实用建议

• 宁可短而准，也不要长而空。一份简洁准确的 AGENTS.md 比洋洋洒洒大文件有用得多
• Codex 犯同样错误两次？让它做个复盘，结论加进 AGENTS.md
• 内容多了可以拆成 code_review.md、architecture.md 等独立文件，在主文件里引用

四、做完不算完，让它验证自己的工作

让 Codex 改完代码后，顺手让它跑测试、检查规范、确认结果。前提是你告诉它「什么叫做好了」。

可以要求它做的事

• 给这次改动写或更新测试
• 跑相关测试套件
• 检查 Lint、格式化、类型检查
• 确认实际行为和需求一致
• Review diff，找潜在 bug 和回归风险

用 /review 做代码审查

> /review main..HEAD        # 对比 base 分支做 PR 式审查
> /review --uncommitted     # 审查未提交的改动
> /review <commit-sha>      # 审查某个 commit

💡 如果你有 code_review.md 文件，在 AGENTS.md 里引用它，Codex 会用里面的标准做审查 —— 团队整体审查风格一致。

五、用 MCP 接入外部信息

有时候 Codex 需要的信息不在代码库里 —— 数据库数据、Jira 任务、实时日志。用 MCP 接入外部系统，比每次手动粘贴信息省事多了。

什么时候用 MCP？

• 需要的信息在代码库之外
• 数据频繁变化
• 想让 Codex 直接调用某个工具，而不是靠你粘贴信息

怎么添加 MCP

CLI 里：

codex mcp add <server-name>

或在 Codex App 设置 → MCP servers。详见 MCP 扩展。

建议

不要一口气接入所有工具。先从一两个能真正减少手动步骤的工具开始，稳定之后再扩展。

六、把重复的工作变成 Skill

同一类工作反复做、每次都要写很长的提示词？把它封装成 Skill，下次直接调用就好。

Skill 适合做什么

• 日志归因分析
• 起草发布说明
• 按 checklist 做 PR 审查
• 制定迁移计划
• 标准化的 Debug 流程
• Incident 总结报告

怎么创建

用 $skill-creator skill 生成第一版，再用 $skill-installer 安装到本地。

写 Skill 的关键

Skill 描述一定要说清楚「做什么、什么时候用它、什么时候不用」。每个 Skill 只做一件事，先把一个典型用例跑通，再考虑覆盖其他情况。

规则很简单：同样的提示词反复用超过 2-3 次，就该变成 Skill 了。

详细见 Skills + Shell 进阶。

七、稳定的流程可以设置自动化

当某个工作流已经稳定可靠之后，可以设置定时自动运行。

自动化适合做什么

• 定期总结最近的 commit
• 扫描代码中的潜在 bug
• 起草版本更新说明
• 检查 CI 失败情况
• 生成每日站会摘要

操作方法

在 Codex App 的 Automations 标签页里，选择项目、提示词、执行频率即可。

八、新手最容易踩的坑

模型选择策略

Prompt 写法

✅ 多说具体场景与约束

❌ 不好：

帮我写个函数处理日期

✅ 好：

用 TypeScript 写一个 formatRelative 函数：
- 输入 Date，输出中文相对时间字符串
- 1 小时内显示"X 分钟前"，1 天内"X 小时前"，1 周内"昨天/前天/X 天前"
- 超过 1 周显示完整日期 YYYY-MM-DD
- 不依赖第三方库
- 写完后用 vitest 写 6 个测试用例覆盖边界

✅ 先放上下文，再问问题

把相关代码 -f 进去再提问，比让 Codex 凭空猜要准得多：

codex -f src/api/user.ts -f types/user.ts "把 user.ts 里的 any 类型全改成具体类型"

✅ 长任务先 plan 再 execute

[第一轮] 我想给现有的 KV 缓存层加上 LRU 淘汰策略，但不破坏已有调用方。
先不要写代码，告诉我你打算怎么改、影响哪些文件、有哪些风险。

[第二轮] 方案 OK，开始实现，按你提的顺序逐步改

让 Codex 先输出计划再实现，错误率会显著下降。

✅ 用 system prompt 锁定风格

codex --system "你是这个项目的资深贡献者。保持现有代码风格：函数式优先、避免类继承、错误用 Result<T,E> 不用 throw" \
      -d ./src "实现 features/auth 模块"

上下文管理

上下文不是越多越好

塞 50 个文件进去，模型反而注意力分散。只放和当前任务直接相关的。

善用 model_auto_compact_token_limit

config.toml 里：

model_auto_compact_token_limit = 900000

当上下文超过 900K Token 时自动压缩历史，避免触达 1M 上限被截断。

长会话用命名 session

codex -s refactor-auth "..."
# 关掉终端，明天继续
codex -s refactor-auth -c "继续昨天的话题"

不同任务用不同 session 名，避免上下文互相污染。

主动 /clear 切换话题

完成一个任务后切到无关任务前，先 /clear 清空当前会话上下文。

推理强度怎么选

安全与隐私

✅ 必开 disable_response_storage

disable_response_storage = true

中转端不存响应内容，只记 Token 用量。

✅ 必开 store: false（OpenCode）

"options": { "store": false }

同理，关闭 OpenAI 响应持久化。

✅ Key 永远不进 Git

把 .codex/auth.json、.continue/config.json、opencode.json 加进 .gitignore：

**/.codex/auth.json
**/.continue/config.json
**/opencode.json

✅ 给生产 Key 加 IP 白名单

控制台 → API Keys → 点 Key 名 → IP 白名单填 CI / 服务器公网 IP。

✅ 分环境用不同 Key

• 本地开发：一个 Key，开宽松额度
• CI/生产：另一个 Key，开 IP 白名单 + 日额度上限

调试与排错技巧

让 Codex 解释错误

npm test 2>&1 | codex "解释这堆失败，从最根本的问题开始排"

让 Codex 跑 minimal repro

我有一个 React 组件偶发渲染两次，写一个最小复现 Demo（单文件、不依赖路由/状态库），帮我定位

用 --exec 让 Codex 自己改自己跑

codex --exec "实现 utils/date.ts 的 formatRelative，写完跑 npm test，失败就改直到全过"

--exec 会真的执行 shell 命令，谨慎在敏感目录使用。

与团队协作

共享 Codex 工作流模板

把常用 prompt 整理成 markdown：

.codex/prompts/
├── review-pr.md
├── write-test.md
└── debug-flake.md

执行时：

codex -f .codex/prompts/review-pr.md -f $(git diff main --name-only)

在 CI 里跑 Codex 做代码审阅

GitHub Actions 示例：

- name: Codex review
  env:
    OPENAI_API_KEY: ${{ secrets.NEXOR_CODEX_KEY }}
  run: |
    git diff origin/main --unified=10 > diff.txt
    codex --json -m gpt-5.4 -r high \
      "review 下面的 diff，输出 JSON: { issues: [{file, line, severity, message}] }" \
      < diff.txt > review.json

快速总结

把 Codex 当队友来配置和维护，时间越长，它对你项目的理解越深，结果会越来越好。