OpenAI Codex 工作区交接包：AGENTS.md、权限边界和回滚记录怎么写

把 Codex 放进真实项目后，最容易出问题的不是模型能力，而是工作区边界、交接记录和回滚证据。这里给一套可直接复用的交接包。

1. 01先读摘要，判断是否与你的场景相关。
2. 02再看来源，保留继续查证的路径。
3. 03最后看步骤、风险和可复用动作。

把 Codex 放进真实项目后，最容易出问题的不是模型能力，而是工作区边界、交接记录和回滚证据。独立开发者、小团队和内容站维护者可以先准备一份交接包，让每次自动化改动都有入口、限制、验收和撤回路径。

更新日期与来源依据

更新日期：2026-06-27。OpenAI 开发者站点的 Codex 文档和 CLI 页面在 2026-06-26 可见更新，文档导航也把工具、Shell、MCP、Skills、Apply Patch 等能力放在同一组能力体系里。可复查来源不超过三条：OpenAI Codex docs、OpenAI Codex CLI docs、OpenAI tools docs。

这篇文章不讨论模型评测，也不要求读者复制某个固定配置。它解决的是工作区治理问题：别人接手你的项目时，能否在五分钟内知道哪些目录能改、哪些命令能跑、哪些外部服务不能碰、发布失败后如何回滚。

适用场景

• 你已经让 Codex 或其他代码代理进入一个真实仓库，仓库里有脚本、部署命令、生产密钥路径或 WordPress 发布工具。
• 你经常让代理做网站运营、文章发布、测试修复、主题改版、自动化脚本维护，希望每次任务能留下可审计记录。
• 团队里有多人轮流使用同一个工作区，需要把“能做什么”和“不能做什么”写成文档，而不是靠口头提醒。
• 项目有远程 SSH、WordPress、Cloudflare、图片生成或缓存清理等动作，任何误操作都会影响线上站点。

真实例子：一个内容站每天要发布文章，工作区里同时有 `scripts/wp-remote.sh`、图片生成规则、development log 和远端 SSH 配置。没有交接包时，代理可能重复猜用户名、误用旧域名、跳过质量 gate，或把本该只做 dry-run 的动作直接执行。

不适用场景

• 一次性本地小实验，仓库没有远端写入、生产数据、密钥路径或用户内容。
• 团队已经有成熟的 runbook、权限审批、CI gate、变更审计和回滚演练，AGENTS.md 只需要做入口索引。
• 任务涉及付款、验证码、登录态、删除数据或敏感个人信息，但操作者没有明确授权；这种任务应停在人工确认。

准备材料

• `AGENTS.md`：放在仓库根目录，写项目入口、禁止事项、常用脚本、远端地址、验证命令。
• `docs/development-log.md`：记录已落地变更、原因、验证结果、阻断项和后续动作。
• `docs/roadmap.md` 或同类计划文件：说明当前优先级，避免代理在过期目标上继续施工。
• 一份远端写入清单：列出 SSH、WordPress、Cloudflare、缓存、图片生成、发布队列等动作的风险等级。
• 一份回滚模板：包括变更文件、远端对象、备份位置、撤回命令、验证 URL 和负责人。

操作步骤

1. 第一步，写清“项目事实”。包含生产域名、旧域名、远端路径、已知失败用户名、禁止使用的工具、图片生成顺序和发布硬门槛。事实区只放稳定信息，避免夹杂临时想法。
2. 第二步，写清“默认行为”。例如搜索文件用 `rg`，远端 WordPress 用项目脚本，文件编辑用补丁，发布前必须跑候选、readiness、post-publish、receipt 四个 gate。
3. 第三步，拆出权限层级。只读动作包括读取文档、拉取文章列表、检查 URL；中风险动作包括本地生成文章包、上传封面；高风险动作包括公开发布、清缓存、删除远端文件。每层写触发条件。
4. 第四步，给每类任务配验收命令。代码任务写测试命令，发布任务写 URL、状态、特色图像、移动端和缓存检查，图片任务写尺寸、格式和主题匹配检查。
5. 第五步，补一段“遇到阻断时怎么停”。例如登录、验证码、密钥缺失、合规 review_required、图片服务不可用、重复内容命中时，必须记录阻断而不是伪造完成。
6. 第六步，把每次执行结果写回 development log。不要只写“完成”，要写候选、来源、命令、结果、未解决风险和下次接手的人该看哪里。

验收清单

• 新代理打开仓库后，能在 AGENTS.md 里找到生产站点、远端路径、常用脚本和禁止事项。
• 任何会写远端的命令都有 dry-run 或明确 execute 标记，且文档写明何时能执行。
• development log 能回答“为什么改、改了什么、怎么验证、还剩什么”。
• 回滚模板里至少有备份位置、撤回命令、线上验证 URL 和缓存处理方式。
• 文档没有过期账号、旧域名、猜测性用户名、内部密钥或临时聊天记录。

可复制模板

下面这段可以直接放进 AGENTS.md，再按项目替换。

## Project Entry
- Read docs/README.md, docs/development-log.md, docs/roadmap.md before work.
- Use project scripts for remote WordPress and SSH. Do not guess credentials.

## Write Boundaries
- Read-only: inspect files, run local checks, fetch public URLs.
- Local write: generate reports, article packages, covers, receipts.
- Remote write: publish, purge cache, deploy, delete. Require the runbook gate.

## Verification
- Code: run targeted tests and syntax checks.
- Content: run candidate, readiness, post-publish, receipt gates.
- Publish: verify URL 200, WordPress status publish, featured image, mobile page, sitemap, cache.

## Rollback Record
- Changed files:
- Remote object IDs:
- Backup path:
- Rollback command:
- Verification URL:

常见坑与排错路径

• 坑一：把“项目介绍”写得很长，但没有可执行命令。修法是把每个动作改成命令、文件路径或 URL。
• 坑二：权限只写“谨慎操作”。修法是列出哪些动作永远不能自动做，哪些动作需要 gate，哪些动作可以本地完成。
• 坑三：回滚只写“可以恢复”。修法是提前跑一次备份命令，记录备份文件名和恢复验证路径。
• 坑四：不同代理重复踩同一个坑。修法是在 development log 里写已知失败路径，比如错误用户名、旧域名、不可用 API。

排错顺序：先看 AGENTS.md 是否给了入口，再看 development log 是否有最近同类任务，再看 runbook 是否有硬门槛。如果三处信息冲突，以更具体、更新、和生产安全相关的规则为准；仍不确定时停在本地报告，不做远端写入。

判断规则与后续维护

• 如果项目出现远端发布、付款、删除、登录、密钥或用户数据，交接包必须升级成硬门槛，不再只是说明文档。
• 如果某个命令连续两次失败，要把失败输出和替代路径写入 log，避免下一次重新猜。
• 如果发布链路新增图片提供方、缓存插件或主机路径，要同步更新 AGENTS.md 和 runbook。
• 每月复查一次：删除过期域名、旧脚本、失效账号名和已经废弃的发布方式。

维护建议：把 AGENTS.md 当成“代理能否安全接手”的入口，不要把所有细节塞进去。稳定事实放 AGENTS.md，过程记录放 development log，复杂流程放 runbook，临时选择放当天 receipt。