如何给 Codex 建立合适的工程规范：从 AGENTS.md 到可验证、可回滚的开发体系

summersolo

92人浏览 · 2026-09-10 15:16:53

summersolo · 2026-09-10 15:16:53 发布

使用 Codex 开发项目时，一个值得警惕的情况是：眼前的问题解决了，但代码库变得更难维护了。

例如，某个页面报错后，修复方式是在前端补一层判断；另一个入口出现同样的问题，又新增一套兼容逻辑。随着需求不断变化，同一条业务规则逐渐散落到多个模块中。最后，功能似乎都能运行，却没有人能够清楚解释：哪一套逻辑才是正确的，修改一个地方会影响哪些链路。

要避免这种局面，不能只依靠一句“请按照最佳实践开发”。

给 Codex 建立工程规范，本质上是在定义一套协作协议：它应该依据什么做判断，可以修改哪些内容，什么时候必须请求确认，以及如何证明任务已经完成。

合适的规范体系，不是一份越来越长的提示词，而是以下几个部分的组合： 明确的任务边界 + 分层的项目知识 + 可执行的工作流程 + 工具层面的约束 + 可检查的交付证据。

本文以 Codex CLI、IDE 等本地开发工作流为主要例子。涉及产品机制的内容依据截至 2026 年 9 月 10 日核对的官方文档；文中的目录结构、审批策略、Git 约定和模板，则是可根据团队情况调整的工程建议。

一、工程规范首先要解决的，不是代码风格，而是决策边界

谈到工程规范，很容易先想到命名、缩进、注释和目录结构。

这些内容当然重要，但对于能够读取文件、执行命令并修改项目的开发代理，更需要先回答：

什么事情由人决定，什么事情可以交给 Codex 自主完成？

建议把责任边界定义为： 人负责业务目标、关键规则、架构取舍、风险接受和发布决策；Codex 负责信息检索、代码分析、方案建议、授权范围内的实现与验证。

这并不是要求每写一行代码都人工审批，而是避免把“执行能力”误当成“业务决策权”。

1.1 把抽象要求改成能够执行的规则

下面几种写法，看似严格，实际缺少操作性：

抽象要求	更可执行的写法
保证代码质量	修改后运行与变更相关的检查，说明执行命令、结果和未验证项
不要乱改代码	修改前列出涉及模块、预期文件范围和不修改的内容；范围扩大时重新确认
深入检查问题	沿相关调用链核对输入、处理、存储和返回，区分直接原因与根本原因
做好 Git 管理	开始前记录工作区状态与基线；按逻辑变更提交，不夹带其他人的修改
不要影响线上	数据库连接、生产配置和发布操作分别授权；不向日常开发环境提供不必要的生产权限

一条值得写进规范的规则，最好包含四个要素：

触发条件：什么情况下适用？ 执行动作：具体要做什么？ 边界限制：不能做什么，何时需要停止？ 验收证据：如何证明已经遵守？

例如：

当修改公共接口的请求字段、响应字段或错误语义时：先列出调用方与兼容性影响，提交变更方案；未经确认，不得直接修改公共契约；修改后补充相应契约测试，并同步接口文档。

这比“注意接口兼容性”更容易执行，也更容易审查。

1.2 不要写无法兑现的绝对承诺

“不允许出现任何 Bug”“必须保证不影响其他模块”，适合作为愿望，不适合作为验收规则。

更合理的表述是：

修改前完成影响分析，修改后执行相应回归验证；对于无法验证的部分，必须说明原因、风险和后续验证方式。

工程规范应该要求有依据地降低风险，而不是要求代理给出无法证明的保证。

二、先理解 AGENTS.md 的作用与加载机制

AGENTS.md 是 Codex 持久化工程指导的重要入口。官方最佳实践建议在其中提供目录结构、运行方式、构建与测试命令、工程约定，以及任务完成的判定方式。

但“仓库里存在这个文件”和“当前任务实际加载了正确的规则”，不是同一件事。

2.1 Codex 如何发现指导文件

按官方说明，Codex 在运行启动时构建指导链：先读取 Codex 主目录中的全局指导，再从项目根目录沿路径读取到当前工作目录。同一目录优先检查 AGENTS.override.md，再检查 AGENTS.md 和已配置的备用文件名；每个目录最多采用一份非空指导文件，靠近当前目录的指导排在后面。默认 Codex 主目录是 ~/.codex，也可以通过 CODEX_HOME 改变。

