为 codex 添加开发门禁.md

# 为 codex 添加开发门禁

当项目进入稳定阶段，或处理某个具体需求时，codex 默认的全量修改模式往往不再适用，此时可以考虑为 codex 添加开发门禁

门禁的优势在于：

- 可控，开发者可以掌握当前开发进度和大体实现

• 修改范围更小，默认每次只处理单个文件
• 代码 review 更方便
• 渐进式开发，中途有变更时改动范围较小，避免推倒重来

添加门禁后，后续的开发流程为：

```
codex 说明本次更改范围 → codex 等待用户确认 → codex 实施更改并汇报此次更改 → 并等待下一阶段确认
```

示例：

## 门禁设置

可以将下面的 prompt 发给 codex，并根据项目实际情况设计适合当前仓库的开发门禁：

```markdown
以下面规则为蓝图，设计符合当前项目的开发门禁：

核心规则：

• 修改前先说明拟修改的文件和原因。
• 每次只完成一个可审查的目标。
• 完成后必须运行 git diff --check 和相关测试。
• 回复中必须列出：修改文件、行为变化、测试结果、未验证项。
• 未经明确要求，不修改无关文件，不执行提交。

参考门禁：
# 仓库协作规则
本文件适用于当前项目仓库及其所有子目录。子目录存在更具体的 `AGENTS.md` 时，以更具体的规则为准。

## 基本原则

• 每次只完成一个可独立审查的目标，避免把无关重构、格式化或功能调整混入同一次变更。
• 对需求、现有实现和判断保持审慎；发现证据不足、规则冲突或影响范围不明确时，先核实再实施。
• 未经用户明确要求，不修改无关文件，不覆盖用户已有改动，不暂存文件，不创建提交，不推送远端。

## 变更前

• 开始工作时先运行 `git status --short`，识别已修改、已暂存和未跟踪文件，并保留用户已有改动。
• 修改前先说明本次可审查目标、拟修改的文件及每个文件的修改原因。
• 修改现有文件前先阅读相关实现、测试和项目规范，不根据文件名或经验猜测行为。
• 若需要扩大范围、修改无关模块、改变公开接口、执行破坏性操作或需求存在关键歧义，先说明影响并等待用户确认。
• 只读检查可在说明后直接进行；代码或文件写入默认需先完成审核门禁。

## 审核授权

• “实施规划”“开始开发”“继续处理”等通用指令，不等同于免除审核或批准多文件批次。
• 只有用户在收到本次审核范围说明后，明确回复“批准审核范围”“批准该批次”或“免除本阶段审核”，才可开始写入。
• 用户确认必须晚于审核范围说明；说明之前给出的通用实施授权无效。
• 涉及公开接口、新增接口、删除接口或字段契约变化时，审核范围必须列出接口路径、请求字段、响应字段和调用方，并获得单独明确批准。
• 未获得批准时，只能进行只读检查和输出审核范围，不得调用写入工具。
• 强制流程为：审核范围说明 → 等待用户确认 → 写入 → diff 自查与验证 → 汇报并等待下一阶段确认。

## 多文件批次

• 默认一个审核阶段只修改一个文件。
• 多个文件确实不可拆分时，审核范围必须列出文件清单、依赖顺序、不可拆分原因和各文件的预期行为变化。
• 只有用户明确回复“批准该批次”后，才可修改该清单内的文件。
• 批次外文件即使与目标相关，也必须重新审核并等待批准。

## 分阶段审核

• 默认采用“先审核、后修改、再复核”的工作方式；用户明确免除审核时才可跳过对应门禁。
• 修改前先列出本阶段目标、核心文件、其他文件、修改原因和预期行为，等待用户确认本阶段范围。
• 默认每个审核阶段只修改一个文件。禁止在未审核范围和顺序的情况下批量修改多个文件。
• 多个文件确实不可分割时，需先说明文件清单、依赖关系及不能拆分的原因；仅在用户明确批准该批次后一起修改。
• 审核顺序遵循重要性和依赖方向：核心业务逻辑、主要接口或数据结构优先，其次是调用方、组件或状态管理，最后是样式、配置和文档。
• 对应测试应随当前阶段设计和验证，但不得以“补测试”为由提前修改尚未审核的生产文件。
• 每个阶段完成后先自查当前 diff，向用户列出实际变化、风险和验证结果，等待审核通过后再进入下一阶段。
• 审核未通过时，只修正当前阶段发现的问题，不开始后续文件或扩大修改范围。

## 实施要求

• 优先进行最小化、行为明确的改动，避免无关格式化、批量重命名和顺手重构。
• 新增或未跟踪文件需说明用途，以及是否属于本次目标。
• 新建源码或文本文件时，必须添加文件级注释，简要说明文件作用或业务意图。
• 不删除、覆盖或纳入提交本地配置、日志、密钥及其他与目标无关的文件。

## 完成与验证

• 完成后必须运行 `git status --short`，确认改动范围和未跟踪文件。
• 完成后必须运行 `git diff --check`，检查空白错误；同时注意该命令不会检查未跟踪文件。
• diff 自查时必须逐个检查新增或修改的函数、核心逻辑和关键分支，确认必要注释完整；不得仅以文件中存在注释作为通过依据。
• 必须运行与本次变更相关的测试、构建、类型检查或静态检查；优先使用仓库已有命令。
• 无法运行的验证项必须说明原因，不将“未运行”或“命令中断”表述为“通过”。

## 完成回复

每次完成代码变更后，回复必须包含：

1. 修改文件：列出文件及各自修改目的。
2. 行为变化：说明用户或系统可观察到的变化。
3. 验证结果：列出实际执行的命令及结果。
4. 未验证项：列出未运行的测试、外部依赖、已知风险和需人工确认的内容；没有则明确写“无”。
5. 当前 Git 状态：说明未跟踪、未暂存、已暂存和已提交情况。

## 审查模式

• 用户要求审查时只做只读检查，除非用户随后明确要求修复。
• 基于当前 Git diff、相关代码和测试审查正确性、回归风险、边界条件、测试缺口及无关改动。
• 按严重程度报告发现，区分已确认问题和待确认风险，并给出对应证据。
• 没有发现问题时也要说明剩余风险和未覆盖的验证范围。

```
门禁生成后，会写入当前项目目录下的 「AGENTS.md」 文件中