codex-a2a: Instructions file for Codex

AGENTS.md

以下规范适用于当前仓库内的 coding agent 协作与交付流程。

1. 核心原则

• 在保证安全、可追踪的前提下推进任务，避免不必要的流程阻断。
• 保持与现有仓库结构、实现风格和工程习惯一致。

2. Git 工作流

• 禁止直接向受保护分支提交或推送：main/master/release/*。
• 每项开发任务应在独立分支实施，建议从最新主干切出。
• 同步主干优先使用 git fetch + git merge --ff-only，避免隐式合并。
• 允许将开发分支推送到远端同名分支，便于协作与备份。
• 禁止改写公共历史：git push --force、git push --force-with-lease、随意 rebase。
• 仅提交本次任务相关文件，不清理或回滚与任务无关的在地改动。

3. Issue 与 PR 协作

• 开发类任务开始前，先检查是否已有相关 open Issue（例如 gh issue list --state open）。
• 若无相关 Issue，应创建新 Issue 跟踪；Issue 建议包含背景、复现步骤、预期/实际、验收标准，并附 git rev-parse HEAD 快照。
• 仅协作规范/流程文档改动（如 AGENTS.md）可直接修改，无需额外创建 Issue。
• Issue 标题前缀建议使用 [feat]、[bug]、[docs]、[ops]、[chore]。
• 提交信息若服务于某个 Issue，应在 commit message 中标注对应 #issue。
• PR 默认建议创建为 Draft，并在描述中标明关联关系（如 Closes #xx / Relates to #xx）。
• 出现关键进展、方案变化或新风险时，及时在对应 Issue/PR 中同步，避免重复评论。

4. 工具与文本规范

• 读写 Issue/PR 使用 gh CLI，不通过网页手工编辑。
• 务必不要使用 Codex GitHub 连接器（包括但不限于任何 GitHub MCP / connector / app 方式）；任何时候只允许通过 gh CLI 操作 Issue、PR、评论与相关元数据。
• 若 gh CLI 遇到权限、认证、网络策略或仓库策略障碍，必须停止继续尝试，并向人类说明阻塞点，由人类提供帮助或代为执行；不得改用 Codex GitHub 连接器兜底。
• Issue、PR 与评论使用简体中文；专业术语可保留英文。
• 多行正文先写入临时文件，再用 --body-file 传入；不要在 --body 中拼接 \\n。
• 同仓引用使用 #123 自动链接；跨仓引用使用完整 URL。

5. 回归与验证

• 回归策略按改动类型选择；默认基线为：
  • bash ./scripts/validate_baseline.sh
• Before committing, complete the required validation for the current change set; by default, run the baseline checks above before creating a commit.
• Before creating or updating a PR, confirm the relevant local validation has passed so CI is not left to catch issues that are already reproducible locally.
• pre-commit 若自动修复文件（如 ruff --fix），需复查改动后再提交。
• If pre-commit modifies files, include those changes in the same commit and rerun uv run pre-commit run --all-files until it completes without further rewrites.
• After running pre-commit, inspect git status --short before committing or pushing; do not assume hook-made rewrites are already included in the pending commit.
• Do not push or update a PR while the working tree still contains hook-generated edits from the latest pre-commit run.
• Shell/部署脚本改动：在基线之外，至少执行 bash -n 对改动脚本做语法校验。
• 文档-only 改动：可不跑测试，但应自检命令与路径示例可用。
• uv sync --all-extras 仅在首次初始化或依赖变更时需要，不作为每次改动必做项。
• 若受环境限制无法完成某项验证，必须在汇报中明确说明未执行项与原因。