因此，推荐采用清楚的文件命名和层次：

~/.codex/AGENTS.md # 个人通用约定 project/ ├── AGENTS.md # 项目通用约定 ├── apps/ │ └── web/ │ └── AGENTS.md # Web 模块约定 └── services/ └── orders/ └── AGENTS.md # 订单模块约定

这里有几个重要的实践后果。

使用标准文件名。不要因为已有 agent.md 或“开发规范.md”，就认为它一定会被默认发现。
覆盖文件不是同目录基础文件的自动追加补丁。使用 AGENTS.override.md 时，要检查是否遗漏了原有约束。
启动发现不是全仓库递归扫描。从仓库根目录启动，不代表所有子模块规范都已加载；跨模块任务应主动核对相关目录的指导。更新规则后，也应通过新的运行确认实际生效情况。

2.2 不要把上下文预算当成文档容量目标

官方文档说明，项目指导存在默认 32 KiB 的合并大小限制，可通过 project_doc_max_bytes 配置。这个参数约束的是项目指导读取量，不是模型的全部上下文窗口。

但真正值得关注的，不是怎样把上限调大，而是：哪些内容必须始终出现，哪些内容只在特定任务中需要？

把全部业务规则、完整架构说明、历史故障和测试记录都塞进根目录 AGENTS.md，并不是好的默认选择。

OpenAI 公开的 Harness 工程实践也强调：把 AGENTS.md 当作知识入口和目录，将详细知识放在结构化文档中，而不是维护一份巨大的指令手册。

三、建立分层规范：不同的信息，放到不同的位置

建议按照稳定程度和适用范围组织内容：

层次	载体	主要内容
全局规范	~/.codex/AGENTS.md	通用协作方式、安全底线、Git 和报告原则
项目规范	项目根目录 AGENTS.md	项目入口、运行命令、文档索引、公共约束
模块规范	模块目录 AGENTS.md	局部边界、专用命令、业务不变量和特殊风险
项目知识	docs/	业务、架构、接口、测试、决策记录
任务状态	任务说明或 docs/tasks/	本次目标、基线、审批、进度和未完成项
可复用流程	Skills	重复使用的审查、排查、验收等工作流
强制检查	权限配置、脚本、CI	不依赖文字提醒的执行限制与质量检查

注意：docs/ 的目录名称和任务文件结构是团队约定。不要把“在规范中写了一个路径”，误认为对应文档的完整内容已经自动进入上下文。应明确告诉 Codex 在什么情况下读取哪份资料。

3.1 全局规范只放跨项目仍然成立的规则

全局规范适合写“修改前先给方案”，不适合写“所有项目必须使用某个前端框架”。

原因很简单：你可能同时维护不同技术栈、不同历史包袱、不同上线要求的项目。项目事实不应被个人偏好覆盖。

全局工程协作规范模板（Markdown）

# 全局工程协作规范 ## 决策与授权 - 依据已确认的业务规则执行，不自行补充关键业务、权限或数据规则。 - 修改前说明目标、影响范围、实施方案、验证方式和主要风险，经用户确认后执行。 - 已批准范围内可以连续执行；范围扩大、关键假设变化或出现新的高风险操作时重新确认。 ## 修改原则 - 优先定位根因，在正确责任层进行最小必要修改。 - 不顺带重构无关模块，不引入重复业务实现。 - 尊重现有架构、接口和代码风格；发现冲突时先说明。 - 审查必须完成约定范围，不因发现第一个问题而提前结束。 ## 环境与数据 - 涉及数据库连接或操作的任务，先确认线上或线下环境及允许的操作范围。 - 本任务已经明确授权的环境不重复询问；切换环境或扩大操作范围时重新确认。 - 未经明确授权，不修改生产数据、生产配置或执行发布。 - 不在代码、文档、日志和报告中暴露密钥及敏感数据。 ## Git 管理 - 开始前核对分支、基线和工作区状态。 - 不覆盖、清理或提交归属不明的已有修改。 - 按完整逻辑变更提交，并在模块完成和版本里程碑保留可追溯记录。 - 已获授权时可自主进行本地提交；推送、合并和发布按项目权限执行。 ## 验证与报告 - 根据变更风险执行相应测试和回归检查。 - 不将未执行的检查写成通过，不将推测写成已确认事实。 - 交付时说明修改内容、验证结果、未验证项、剩余风险和 Git 状态。

