AIGCBot
中文Get the checklist
Codex principles and daily practice

AI CODING AGENT / ENGINEERING WORKFLOW / LESSON 00

Codex principles and architecture

A Chinese guide to Codex's agentic loop, context, tools, edits, verification, and reporting boundaries.

Reading
14 min
Track
Codex principles and daily practice
Source
Chinese reviewed guide

The reviewed guide body for this track is currently maintained in Chinese.

预计阅读时间: 14 分钟

学习 Codex 的第一步，不是背命令，而是把它看成一个可以进入仓库、理解上下文、执行工具、修改文件并验证结果的工程代理。它和普通聊天助手的差异在于：普通助手主要给建议，Codex 可以把建议变成工作区里的可审查变更。

这篇先建立一张心智地图：Codex 为什么能做工程任务、它的 agentic loop 如何运转、哪些边界必须由人来控制，以及为什么一个好用的 Codex 工作流通常由提示、项目规范、权限、验证和复盘共同决定。

一句话模型

可以把 Codex 理解成下面这条循环：

目标 -> 上下文 -> 计划 -> 工具调用 -> 文件变更 -> 验证 -> 汇报 -> 下一轮反馈

其中最关键的不是“模型很聪明”，而是它能在一个受控工作区里反复完成这几个动作：

阶段Codex 做什么人需要把关什么
目标解析你要改什么、为什么改、完成标准是什么目标是否真实、范围是否清楚
上下文读取文件、搜索符号、查看测试、理解已有约定哪些资料是事实，哪些只是历史假设
计划拆任务、选择实现路径、判断风险方向是否符合产品和工程优先级
工具调用运行 shell、读文件、打补丁、调用 MCP 或插件权限是否合理、是否触碰敏感系统
文件变更修改代码、文档、配置、测试变更是否最小、是否破坏用户已有修改
验证运行 lint、test、build、浏览器检查或手工检查验证是否覆盖真实风险
汇报说明改了什么、哪里验证了、还有什么风险是否可以合并、部署或继续迭代

这条循环决定了 Codex 最适合的工作：有明确产物、能被验证、上下文主要在仓库或已连接工具中的工程任务。

Codex 的几个界面

Codex 可以出现在不同界面里，但底层思路相似：

  • CLI：适合在终端里处理本地仓库、自动化、脚本化和非交互任务。
  • IDE 扩展：适合贴近编辑器做局部修改、解释、重构和快速检查。
  • ChatGPT 桌面应用：适合长任务、计划、文件编辑、差异审查、多工具协作和部署操作。
  • Cloud 或远程任务：适合把相对独立的工作放到托管环境中并行处理。

选择界面时，不要先问“哪个最强”，而要问“上下文在哪里、风险在哪里、我想多强地参与过程”。

如果任务需要看本地服务、浏览器截图、部署脚本和同机文件，桌面应用更自然。如果任务只是“在一个干净仓库里修一个清晰 bug”，CLI 或 Cloud 都可以。若任务高度依赖你当前编辑器焦点，IDE 扩展更顺手。

上下文不是越多越好

Codex 能读取仓库并搜索文件，但它仍然需要方向。一个有效提示通常包括四类信息：

目标：我要达成什么结果。
上下文：哪些文件、错误、截图、接口或业务规则重要。
约束：不能破坏什么，必须遵守什么。
完成标准：通过哪些检查，看到什么现象才算完成。

例如：

帮我把学习页新增 Codex 专题，放在 Flink 前面。
要求：
- 继续使用现有 Next.js 静态导出和 learning.ts 数据模型。
- 不移除备案号。
- 新增文章必须进入 sitemap。
- 完成后运行 lint 和 build，并部署到 aigc-bot.com。

这样的提示不需要很长，但它把目标、边界和验收都交代清楚了。Codex 仍然会自己读代码，但不会在一开始就猜错方向。

权限边界决定信任边界

Codex 的工程能力来自工具调用，工具调用必须被权限边界包住。常见边界包括：

  • 只读：适合解释代码、做方案、审查设计，不允许修改文件。
  • 工作区写入：适合大多数本地开发任务，可以读写当前仓库。
  • 网络访问：适合查官方文档、安装依赖、访问服务，但要防止不受信任内容注入。
  • 更高权限：例如写工作区外文件、操作服务器、部署生产环境，应该只在明确任务中使用。

默认应该让 Codex 在最小权限下工作。要部署生产、修改 Nginx、连接数据库或读取私密系统时，需要把动作和风险说清楚，并留下验证记录。

AGENTS.md 是项目级“工作协议”

如果你每次都要提醒 Codex“别改这个目录”“跑这个命令”“文档要同步”，说明这些规则应该进入 AGENTS.md。它适合承载：

  • 仓库结构和重要目录。
  • 本地启动、lint、test、build、部署命令。
  • 代码风格、提交规则和验收标准。
  • 明确的禁止事项，比如不能删除备案号、不能覆盖用户未提交修改。
  • 特定子目录的额外规则。

AGENTS.md 不是越长越好。最有价值的规则通常来自真实摩擦：Codex 犯过一次错，你纠正；犯第二次，就把规则沉淀下来。

Codex 擅长什么

适合交给 Codex 的任务有明显共同点：

  • 产物能落到文件、命令输出、部署结果或可见页面。
  • 代码库里能找到足够上下文。
  • 能通过测试、构建、截图、日志或接口结果验证。
  • 失败可以回滚，变更可以用 Git 审查。

典型场景包括：

  • 实现一个页面、组件、接口或脚本。
  • 修 bug 并补回归测试。
  • 阅读大段代码并写出调用链说明。
  • 根据截图调整 UI。
  • 同步内容、生成文档、写迁移计划。
  • 对 uncommitted diff 或 PR 做代码审查。
  • 把重复流程沉淀为 Skill、Hook 或自动化任务。

Codex 不应该替你判断什么

Codex 可以给建议，但不应该替你最终承担这些判断：

  • 是否发布到生产。
  • 是否删除数据、轮换密钥或改变权限边界。
  • 是否把未经复核的商业、法律、医疗、安全结论当成事实。
  • 是否引入长期维护成本很高的新依赖。
  • 是否接受一个没有验证、只有“看起来对”的大改动。

工程代理的价值是放大你的执行和审查能力，而不是替你取消判断。

好的 Codex 工作流长什么样

一个成熟的工作流通常长这样：

  1. 任务开始前：目标、上下文、约束和完成标准清楚。
  2. 读代码阶段：Codex 先理解现有模式，而不是直接重写。
  3. 计划阶段：复杂任务先列计划，简单任务直接做。
  4. 实现阶段：改动集中在必要文件，不做顺手重构。
  5. 验证阶段：运行与风险匹配的检查。
  6. 汇报阶段：说明变更、验证和剩余风险。
  7. 复盘阶段：把反复出现的规则写回 AGENTS.md、文档或 Skill。

这也是后面几篇教程的主线：把 Codex 从“能帮忙写代码”升级为“能嵌入你的工程系统”。

参考资料