以仓库为中心的 Codex 工作流

开发工作的中心应该是本地 Git 仓库，而不是一个越聊越长的 ChatGPT Project。项目的真实边界就是这个仓库，要长期保留的上下文写进受版本控制的文件里。Codex 应用、CLI 和 VS Code 插件只是进入同一个仓库的三个入口。

这套做法不限于 Codex。仓库里没有 CLAUDE.md 时，Claude Code 直接读 AGENTS.md；Antigravity CLI 也把 AGENTS.md 当作工作区规则。下文用 Codex 举例，仓库契约、一个结果一个对话和分开授权这几条换成别的 Agent 照样成立。

核心模型

聊天记录是临时的工作记忆，不是项目的单一事实来源（Source of Truth）。任何会影响后续任务的决策，应该落在 AGENTS.md、架构文档、README、测试或 Issue 中，而不是埋在冗长的对话里。

ChatGPT Projects 仍然适合管理上传的文件、网页来源和相关讨论，但它无法替代本地目录、Git 状态和可运行的测试。如果在 Project 中写代码感觉隔靴搔痒，直接从仓库启动 Codex 即可。

首次接入仓库

第一次让 Agent 进一个仓库，要先给它一份契约。AGENTS.md 就是写给 Agent 的项目规则：怎么装、怎么测、哪些不能动、做到什么程度算完成。动手写之前，先看看仓库里已经有哪些规则和架构文档，然后进行最小化且可审查的修改：

1. 保留现有的架构真源，也就是仓库里已经认定为准的那份架构文档，不要再创建一份重复的；
2. 仅当仓库缺少等价契约时，才创建 AGENTS.md；
3. Codex、Claude Code 和 Antigravity CLI 都直接读 AGENTS.md，一般不需要桥接文件；只有某个工具不读它时，才加一个只写“规则见 AGENTS.md”的桥接文件，不要复制规则；
4. 仅在发现实际缺口时，才添加 .gitignore、.editorconfig 或编辑器设置；
5. 在任何 commit、push 或部署之前，检查 git diff。

项目拥有的有用文件可能包括：

• AGENTS.md：仓库的标准契约；
• .gitignore、.editorconfig 和 .gitattributes；
• 唯一选定的架构文档；
• 可选的项目级 VS Code 设置。

对于成熟仓库，必须保留未提交的工作并审查每一个提议的文件。

AGENTS.md 应该写什么

按官方指导文件发现规则，Codex 会先读取个人指导，再从项目根目录沿路径读取到当前工作目录的项目指导；离工作目录越近的指导覆盖较早的指导。Codex 默认最多读入合计 32 KiB 的指导，Claude Code 的文档建议每个 CLAUDE.md 不超过 200 行。项目文件应简短且具体，回答以下问题：

• 仓库的用途是什么，架构真源在哪里？
• 安装、测试、构建和 lint 命令是什么？
• 哪些目录、数据和生成文件不在范围内？
• 修改代码前必须阅读什么？
• 哪些检查定义了“完成”？
• 哪些 push、部署、迁移和破坏性操作需要审批？

不要将一次性任务规格、临时日志或几十页的背景信息塞进 AGENTS.md。持久规则属于契约，领域知识属于文档，行为属于测试，当前目标属于聊天。

Codex 应用：长任务控制台

使用 Codex 应用处理较长的推理、跨文件实现、独立审查或并行工作：

1. 打开本地仓库，而不是创建一个巨大的聊天 Project。
2. 为每个可验证的结果启动一个聊天。
3. 让 Codex 检查 Git 状态、最近的 AGENTS.md 和架构真源。
4. 对于复杂变更，在实施前建立事实基线。
5. 将并行写代码的 Agent 放在独立的 Git worktree 中，绝不要放在同一个 checkout 中；worktree 能隔离什么、不能隔离什么，见多 Agent 协作。
6. 任务完成后，将持久决策写回仓库。

保持对话大小大致相当于一个分支或一个结果。当方向改变时，启动新聊天；要比较另一种方法时，fork；继续旧任务时，resume。较短的上下文更容易审查和恢复。

Codex CLI：默认的仓库入口

官方安装器和基本登录流程如下：

curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex --version
codex login
codex login status

从目标目录启动；CLI 将其启动目录视为项目：

cd /path/to/repository
codex
codex -C /path/to/repository
codex exec "运行测试并解释第一个失败，不要修改文件"
codex review
codex resume
codex doctor
codex update

官方 CLI 命令参考列出了以下常用交互式命令：

命令	用途
/status	检查目录、模型、权限和上下文
/permissions	调整本次会话的审批和沙箱策略
/model	选择模型，并在支持时调整推理强度
/plan	使复杂的执行路径可审查
/review, /diff	审查当前更改和 Git diff
/mention	明确将文件添加到上下文
/new, /resume, /fork	控制对话生命周期
/compact	压缩长上下文并继续
/mcp, /apps, /plugins	检查已连接的能力

保持 workspace-write 和按需审批作为正常边界。不要仅仅为了节省一次确认就使用 --dangerously-bypass-approvals-and-sandbox；仅在需要网络、跨仓库工作或发布时，才提升特定操作的权限。

VS Code 扩展：在代码旁工作

安装官方 Codex 扩展后，使用 Codex 侧边栏图标或从命令面板运行 Codex: Open Codex Sidebar 并登录。CLI 和 IDE 通常共享身份验证和 Codex 配置层。在 Windows 上用 WSL 时，把仓库放在 Linux 主目录下，从 WSL 终端运行 code .，见官方 WSL 说明。

扩展最适合：

• 解释当前选区或打开的文件；
• 在立即查看 inline diff 的同时进行聚焦修改；
• 将文件或选区添加到当前线程；
• 在编辑器内规划、审查和运行本地工作；
• 将较长的工作委托给云端，并在本地审查结果。

有用的入口包括新建聊天、将文件/选区添加到线程，以及 /plan、/review、/status、/model、/reasoning、/local、/worktree 和 /cloud。

开场白与授权

每次交给 Agent 的任务写成一份任务包：目标、上下文、约束和完成条件，写法见上下文工程。

有用的开场白是：

首先建立事实基线：确认仓库根目录和 Git 状态，
然后读取最近的 AGENTS.md 和架构真源。保留无关的更改。
直接实施并运行相关测试。报告更改的文件、验证结果和剩余风险。
不要 commit、push 或部署。

对于诊断，说“只读；不要修复”。对于审查，说“不要仅信任测试”。因为每个操作都会改变不同的外部状态，所以应分别授权 commit、push、PR 和部署。

故障排除

Codex 缺乏项目上下文。 验证它是否在正确的目录中启动，然后将稳定信息放入 AGENTS.md 或架构文档中。不要用不断增长的提示词来弥补错误的项目边界。

对话变得缓慢且混乱。 完成一个结果后启动新聊天。使用 /compact、/resume 或 /fork；不要让一个线程承担整个项目生命周期。

CLI 和扩展行为不同。 确认两者使用相同的目录和账户，并检查个人 ~/.codex/config.toml 与项目 .codex/config.toml 是否一致。

真实仓库已有未提交的更改。 永远不要清理或覆盖它们。限制任务范围，让 Codex 识别任务拥有的文件，并为并行工作使用单独的 worktree。

参见 Herdr：给多个 AI 编程代理用的持久终端，了解如何在持久终端里同时跑几个代理；构建日志 记录了周边环境的演进历史。

我的阅读