团队场景注意：不能只依赖某位开发者电脑里的全局文件。团队共同依赖的规范，应进入共享仓库或统一管理机制。

3.2 项目规范要让 Codex 快速找到正确入口

项目级 AGENTS.md 应该能够回答：这个项目做什么？业务依据在哪里？代码怎么组织？应该运行哪些检查？哪些地方不能随意修改？

模板中的尖括号是待填写项。落地时应替换成核验过的事实，不要让 Codex 为了填满模板而猜测。

项目工程规范模板（Markdown）

# 项目工程规范 ## 项目概况 - 项目目标：<一句话说明> - 主要用户与核心流程：<简述> - 技术栈与版本依据：<实际配置文件路径> - 目录入口：<主要应用、服务、共享模块和测试目录> ## 项目知识入口 - 已确认业务规则：docs/business.md - 架构与模块边界：docs/architecture.md - 代码定位地图：docs/code-map.md - 测试与环境说明：docs/testing.md - 重要决策：docs/decisions/ - 当前任务与进度：docs/tasks/ 按任务读取相关资料，不默认加载全部历史文档。修改子目录前，核对该路径适用的模块规范。 ## 运行与验证 - 安装依赖：<工作目录、实际命令、前置条件> - 启动项目：<工作目录、实际命令、目标环境> - 静态检查：<实际命令> - 单元测试：<实际命令> - 集成测试：<实际命令、数据依赖> - 构建：<实际命令> 未验证的命令必须标注“待验证”。运行脚本前核对其环境依赖和数据副作用。 ## 变更边界 - 公共接口、共享模型、权限规则和数据库结构变更需要单独说明影响。 - 不直接编辑生成文件，应修改生成源并重新生成。 - 不为完成当前任务擅自削弱规范、测试门槛或安全配置。 - 文档与实现冲突时，说明双方依据，不自行决定哪一方应该被改写。 ## 完成标准 - 满足本次验收要求。 - 完成与变更相关的检查，并报告未验证项。 - 检查最终差异，不包含无关修改。 - 必要文档与任务状态已同步。 - 按项目授权完成 Git 提交并报告状态。

命令准确性比模板完整性更重要。真实项目没有端到端测试命令，就明确写“尚未建立”；不要为了让文档看起来完整，编造一个实际上不存在的脚本。

3.3 模块规范要说明局部边界，而不是复制全局规范

假设项目有一个订单服务，模块规范示例：

# 订单模块规范 ## 职责负责订单创建、状态流转和订单查询。不承担用户认证、支付结算或通用通知编排职责。 ## 业务不变量 - 状态变更必须通过统一业务入口。 - 不得绕过授权校验直接执行状态修改。 - 重复请求行为以已确认的接口契约为准。 ## 依赖边界 - 通过约定接口调用其他模块。 - 不直接修改其他模块拥有的数据。 - 修改共享契约前，列出调用方及兼容性影响。 ## 验证重点订单创建、重复请求、非法状态流转、越权访问及相关回归。

这里的价值在于告诉 Codex：这个模块拥有什么责任，又不应该承担什么责任。

四、项目文档应该是一张地图，而不是第二份代码仓库

只写“修改前阅读业务文档”还不够。如果文档数量很多，却没有索引、状态和责任边界，Codex 仍然需要在多份资料之间猜测。

4.1 建立业务到代码的定位关系

建议维护一份轻量的 docs/code-map.md。它不需要记录每一个函数，而应该记录业务入口和关键链路。

示例：

业务能力	页面或调用入口	核心处理模块	关键验证入口
用户登录	登录页面、认证接口	认证服务	登录与权限测试
创建订单	下单页面、订单接口	订单服务	创建与重复请求测试
文件上传	上传组件、文件接口	文件服务	文件类型与访问权限测试
消息通知	业务事件、定时任务	通知模块	接收对象与重复发送测试

对于复杂链路，再补充涉及的数据表、缓存、事件和第三方系统即可。

这样，Codex 接到“订单重复创建”的任务时，能够先找到相关入口，再逐步扩大检查范围，而不是每次从整个仓库重新开始。

4.2 区分“应该怎样”和“现在怎样”

这里需要特别纠正一个容易被过度简化的说法：

文档是权威依据，不等于文档永远比代码和运行事实更真实。

