Skip to content

codex-working-rules.md

Latest commit

 

History

History
136 lines (97 loc) · 6.12 KB

codex-working-rules.md

File metadata and controls

136 lines (97 loc) · 6.12 KB
Raw

Codex Working Rules

当前有效交付规则

以下规则优先级高于本文档中的旧描述，作为当前项目的正式执行口径：

  • 不再采用“需求写完、测试用例跑完就提交”的旧规则。
  • 现在统一采用更接近真实项目的流程：
    • 前后端各自开发并完成本侧内测
    • 先进入 dpy / origin/dpy
    • 基于 origin/dpy 进行前后端联调
    • 联调通过后再进入本地 master
    • 在本地 master 做发布前完整验证
    • 验证通过后才推送 origin/master

状态口径

  • 本地内测通过：表示可以进入 dpy
  • origin/dpy 联调通过：表示可以进入本地 master
  • 本地 master 发布验证通过：表示可以推送 origin/master
  • origin/master 推送成功：才表示正式完成

提交与推送门槛

对于任何完整功能切片或涉及前后端真实功能代码的 TASK：

  1. 前端完成本侧实现与本地内测后，才可进入 dpy
  2. 后端完成本侧实现与本地内测后，才可进入 dpy
  3. 只有当前后端都已经进入 origin/dpy 后，才进行联调
  4. 只有联调无阻塞问题后，才允许把对应改动进入本地 master
  5. 只有本地 master 做完发布前完整验证且通过后，才允许推送 origin/master

结果解释

  • 只有后端完成：不能作为可发布完成态
  • 只有前端完成：不能作为可发布完成态
  • 前后端都进入 dpy 但尚未联调：仍不能进入 master
  • 联调通过但本地 master 发布验证未通过：仍不能推送 origin/master
  • 只有“前后端各自内测通过 + origin/dpy 联调通过 + 本地 master 发布验证通过”后，才进入正式发布

联调与发布验证要求

  • dpy 上的验证口径是“可联调”，不是“可发布”
  • master 上的验证口径是“发布视角验证”，即确认完整功能是否真正可用
  • 联调结果必须留痕，至少说明：
    • 联调环境
    • 通过场景
    • 失败场景
    • 是否存在阻塞发布的问题
  • 联调记录中必须明确给出结论：
    • 允许进入 master
    • 或 暂不允许进入 master

特殊情况

  • 纯文档任务可以按文档任务规则单独提交，不要求前后端联调
  • 纯后端基础设施任务或纯前端基础设施任务，如果当前明确不属于某个前后端闭环切片，需要在 issue 中明确写清“为什么可以脱离联调单独提交”
  • 一旦某任务属于完整功能切片，就必须按上述 dpy -> 联调 -> master 的口径判断是否可发布

当前用户确认规则（必须优先遵守）

用户已明确要求：后续任务开发过程中，除以下情况外，Codex 不要再额外询问确认，直接推进任务、读取 GitHub issue、修改代码、运行测试、提交、推送、同步 Project/Issue 状态。

必须询问的情况仅包括：

  • 系统级配置变更，例如全局环境变量、系统软件安装、系统凭据配置。
  • 删除、重置、强制覆盖、丢弃未提交改动等高风险或不可逆操作。
  • 工具权限层强制要求用户授权的外部执行确认。

常规操作默认直接执行，包括但不限于：

  • 查看 GitHub issue / Project / 仓库状态。
  • 常规代码和文档修改。
  • 运行沙箱内构建、测试、校验脚本。
  • 按既定流程提交到 dpy、推送 origin/dpy、cherry-pick 到 master、验证、推送 origin/master、切回 dpy。
  • 完成任务后关闭对应 TASK issue，并将 Project 状态更新为 Done。

单个任务的外部确认节奏

用户已明确要求：每个 TASK 最多只应出现三次外部确认/授权请求。

  1. 读取任务一次：读取 GitHub issue / Project 任务信息。
  2. 提交到 origin/master 前一次：在请求前必须先说明本次提交内容、变更范围、验证命令和验证结果。
  3. 关闭任务一次：将 Project 状态更新为 Done 并关闭对应 TASK issue，必须合并为一次操作，不要拆成多次询问。

除上述三类外，本地开发、沙箱内测试、本地提交、推送 origin/dpy、cherry-pick 到本地 master、本地 master 验证等任务类操作默认直接执行。

本文件用于记录本仓库中 Codex 后续会话必须延续的协作规则，避免新会话忘记上下文。

执行权限规则

除以下高风险场景外，Codex 应直接操作，不再额外询问用户确认：

  • 本地代码修改、测试、构建、提交。
  • 推送 origin/dpy。
  • cherry-pick 到本地 master。
  • 推送 origin/master。
  • 修改 GitHub Issue / Project 状态。
  • 关闭已完成的 TASK issue。
  • 常规状态查询、日志查询、issue 查询。

以下场景必须先询问用户：

  • 系统级配置变更。
  • 删除类操作。
  • destructive Git 操作，例如 git reset --hard、强制推送、丢弃未提交改动。
  • 安装或变更全局工具、系统环境变量、系统凭据。
  • 其他可能造成不可逆影响或明显越出当前任务范围的高风险操作。

GitHub 凭据规则

当前环境中，沙箱内 GitHub 凭据可能不可用；GitHub 远端写操作可以直接使用沙箱外凭据执行。

常规 GitHub 写操作包括：

  • git push origin dpy
  • git push origin master
  • gh project item-edit
  • gh issue close

这些操作属于本项目固定交付流程，不需要再次向用户做业务确认。若工具层弹出执行权限控件，Codex 直接发起具体命令；用户已约定这类常规发布/状态同步操作可以执行。

分支与发布规则

  • 日常开发在 dpy。
  • 完成任务后推送 origin/dpy。
  • 通过 cherry-pick 将对应提交发布到 master。
  • 在 master 上完成必要验证后推送 origin/master。
  • 推送 origin/master 后必须立即切回 dpy。
  • TASK 完成且代码进入 origin/master 后，将对应 GitHub Project 状态改为 Done 并关闭 issue。

验证规则

  • 每个 TASK 开始前先沉淀验证清单，优先放在 docs/task-verification-task-XX.md。
  • 代码类 TASK 至少运行相关模块的最小测试或构建验证。
  • 编译通过不等于 TASK 完成；必须对照 issue 的 Scope 和 Acceptance 做行为验证。