pr-maintainer

PR 维护者

维护由 Codex 或 Claude Code 创建的 PR 时，如果仓库存在 PR 维护政策或 ADR，请遵循该政策或 ADR。

使用时机

Agent 创建 PR（包括草稿 PR）后，或有人要求继续处理 Agent 创建的 PR，完成 CI、审查意见、修复提交并合并时，使用此技能。

即使将 Agent 创建的草稿 PR 标记为可供审查的操作是用户在 Agent 会话之外手动完成的，也要在该草稿 PR 刚变为可供审查时立即使用此技能。将该状态变更视为开始监控 CI 和审查状态的信号。

如果创建草稿 PR 仅仅是因为仓库工作流要求创建草稿 PR，并且实现已通过仓库约定的本地验证（确切的 CI 等效筛选条件请参阅项目的测试规则），则应在同一会话中将其标记为可供审查，并立即进入轮询工作流。不要仅仅因为 PR 是通过 --draft 创建的，就让可供审查的草稿 PR 闲置。

Codex 和 Claude Code 共用此技能。GitHub 的 I/O 通过 gh 执行；Agent 专属的部分仅限于在现有工作树中应用修复的代码编辑会话。

核心政策

• 继续使用创建 PR 时的同一 Agent 会话和同一专用工作树。

• 默认创建可供审查的 Agent PR。除非用户明确要求仅发布草稿，或实现尚不可供审查，否则不要在 gh pr create 中传入 --draft。

• 创建 PR 后，立即确保满足非草稿状态的后置条件，然后再轮询 CI 或设置自动合并：

  IS_DRAFT="$(gh pr view "$PR" --json isDraft -q .isDraft)"
  if [ "$IS_DRAFT" = "true" ]; then
    gh pr ready "$PR"
  fi
  
  IS_DRAFT="$(gh pr view "$PR" --json isDraft -q .isDraft)"
  if [ "$IS_DRAFT" = "true" ]; then
    echo "PR is still draft; aborting auto-merge setup."
    exit 1
  fi
  

• 如果 PR 已可供审查，不要只停留在草稿 PR URL。应先将其标记为可供审查，然后立即进入轮询工作流。

• 仅在用户明确要求仅发布草稿、本地验证尚未完成或未通过、工作范围有意暂不供审查，或必须报告阻塞问题时，才让 PR 保持草稿状态。

• 如果用户表示已手动将草稿 PR 改为可供审查，请立即进入轮询工作流。

• 不要使用 @codex fix 或由 GitHub 评论触发的修复命令。

• 轮询时间最多 20 分钟，每 3 分钟一次。

• 使用 gh / gh api 处理 PR 状态、检查、失败日志、评论、问题创建、标签、回复和合并。

• 在同一工作树中修复 CI 失败和审查问题，然后运行仓库常规的推送前验证。

• 使用日语回复每条审查评论。

• 不要自动解决审查线程。

• 最多进行 4 轮修复。

• 如果第 4 次尝试后仍需继续修复，或者修复审查问题又引发了更多设计层面的审查问题，请停止并升级为设计讨论。

• 只有在机器人审查已顺利完成且所有必需检查均通过时，才可在没有人工干预的情况下合并。

• 如果审查或评论为空集，应视为“审查尚未完成”，而不是审查通过。

• 使用 squash 合并。

• PR 合并后，立即按照项目的工作树目录清理已合并的工作树（请参阅仓库的 git-workflow 规则），避免 .venv 和其他构建产物遗留。

轮询工作流

打开 PR 后，将 PR 编号和当前 head SHA 记录到会话记忆中。如果 isDraft 为 true， 则判断 PR 是否可供审核：

• 如果可以审核，在轮询前运行 gh pr ready "$PR"。
• 如果无法审核，评论或报告维护为何尚无法继续，然后停止，不要合并。

然后循环，直到成功、需要修复、需要升级处理、超时或合并。

收集状态的命令：

gh pr view "$PR" --json \
  number,title,isDraft,headRefName,headRefOid,baseRefName,mergeStateStatus,reviewDecision,statusCheckRollup,labels

gh pr checks "$PR" --json name,state,bucket,link,startedAt,completedAt,workflow

审核完成门槛：

• CI 成功后不要立即合并。

• 继续轮询，直到预期的 Codex/Bot 审核信号以 PR 审核、审核评论、问题评论、问题回应或其他仓库标准的机器人审核记录形式出现。

• Codex 审核状态由 PR 问题中 chatgpt-codex-connector[bot] 的回应表示：

  • eyes 回应：审核正在进行——继续轮询，暂不合并。
  • +1 回应：审核已完成且无问题——如果没有阻塞性审核评论，则视为机器人已完成无问题审核。