建议分别管理两类信息。

规范性依据：描述系统应该怎样，例如已经审批的业务规则、权限矩阵和接口契约。
事实性证据：描述系统现在怎样，例如当前代码、实际数据库结构、测试结果和运行观测。

当两者冲突时，正确动作不是自动选择一边，而是记录差异：

已确认规则：普通用户只能查看自己的订单。当前实现：查询入口未发现相应的数据范围约束。判断：存在实现与业务规则不一致的风险。下一步：确认影响范围并提交修复方案。

尤其不要让 Codex 为了消除“不一致”，直接把业务文档改成当前错误实现。

4.3 给文档增加状态，而不是不断增加副本

建议重要文档至少有草案、已确认、已废弃状态，并记录维护人或责任角色。对于容易变化的文档，还应记录核验时间和适用版本。

不要长期保留多个同时被引用的“最终版”“最终确认版”“最终修订版”。新的决策生效后，应明确旧版本是否废弃，以及哪些地方需要同步。

五、建立“先方案、后执行”的授权流程

官方最佳实践建议，对于复杂、模糊或难以描述的任务，先让 Codex 制定计划，再开始编码。

对于商业项目，可以进一步把它固化成团队流程：

读取规范与任务资料 ↓ 核对代码基线、工作区和目标环境 ↓ 明确验收要求，分析相关链路 ↓ 提交实施方案与影响范围 ↓ 人工确认 ↓ 小步实施、验证与复核 ↓ 同步文档、按授权提交、交付结果

5.1 审批的是变更范围，而不是每一个操作步骤

“先确认再执行”不应退化成：修改一个文件问一次，增加一个测试问一次，执行一条已批准的检查又问一次。

更好的审批对象是一份边界明确的变更方案。

任务变更方案模板

# 任务变更方案任务目标：验收标准：代码基线：问题分析或实现思路：涉及模块与预计文件范围：明确不修改的内容：接口、数据与权限影响：验证方案：主要风险与回退方式：需要确认的事项：

批准后，Codex 可以在这些边界内持续执行。但出现以下变化时，应重新确认：

变化	为什么需要重新确认
修改范围扩大到新的业务模块	原有影响评估可能不再成立
需要改变公共接口或共享数据模型	可能影响其他调用方
发现业务规则存在歧义	不能由实现者自行决定产品行为
需要连接生产环境或执行数据变更	风险等级与原任务不同

5.2 业务审批与工具审批不是同一件事

用户批准“按这个方案修复订单问题”，不等于授权“发布到线上”。同样，用户批准某个命令获得网络访问，也不等于认可该命令所实现的业务变更。

应分别记录： 业务上允许做什么，技术上允许访问什么。 这两种授权缺一不可。

5.3 定义清楚停止条件

不建议只写“遇到问题就停止”，也不建议只写“完成所有任务之前不要停止”。

可以改成：

在已批准范围内持续执行。遇到业务歧义、权限不足、环境不明、不可逆操作或范围扩大时，停止受影响部分并汇报；与阻塞无关、已经批准且能够独立验证的任务可以继续。

这样既保留执行连续性，也不会让“持续执行”变成越权理由。

六、代码修改规范：沿业务链定位根因，在正确层次修复

6.1 不要只检查报错文件

假设页面提示“提交失败”，问题可能在请求构造、接口校验、状态流转、数据约束或下游服务。

建议把检查范围定义为实际相关链路：

用户操作 → 页面与组件 → 状态和请求参数 → 接口与权限校验 → 业务处理 → 数据库、缓存或事件 → 返回结果 → 页面反馈

并不是每个任务都必须涉及这些环节。没有数据库、缓存或第三方服务的链路，应明确“不涉及”，而不是为了显得全面而虚构检查内容。

这里应该坚持两个原则：

检查范围围绕任务展开，而不是每次扫描整个仓库。
一旦约定了审查范围，就应完成该范围，不能发现第一个问题后停止。

6.2 把直接原因、根因和假设分开

一份合格的问题分析应能够区分：

现象：用户连续操作后出现重复记录。直接原因：同一业务请求被处理了多次。候选根因：

前端存在重复触发。
请求重试缺少对应处理。
后端未按约定识别重复业务请求。已确认依据： <实际代码、日志、请求记录或复现结果> 尚未排除： <仍需验证的假设>

在证据不足时，保留候选根因，比直接宣布“已经找到根本原因”更可靠。

