以仓库为中心的 Codex 工作流
这套环境不再把巨大的 ChatGPT Project 当作开发工作的中心。项目的真实边界是本地 Git 仓库，持久化的上下文存储在版本控制的文件中。Codex 应用、CLI 和 VS Code 插件只是进入同一个仓库的不同入口。
核心模型
聊天记录是临时的工作记忆，不是项目的单一事实来源（Source of Truth）。任何会影响后续任务的决策，应该落在 AGENTS.md、架构文档、README、测试或 Issue 中，而不是埋在冗长的对话里。
ChatGPT Projects 仍然适合管理上传的文件、网页来源和相关讨论，但它无法替代本地目录、Git 状态和可运行的测试。如果在 Project 中写代码感觉隔靴搔痒，直接从仓库启动 Codex 即可。
首次接入仓库
为仓库添加 Agent 可读的契约时，不要依赖私有的 bootstrap 项目或要求公开它。进入目标仓库后，先检查现有的所有权结构：
cd /path/to/repository
git status --short --branch
find . -maxdepth 2 -type f \
\( -name 'AGENTS.md' -o -iname 'arch.md' -o -iname 'architecture.md' \) \
-print
然后进行最小化且可审查的修改：
- 保留现有的架构真源，不要创建重复文件；
- 仅当仓库缺少等价契约时，才创建
AGENTS.md； - 兼容 Agent 的桥接文件应引用同一规则，而不是复制粘贴；
- 仅在发现实际缺口时，才添加
.gitignore、.editorconfig或编辑器设置； - 在任何 commit、push 或部署之前，检查
git diff。
如果存在仓库专用的 bootstrap 命令，其公开文档应描述行为，而不是暴露辅助仓库的名称或绝对路径。它应默认执行 dry-run 或仅创建行为，报告冲突的架构候选项，拒绝不安全的路径，并在替换文件前要求明确授权。
项目拥有的有用文件可能包括：
AGENTS.md：仓库的标准契约；.agents/rules/project-guidance.md：兼容 Agent 的桥接文件；.gitignore、.editorconfig和.gitattributes；- 唯一选定的架构文档；
- 可选的项目级 VS Code 设置。
对于成熟仓库，必须保留未提交的工作并审查每一个提议的文件。Bootstrap 的便利性绝不能成为覆盖项目的权限。
AGENTS.md 应该写什么
Codex 会先读取个人指导，然后沿目录路径读取项目级的 AGENTS.md 文件；离工作目录越近的指导优先级越高。项目文件应简短且具体，回答以下问题：
- 仓库的用途是什么，架构真源在哪里？
- 安装、测试、构建和 lint 命令是什么？
- 哪些目录、数据和生成文件不在范围内？
- 修改代码前必须阅读什么？
- 哪些检查定义了“完成”？
- 哪些 push、部署、迁移和破坏性操作需要审批？
不要将一次性任务规格、临时日志或几十页的背景信息塞进 AGENTS.md。持久规则属于契约，领域知识属于文档，行为属于测试，当前目标属于聊天。
Codex 应用：长任务控制台
使用 Codex 应用处理较长的推理、跨文件实现、独立审查或并行工作：
- 打开本地仓库，而不是创建一个巨大的聊天 Project。
- 为每个可验证的结果启动一个聊天。
- 让 Codex 检查 Git 状态、最近的
AGENTS.md和架构真源。 - 对于复杂变更，在实施前建立事实基线。
- 将并行 Agent 放在独立的 Git worktree 中，绝不要放在同一个 checkout 中。
- 任务完成后，将持久决策写回仓库。
保持对话大小大致相当于一个分支或一个结果。当方向改变时，启动新聊天；要比较另一种方法时，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 # 本环境也可用 cx
codex -C /path/to/repository
codex exec "运行测试并解释第一个失败，不要修改文件"
codex review
codex resume
codex doctor
codex update
官方 CLI 命令参考列出了以下常用交互式命令：
保持 workspace-write 和按需审批作为正常边界。不要仅仅为了节省一次确认就使用 --dangerously-bypass-approvals-and-sandbox；仅在需要网络、跨仓库工作或发布时，才提升特定操作的权限。
VS Code 扩展：在代码旁工作
在 WSL 下，将仓库保留在 Linux 文件系统中（例如 $HOME/Projects），并从 WSL 终端启动编辑器：
cd /path/to/repository
code .
VS Code 左下角应显示 WSL: ...。安装官方 Codex 扩展后，使用 Codex 侧边栏图标或从命令面板运行 Codex: Open Codex Sidebar 并登录。CLI 和 IDE 通常共享身份验证和 Codex 配置层。
扩展最适合：
- 解释当前选区或打开的文件；
- 在立即查看 inline diff 的同时进行聚焦修改；
- 将文件或选区添加到当前线程；
- 在编辑器内规划、审查和运行本地工作；
- 将较长的工作委托给云端，并在本地审查结果。
有用的入口包括新建聊天、将文件/选区添加到线程，以及 /plan、/review、/status、/model、/reasoning、/local、/worktree 和 /cloud。如果扩展错误地在 Windows 侧运行，请启用此 VS Code 设置：
{
"chatgpt.runCodexInWindowsSubsystemForLinux": true
}
这是 VS Code 设置，不是 ~/.codex/config.toml 中的键。更改后需重新加载 VS Code 窗口。
紧凑的任务模板
无需向模型投喂巨大的上下文转储。通常四个部分就足够了：
Goal
要实现的可观察结果。
Context
仓库、分支、相关文件、已验证的事实和复现步骤。
Constraints
什么不能改变；是否允许网络、依赖、commit、push 或部署。
Done when
必需的测试、dry-run、diff 检查和验收行为。
有用的开场白是：
首先建立事实基线：确认仓库根目录和 Git 状态，
然后读取最近的 AGENTS.md 和架构真源。保留无关的更改。
直接实施并运行相关测试。报告更改的文件、验证结果和剩余风险。
不要 commit、push 或部署。
对于诊断，说“只读；不要修复”。对于审查，说“不要仅信任测试”。因为每个操作都会改变不同的外部状态，所以应分别授权 commit、push、PR 和部署。
故障排除
Codex 缺乏项目上下文。 验证它是否在正确的目录中启动，然后将稳定信息放入 AGENTS.md 或架构文档中。不要用不断增长的提示词来弥补错误的项目边界。
对话变得缓慢且混乱。 完成一个结果后启动新聊天。使用 /compact、/resume 或 /fork；不要让一个线程承担整个项目生命周期。
CLI 和扩展行为不同。 确认两者使用相同的 WSL 目录和账户，并检查个人 ~/.codex/config.toml 与项目 .codex/config.toml 是否一致。
Bootstrap 流程提议第二份架构文档。 停止并定位现有的真源，包括嵌套文档。人类必须解决多个候选项；自动化不得猜测或创建竞争架构。
真实仓库已有未提交的更改。 永远不要清理或覆盖它们。限制任务范围，让 Codex 识别任务拥有的文件，并为并行工作使用单独的 worktree。
参见 Herdr AI Agent 工作区 了解如何在持久终端中同时管理 Pi、Codex 和 Antigravity CLI；构建日志 记录了周边环境的演进历史。