Files
praxis/docs/07-codex.md
T
阿白叔andClaude Opus 4.7 154f592f3c docs: split language by audience, add Codex / AGENTS.md spec
Language policy: Chinese for human-facing files (README, docs/,
human-fillable templates), English for AI-facing files (CLAUDE.md,
AGENTS.md, AI templates). Commits / PRs / branches / tags stay
English.

- Translate docs/01-06 to Chinese
- Translate README.md, PR / handoff / project README templates to Chinese
- Drop README.en.md (redundant once language policy is explicit)
- Rewrite CLAUDE.md and CLAUDE.md.template under the new policy
- Add AGENTS.md (root) and templates/AGENTS.md.template for Codex
- Add docs/07-codex.md covering Codex usage and AGENTS.md / CLAUDE.md sync rules

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-20 09:44:15 +08:00

4.4 KiB
Raw Blame History

07 — Codex

我们怎么在团队里用 Codex(CLI 与 IDE 集成),以及 AGENTS.md 怎么写。

为什么要规范

Codex 不读 CLAUDE.md。Claude Code 默认不读 AGENTS.md。两个工具在 同一个仓库里干活,看的是不同的"项目说明书"。如果只写一份,另一边就 是裸奔。

我们的做法:两份都写,内容保持同步。哪边的工具进来读哪边的文件。

文件分工

<repo>/
├── CLAUDE.md      ← Claude Code 读的项目上下文
├── AGENTS.md      ← Codex CLI / Codex IDE 读的项目上下文
└── docs/...       ← 给人读的文档(中文)

两个文件内容大体一致:项目是什么、怎么跑、架构、本仓库特有的 约定、不要做什么。

它们的区别是:

  • CLAUDE.md 偶尔会引用 Claude Code 特有的概念(skill、sub-agent、 permission mode、.claude/settings.json)。
  • AGENTS.md 偶尔会引用 Codex 特有的概念(approval 模式、 ~/.codex/config.toml、MCP server 配置)。
  • 双方共有的部分(项目背景、命名约定、语言策略、commit 格式)必须 完全一致。

同步责任

谁改了 CLAUDE.md,谁顺手改 AGENTS.md(反之亦然)。在 PR 描述里 加一句"Synced AGENTS.md"或"Synced CLAUDE.md"——reviewer 一眼就能确认。

如果 PR 只改了一边,reviewer block 这个 PR,让作者补上。

要是哪天发现两边内容已经漂移得太远,开一个专门的 PR 重新对齐, 不要在功能 PR 里捎带修。

Codex 使用约定

启动方式

  • 终端:codex(不指定 prompt 进交互模式)或 codex "<prompt>"(一次性 任务)。在仓库根目录启动,让它能找到 AGENTS.md。
  • IDE:用官方插件(VS Code / JetBrains)。仓库根目录的 AGENTS.md 自动加载。

Approval 模式

默认用 on-request(命令前问一下)。机器是个人的、风险可控的环境 才用 on-failure 或 never。生产环境、共享机器、不熟悉的仓库—— 保持 on-request。

调整方式见 Codex 文档;个人偏好放进 ~/.codex/config.toml,不要 提交进仓库。

沙盒(sandbox)

  • 写代码 + 跑测试:workspace-write + 网络 off。够用了。
  • 需要联网装包 / fetch 资源:临时切 workspace-write + 网络 on,跑完 切回。
  • danger-full-access 几乎不用。除非你知道自己在干嘛而且代价能承担。

不要让 Codex 干的事

跟 Claude Code 一样:

  • 删数据、git push --force、改 auth、动密钥——人决策。
  • 改 schema、加依赖、改 CI——人审批。
  • 跨仓库的改动——手动协调,不要让 agent 一次推两个仓库。

AGENTS.md 写法

每个项目的 AGENTS.md 按这个顺序写:

  1. 项目 —— 一两句话定位。不要超过两句。
  2. 怎么跑 —— Build / test / lint 命令,bash 块。
  3. 架构 —— 一段话。入口、数据流、核心模块。能省字就省字。
  4. 本仓库特有约定 —— 命名、目录、那些代码里看不出来的模式。
  5. 语言策略 —— 哪些文件是中文(人看),哪些是英文(AI 看), commit / PR / branch / tag 用什么语言。
  6. 不要做的事 —— 翻过的车,每条一行。

100 行以内是目标,超出说明它在朝"通用文档"漂移,该拆。

模板见 templates/AGENTS.md.template。

工具选择建议

不是非此即彼,但有偏好:

  • 写 docs / 写规范 —— Claude Code(这个仓库就是它写的)。
  • 大段重构 / 跨多文件功能 —— Claude Code,因为有 plan mode 和 sub-agent。
  • 窄范围编辑、跑个测试、改个配置 —— Codex CLI,启动快。
  • IDE 内 inline 改一段 —— Codex IDE 插件或 Cursor,看习惯。

两个工具混着用没问题,只要:

  • 一个 session 一个工具(别又开 Claude Code 又开 Codex 改同一个文件, 互相覆盖很难追)。
  • 两边产出的 commit 都按本仓库的 commit 格式(03-git-workflow.md)。

配置同步与个人覆盖

  • 项目级:AGENTS.md、CLAUDE.md、.claude/settings.json 都进仓库。
  • 个人级:~/.codex/config.toml、~/.claude/settings.json、 .claude/settings.local.json——永远不进仓库,gitignore 已经覆盖。
  • 个人 token 永远不写进仓库里的任何文件,包括 AGENTS.md。