6.3 最小改动，不是最少修改行数

假设已经确认，重复操作的问题需要在服务端统一处理。仅在一个页面禁用按钮，可能只覆盖了一个入口。为了少改几行而绕开真正的责任层，未必是最小风险方案。

建议把“最小改动”定义为： 在正确责任层修复问题，不扩大到无关职责，并保留清楚的验证与回退边界。

与此同时，发现公共组件设计不理想，也不代表可以顺手重构全部调用方。应把当前修复和长期治理拆成不同任务。

6.4 给高风险代码变化设置明确规则

对下面几类变化，建议单独要求影响说明。

公共接口变化。说明字段、类型、错误语义和调用方的兼容性。
共享组件或工具变化。检查全部相关调用位置，避免为一个页面加入难以解释的特殊分支。
依赖变化。说明新增依赖的必要性、版本依据和替代方案，不把“升级到最新”当成默认修复方法。
异常处理变化。不通过吞掉异常、返回伪成功或删除校验，让表面现象消失。

七、Git 规范：让每次变更都能被审查和追溯

Git 管理不应只发生在任务结束时。建议把它放到任务开始、实施过程和交付阶段。

7.1 开始前，先了解当前工作区

一组可用于人工或代理预检的只读命令示例：

git status --short --branch git rev-parse HEAD git diff --stat git diff --cached --stat

这些输出应帮助回答：当前在哪个分支？从哪个提交开始？是否已有未提交修改？暂存区中是否存在不属于本任务的内容？

必要时继续检查具体差异，而不是仅根据文件数量判断。

建议明确禁止：

为了获得“干净工作区”，擅自执行丢弃、重置、清理或暂存其他人工作成果的操作。

如果已有修改与本任务重叠，先确认归属。能够隔离时，可以在单独分支或工作树中处理，而不是改写原工作区。

7.2 按逻辑变更提交，而不是按文件数量提交

一次提交最好回答一个清楚的问题：这次变更解决了什么？

因此，同一功能的实现、测试和必要文档可以放在同一个逻辑提交中。不建议把“修复上传问题”“调整首页样式”和“升级公共依赖”混进一个提交。

对于模块开发和大版本迭代，应保留明确的里程碑记录，但这不意味着一定要等整个模块全部完成才第一次提交。可验证的子任务，也可以形成独立提交。

7.3 提交说明要包含原因和验证状态

提交说明的结构示例：

fix(order): 统一处理订单重复提交原因：说明原问题及已确认的触发条件。修改：说明核心处理位置和相关入口变化。验证：填写实际执行的检查及结果。限制：填写尚未验证的场景和已知风险。

提交前，应检查最终暂存差异，避免夹带密钥、日志、大体积临时文件或其他人的修改。

7.4 区分提交、推送、合并和发布

可以允许 Codex 在已审批方案内自主进行本地提交，不必每次重复确认。但建议分别定义以下权限：

本地提交权限
远程推送权限
主分支合并权限
版本标记权限
生产发布权限

尤其当远程操作关联自动化流程时，不应把“做好 Git 管理”理解为对全部后续动作的授权。

八、数据库规范：每个任务都要明确环境和操作范围

数据库规范不能只有一句“不要删除数据”。更关键的是：当前连接的究竟是什么环境？本次允许执行哪些操作？

8.1 以实际连接目标判断环境

“代码在本地运行”和“连接的是线下数据库”，并不是同一个判断。

建议规定：

涉及数据库连接或操作的任务，开始前确认线上或线下环境，并进一步明确本地、测试、预发布或生产目标。任务中已明确授权的同一环境不重复询问；切换连接、账户或操作范围时重新确认。

确认内容可以采用如下结构：

【数据库操作确认】目标环境：目标实例与库名：脱敏展示使用账户及权限：计划操作：查询 / 写入 / 结构变更涉及对象：预期影响范围：数据保护与恢复方式：本次授权边界：

环境检查结果只能证明“连接目标是什么”，不能代替用户授权。

8.2 把安全约定落实到账户和环境

建议日常开发只提供完成任务所需的最低权限。生产排查优先使用受控的只读路径；开发测试使用独立测试数据；数据变更通过审查后的迁移或变更流程执行。

同时，对只读操作也规定字段、记录量、执行范围和超时，不把“只读”当成无需评估的理由。