• Codex 发现会作为行内拉取请求审核评论发布，而不是问题级评论。gh pr view --comments 不会返回行内审核评论。请务必使用拉取请求审核评论端点单独获取。GitHub 列表端点会分页；务必传入 --paginate 和 per_page=100，以免遗漏后续页上的评论：

  gh api --paginate "repos/{OWNER}/{REPO}/pulls/$PR/comments?per_page=100" \
    --jq '[.[] | select(.user.login == "chatgpt-codex-connector[bot]") | {id, path, line, body: .body[:300]}]'
  

• 含有 P1 或 P2 标记的 Codex 行内评论属于阻塞性发现。无论是否有 +1 回应，任何未解决的 P1/P2 行内评论都应视为“审核存在阻塞性发现”。

• 如果 CI 通过，但尚无审核、评论或回应，则继续等待，直到达到 20 分钟的轮询超时。

• 只有在存在机器人审核记录且其中没有阻塞性发现时，才将审核视为无问题。

• 如果 20 分钟内没有出现机器人审核记录，请用日语在 PR 中评论，说明 CI 已通过，但审核未能在轮询时限内完成，然后停止，不要合并。

收集无问题回应状态的命令：

gh api --paginate "repos/{OWNER}/{REPO}/issues/$PR/reactions?per_page=100"

对于其他任何针对 GitHub 列表端点的 gh api 调用，除非已知该端点只返回单个资源，否则请使用 --paginate 和 per_page=100。不要仅根据第一页的响应推断“没有审核记录”或“没有阻塞性发现”。

对于失败的 CI 任务，使用 gh 获取失败日志：

gh run view "$RUN_ID" --log-failed

当 gh pr view 无法提供足够信息时，使用 gh api 获取审核评论和审核线程。限制 GitHub API 响应的大小，并在推理前概述较长的日志。

修复规则

当 CI 失败或审核评论要求修改时：

1. 阅读失败日志和审核评论。
2. 判断每项发现是否成立。
3. 在现有 PR 工作树中应用最小且完整的修复。
4. 推送前运行仓库的常规验证，包括适用的测试、Ruff 和 mypy。
5. 提交并推送修复。
6. 用日语回复每条审核评论。

回复格式：

対応しました。

- 修正内容: ...
- 修正commit: ...
- 検証: `...` passed

如果不针对某条评论修改代码：

この指摘は対応不要と判断しました。

- 理由: ...
- 確認内容: ...

升级规则

出现以下任一情况时，停止自动修复并升级处理：

• 第 4 次修复尝试仍未通过 CI 或解决审查问题。
• 修复后，同一职责边界内再次出现审查评论。
• 修复需要更改工作流／权限／密钥。
• 修复需要直接推送到 main／默认分支或重写历史记录。
• 修复需要进行大规模设计更改，而非局部修复。

自动修复允许的操作：

• 应用代码更改
• 测试
• 文档
• 数据库迁移
• 依赖项和锁文件更新

自动修复不允许的操作：

• 更改 .github/workflows/**
• 更改 GitHub Actions 权限
• 更改密钥或环境配置
• 直接推送到 main／默认分支
• 重写 Git 历史记录
• 大规模重写设计

升级处理时：

1. 如有可用标签，为 PR 添加设计／升级标签。
2. 创建 GitHub issue，说明设计问题和可选方案。
3. 使用日语在 PR 中发表评论，附上 issue 链接、概要、可选方案，以及需要用户决定的事项。
4. 停止操作，不要合并。

合并规则

合并前，确认：

• PR 不是草稿。
• PR 创建后的后置条件已确认 isDraft == false；如果 PR 仍为草稿，不要运行 gh pr merge --auto。
• Head SHA 与最后检查的 SHA 一致。
• 必需检查均已成功。
• 机器人审查已完成，且没有阻止合并的问题。
• PR 审查评论／普通评论或 PR issue reactions 中包含预期的机器人审查记录。
• 修复循环次数低于升级阈值。
• PR 不处于升级状态。

然后运行：

gh pr merge "$PR" --squash --auto --delete-branch --match-head-commit "$HEAD_SHA"

GitHub 报告 PR 已合并后，切换到共享检出目录（项目根目录），并移除已合并的 worktree。如果仓库定义了清理自动化目标（例如 make worktree-cleanup-merged），请使用该目标；否则直接移除 worktree：

cd "$PROJECT_ROOT"
git worktree remove "$WORKTREE_PATH"

不要遗留已合并的 worktree 或其 .venv。

状态

在会话记忆中保留循环次数、最新检查的 head SHA 和审查生成情况。暂时不要添加持久化状态。如果会话丢失，请停止操作；用户会提供新的指示。

参考资料

• 仓库的 PR 维护 ADR／政策文档（如果存在，例如位于 docs/decisions/ 下）
• AGENTS.md／CLAUDE.md（如果存在）