工程化九大原则

CSDN《Codex 使用最佳实践》将官方 best practices 提炼为九大原则。这九条是 Codex 从“代码生成器”变成“工程队友”的关键。

原则 1:Prompt 不用花哨,但上下文要完整

Codex 足够强,即使 prompt 不完美也常能给出不错结果。但在真实大项目里,真正影响结果的不是文案多漂亮,而是有没有把关键上下文说清楚。

四要素:目标 / 上下文 / 约束 / 完成标准(详见第 26 章)。

原则 2:复杂任务先 Plan,再让它动手

简单任务直接做。复杂任务先让 Codex:

• 阅读相关代码
• 复述对问题的理解
• 找出风险点
• 给出修改方案
• 说明验证方式

详见第 13 章 Plan 模式。

原则 3:把重复要求写进 AGENTS.md

如果你发现自己经常反复提醒 Codex:

• 不要改无关文件
• 改完要跑测试
• 提交前先看 diff
• API 返回格式不能变
• 这个项目用 pnpm

这些就不应该每次写进 prompt,而应该沉淀到 AGENTS.md(详见第 10 章)。

原则 4:配置比临场提醒更稳定

很多 Codex 使用问题,本质不是模型能力问题,而是环境配置问题:

• 工作目录不对
• 没有写权限
• 默认模型不合适
• sandbox 太松或太紧
• 缺少必要工具
• MCP 没配好

习惯:

• 个人默认放 ~/.codex/config.toml
• 项目级放 .codex/config.toml
• 临时命令行参数只用于一次性场景

详见第 7、8 章配置。

原则 5:不要只让 Codex 写代码,也要让它验证代码

工程里真正的完成应该是:

• 测试补了没
• 相关测试跑了没
• lint / format / type check 过了没
• diff 有没有异常
• 有没有引入回归

把验证要求写进任务,让 Codex 写代码 + 验证代码(详见第 14 章)。

原则 6:外部上下文用 MCP,不要一直复制粘贴

外部上下文(issue、文档、数据库、监控)如果每次手动复制,很快变成负担。

用 MCP 让 Codex 稳定访问高频、会变化、和任务强相关的信息(详见第 15 章)。

原则 7:重复工作做成 Skill

如果一个流程你重复做了很多次,而且每次都要写一大段 prompt,那它就应该变成 Skill。

适合 Skill 的场景:

• 日志排查
• 发布说明生成
• PR checklist review
• 数据迁移计划
• 事故复盘摘要
• 标准调试流程

详见第 16 章 Skills。

原则 8:稳定流程再自动化

自动化很诱人,但不要太早。正确顺序:

1. 先手动跑通
2. 把方法沉淀成 Skill
3. 确认输出稳定
4. 再放到 automation 里定时执行

Skill 定义方法,Automation 定义时间(详见第 19 章)。

原则 9:长任务要管理 session,不要一个线程聊到底

Session 不只是聊天记录,它会积累上下文、决策和中间状态。

原则:一个 session 对应一个相对完整的任务。

• 同一问题 → 留在同一线程
• 任务分叉 → fork 新线程或用 subagent
• 上下文臃肿 → /compact
• 跨天任务 → /export /load

详见第 17、20 章。

九大原则一句话总结

用清晰上下文启动任务 → 复杂需求先计划 → 用 AGENTS.md 沉淀规则 → 用配置保证一致性 → 用测试和 review 闭环 → 用 MCP 接入外部 → 用 Skill 固化流程 → 用 automation 放大工作流 → 用 session 管理保持干净。

资料来源

• CSDN《Codex 使用最佳实践:别把它当聊天机器人,要当成一个可配置的工程队友》——九大原则中文提炼
• OpenAI 官方 Codex best practices——原始九大原则