密码、访问令牌和完整生产连接信息，不应写入 AGENTS.md 或任务报告。

8.3 数据变更需要独立的验证和恢复方案

涉及结构或数据调整时，建议至少说明：变更目的、适用版本、执行顺序、重复执行的处理方式、旧版本兼容性、失败恢复方法，以及如何验证结果。

对于重要变更，不应把“已经备份”当成恢复能力已经得到证明。还需要验证备份是否可用，恢复过程是否符合本次变更要求。

也不要把“包一层事务”当成适用于所有数据库操作的通用恢复方案，应针对实际数据库和操作类型验证。

这里最需要牢记的是：

代码回退不等于数据回退，数据回退也不等于外部业务动作已经撤销。

因此，“上线后有问题就回滚”必须落实为具体步骤，而不能只是一个词。

九、测试规范：定义覆盖要求，更要定义证据要求

“测试通过”这句话，只有在明确测试了什么之后才有意义。

9.1 根据风险选择测试，而不是机械地堆数量

建议使用变更影响驱动的测试矩阵：

测试层次	重点关注
单元与业务规则测试	边界值、状态转换、计算与条件分支
接口与契约测试	参数、返回结构、错误语义、兼容性
集成测试	数据存储、缓存、事件、外部依赖交互
端到端测试	用户实际完成一条业务流程
权限与异常测试	越权、失效状态、非法输入、失败路径
回归测试	共享能力及相邻业务链路
性能与可靠性验证	与本次变化相关的并发、超时、资源消耗等风险

这不是要求每次修改都执行全部类型。修改一处展示文案，不需要机械地执行所有压力测试；修改公共权限规则，也不能只检查一个页面。合理目标是用足够小的测试集合覆盖关键风险，而不是单纯追求测试数量少。

9.2 明确不同检查能够证明什么

编译成功，只能作为构建层面的证据。
接口返回成功，不足以独立证明数据处理正确。
页面能够打开，不足以证明完整业务流程可用。

因此，应把任务完成拆成可检查的条件，而不是用一项检查代替所有结论。

例如，对于“修复重复提交”的假设任务，验收可以覆盖：正常提交、连续操作、重复请求、失败后重试，以及未修改入口的回归。具体期望行为仍须来自已确认的业务契约，不能由测试编写者自行决定。

9.3 测试报告必须保留真实边界

建议每次交付报告至少说明：

验证对象与代码版本：使用环境：实际执行的命令或操作：实际结果：原问题是否完成前后对照：未执行项及原因：尚存风险：

未执行、执行失败、执行通过，应作为不同状态记录。如果没有可用的浏览器环境，就不能声称已经完成真实页面点击验收；如果无法连接约定的测试数据库，就应说明集成验证受阻。

对于原本已经存在的失败，应保留基线证据，区分新增问题和历史问题，而不是直接删除用例或降低断言。

十、把关键规范变成配置与自动化检查

到这里为止，大部分规则仍然属于“告诉 Codex 应该怎样做”。但关键安全和质量要求，不能只依赖文字提醒。

10.1 区分指令、沙箱和审批

Codex 官方文档明确区分：沙箱定义技术上能够访问和修改的范围，审批策略决定哪些动作需要请求许可。

一个用于本地开发的配置起点（TOML）：

approval_policy = "on-request" sandbox_mode = "workspace-write" [sandbox_workspace_write] network_access = false

on‑request 不是每条命令都询问；符合当前沙箱边界的操作可以直接执行。它也不会自动实现你的“业务方案审批”制度。

仅做分析时，可以使用官方文档给出的只读启动形式：

codex --sandbox read-only --ask-for-approval on-request

用户配置通常位于 ~/.codex/config.toml；项目也可以有 .codex/config.toml，但项目配置层仅在项目受信任时加载。组织还可以通过管理策略施加额外限制。

10.2 用不同机制解决不同风险

目标	更合适的落实方式
不修改无关业务	任务范围、方案审批、差异审查
不访问不必要的数据	账户权限、网络与环境隔离
不提交敏感信息	凭据管理、敏感信息检查、提交审查
保持格式和静态质量	格式化、静态检查、持续集成
不破坏公共契约	契约测试、兼容性检查、调用方审查
不绕过发布要求	受保护分支、独立发布权限与审批

这里的持续集成，即 CI，应执行能够稳定重复的检查，而不是每次依靠代理自行决定是否检查。

