为 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」 文件中