也建议把规范文件、安全配置和 CI 门槛的削弱，作为需要单独审查的变更。否则，执行者可能通过修改检查本身，让任务表面上通过。

10.3 Rules 和 Hooks 是辅助约束，不是万能防线

Codex 的 Rules 可控制沙箱外命令的执行，并支持允许、提示审批和禁止等决策；官方目前仍将该机制标注为实验性。

Hooks 可以在特定事件或工具调用前后执行检查。但官方也明确提示，工具覆盖存在例外，不应把 Hooks 当作完整的安全边界。

因此，不建议仅靠字符串匹配脚本承担全部生产保护责任。

更稳妥的设计是：

文档负责表达意图，工具检查负责发现常见违规，权限和环境负责限制真实影响。

对于网页、日志、第三方文档和外部工具返回中的“忽略规范”“关闭检查”等内容，也应将其视为待分析的数据，而不是变更授权的来源。

十一、用 Skills 承载重复流程，而不是无限扩充 AGENTS.md

当同一种操作反复出现时，可以考虑把它沉淀为 Skill。例如，根因排查、接口兼容性审查、数据库迁移预检、移动端验收，都属于有明确输入、步骤和输出的流程。

官方说明，Skills 使用渐进式加载：先提供名称和描述，在决定使用某个 Skill 时再读取完整 SKILL.md。本地仓库 Skill 可放在 .agents/skills/，用户级 Skill 可放在 ~/.agents/skills/。

11.1 AGENTS.md 和 Skill 应各司其职

AGENTS.md：哪些约束始终适用，当前项目应如何工作。 Skill：某一类任务应采用什么流程。任务说明：这一次具体要解决什么问题，以及授权边界是什么。

不要在三个位置重复维护同一大段规则，否则后续很容易出现多个版本。

11.2 一个根因审查 Skill 的示例

存放路径：.agents/skills/root-cause-review/SKILL.md

--- name: root-cause-review description: 用于已存在缺陷的根因分析和修复方案评估，不用于直接实施新功能。 --- # 根因审查 ## 输入问题现象、复现信息、审查范围和当前代码基线。 ## 流程 1. 阅读适用规范与任务相关资料。 2. 复现问题，或明确记录无法复现的原因。 3. 沿相关调用链检查输入、校验、处理、存储和返回。 4. 区分直接原因、根因候选与已排除假设。 5. 检查重复实现、历史分支和前后端规则差异。 6. 完成全部约定审查范围。 7. 输出最小修复方案、影响范围和验证计划。 ## 限制本 Skill 默认只分析，不修改代码。需要连接数据库或使用外部系统时，先核对任务授权。不得以调用 Skill 为由绕过项目审批要求。 ## 输出证据摘要、原因分析、受影响链路、修复方案和未解决问题。

这里最关键的不是 Skill 名称，而是它有明确的适用场景和不适用场景。调用一个 Skill，不应自动扩大任务权限。

11.3 控制上下文，应依靠分工，而不只是压缩文字

建议把稳定约束放进规范，把详细知识放进文档，把重复流程放进 Skill，把临时进度放进任务记录。

任务结束后，只有能够长期复用的经验才进入常设规范。一次测试失败日志、临时排查路径和当天的执行进度，不应该永久占据根目录 AGENTS.md。

十二、多 Agent 协作：先明确责任，再考虑并行

Codex 支持通过子代理分解并行任务。官方建议优先从探索、排查、测试分析和汇总等读取较多的任务开始，对多个代理同时写代码的工作流保持谨慎，因为这会增加冲突与协调成本。

12.1 不要把同一句大任务复制给所有 Agent

“你负责后端”“你负责前端”“你负责测试”，仍然可能过于模糊。每个 Agent 至少应该知道：它的目标是什么，可以修改哪些目录，不可以修改什么，依赖什么输入，最后交付什么。

示例角色分工：

分析 Agent：调用链、根因和影响评估；边界：默认只读
实现 Agent：已审批方案内的代码与测试修改；边界：不扩大业务范围
验证 Agent：对照验收要求独立复核；边界：不自行降低验收标准
主 Agent：分工、共享契约、集成和结果汇总；边界：统一处理跨模块冲突

对高耦合任务，建议先采用：并行分析，集中修改，独立验收。 只有当模块边界和公共契约足够清楚时，再扩大并行写入。

12.2 工作树隔离不等于外部环境隔离

Git worktree 能提供独立的工作文件副本，同时共享仓库的提交和分支等元数据，适合并行处理不同分支的任务。

但从工程设计上，还需要分别隔离测试数据、服务端口、缓存命名空间和其他外部资源。不能因为两个 Agent 位于不同工作树，就允许它们同时修改同一数据库或执行互相干扰的集成测试。

公共接口、共享类型、数据库迁移和合并操作，也应指定明确的责任人或主 Agent。

12.3 交接依靠任务状态，不依靠完整聊天记录

建议任务记录保留：

当前基线：已批准方案：已完成事项：剩余事项：已修改文件：验证证据：阻塞与风险：下一步：

不要要求后续 Agent 重读全部历史对话。任务记录的价值，是让新的执行者迅速知道“现在到了哪里”，而不是保存所有思考过程。

十三、规范写完以后，也需要测试

一套规范是否合适，不能只看文字是否完整。需要观察它能否真正改变执行行为。

13.1 用小任务检查规范是否生效

建议在隔离环境中准备一些代表性场景：

测试场景	应观察的行为
要求修复一个边界清楚的小问题	是否先识别范围，而不是顺带重构
工作区已有其他人的修改	是否保留原有修改并核对归属
数据库目标未明确	是否在连接或操作前确认
接口变化影响多个调用方	是否说明兼容性和回归范围
测试环境不可用	是否如实记录未验证，而不是宣称通过
文档与代码冲突	是否列出差异与依据，而不是自行改写规则

这类检查应尽量使用测试仓库、模拟目标和无敏感数据的环境，不必通过真实生产风险来证明规则有效。

同时，要分别验证两件事：

代理是否理解规则
工具是否真的执行了限制

仅让 Codex 复述“我会遵守规范”，不能证明权限隔离和 CI 门槛有效。

13.2 观察行为指标，而不是文档页数

建议关注：无关修改是否减少，环境确认是否遗漏，返工次数是否降低，任务是否提供真实验证证据，以及新会话接手任务是否更容易。

不要仅凭一次任务成功，就给规范贴上“最佳”的标签。比较不同方案时，应尽量保持任务类型、代码基线、工具权限和验收标准一致。

13.3 定期删除过期规则

规范维护不应该只做加法。发现过时命令，应修正；临时约束到期，应移除；已经被自动化检查完全覆盖的细节，可以缩减文字说明；反复出现的失败模式，才值得升级为常设约束。

推荐循环：

观察问题 → 分析缺少的是知识、边界还是工具检查 → 修改对应层次 → 用代表性任务验证 → 保留有效规则，删除无效负担

十四、从已有项目开始，怎样逐步落地

不建议第一天就要求 Codex 生成几十份工程文档。一个更容易维护的顺序是：

第一阶段：建立最小入口 先完成一份准确的根目录 AGENTS.md、必要的运行与验证说明，以及当前项目最重要的业务和代码定位入口。重点是“准确”，不是“齐全”。 Codex CLI 的 /init 可以生成起始 AGENTS.md，但官方也明确建议根据团队实际构建、测试、审查和发布方式修改生成结果。

第二阶段：拿真实任务验证 用一个边界清楚的小功能或缺陷修复，检查规范是否能支持从分析、审批到验证和提交的完整过程。根据实际摩擦调整，而不是提前设计全部流程。

第三阶段：补充局部规则与自动化检查 当某个模块反复出现边界问题时，增加模块规范。当某种检查反复由人工执行时，将它沉淀为脚本或 CI。当某种任务流程反复出现时，再考虑 Skill。

第四阶段：扩展多 Agent 与长期治理 先保证单任务能够稳定交付，再扩大并行范围。同时维护任务索引、架构决策和技术债记录，避免新增流程之后无人维护。

一段用于建立项目规范的启动提示词

请作为本项目的工程规范负责人，先只读检查仓库，不修改文件。核对现有 AGENTS.md、目录结构、技术配置、运行与测试脚本、业务文档、Git 状态及环境使用方式。基于实际项目提出最小可用的规范方案：全局与项目规则分工、必要的模块规范、文档索引、代码修改边界、Git 管理、数据库环境确认、测试和交付标准。区分已核实事实、已有约定和待确认事项；不要猜测业务规则，不编造运行命令，不批量生成空文档。先提交拟新增或修改的文件清单、主要内容与风险，我确认后再落地。