Community编程与开发github.com

PR 整理

在开启或更新拉取请求前、重构、重命名、移除或设计变更后,或当被要求整理、清理分支时使用。它发现差异遗留的痕迹——过时的引用和旧设计的措辞、没有测试或文档的新行为、未接入验证器或 CI 的检查器或静默通过的检查器、与来源不再匹配的数字或示例,以及即将提交的个人信息或凭证——修复事实性错误,标记其余问题,并附上证据报告两者。

PR 整理 是什么?

PR 整理(PR tidy)是一个 AI 技能,用于在分支变为拉取请求之前对其进行一致性清扫。它专注于检查差异所更改的内容,然后查找差异本应更改的所有其他内容。该技能从分析仓库指令文件(如 AGENTS.md、CLAUDE.md、CONTRIBUTING*、README*)开始,使用 Git 来确定基础分支和差异,并对更改进行分类(新增、变更、删除/重命名、基础设施)。其主要能力包括查找和修复过时的引用、为新增/变更行为提供测试和文档、确保检查器正确失败、验证数字和示例、检测个人信息和凭证,并根据修复或标记准则进行最小化编辑。它验证所有声明并生成详细报告。该技能支持任何基于 Git 的工作流,其机械层可以部分自动化,使用 pre-commit 钩子进行文件卫生、代码拼写检查、密钥检测等任务。

兼容平台✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/chiuhoward/skills/tree/HEAD/pr-tidy

Installed? Explore more 编程与开发 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

PR 整理 是做什么的?

对分支进行一致性清扫,是在其成为拉取请求之前。它查看差异更改了什么,然后查看差异本应更改的所有内容。

只处理分支自身的更改。除非差异使其错误,否则保留仓库中其他地方的未触及债务不变。

0. 范围

  1. 首先阅读仓库的说明:AGENTS.md、CLAUDE.md、CONTRIBUTING*、README*,以及它们指向的任何文档。

  2. 找到基础分支和差异:

    base=$(git merge-base origin/main HEAD)   # 或仓库的默认分支
    git log --oneline "$base"..HEAD
    git diff --stat "$base"...HEAD
    git diff --name-only "$base"...HEAD
    
  3. 检查工作树(git status)。保留未提交的更改。如果您要做的编辑与它们重叠,请停止并询问。

  4. 如果您在默认分支上且没有可比较的内容,请停止并说明。

1. 分类差异

将更改分类为:

  • 新增: 文件、命令、函数、选项、标志、配置键、环境变量、脚本、技能。
  • 变更: 行为、默认值、API、签名、规则和设计:现在说法不同的指南或规范。
  • 删除或重命名: 任何被删除、重命名、移动或替换的内容。
  • 基础设施: 构建、CI、测试、工具。

根据此列出表面:读者或其他文件可能引用的每个名称、路径、标志、选项、术语和规则。对于设计变更,也列出旧想法的关键短语,而不仅仅是其名称(一个已删除的“每级检查”可能仍被描述为“每个级别下的检查”)。

2. 过时的引用

对于每个被删除、重命名或重新设计的项,搜索整个仓库,而不仅仅是更改的文件:

git grep -n -w "old_name"          # 名称、路径、标志
git grep -n -i "旧设计中的短语"

在代码、注释、测试、文档、README、示例、笔记本、模板、技能文件、图表(Mermaid 和 ASCII)以及配置中查找。每个命中要么被更新,要么附有原因被标记。

然后为每个新增或变更的项构建一个覆盖图:它在哪里有文档?

覆盖图:
  item              参考       如何做   示例   说明
  --new-flag        README     -        -       -
  check_levels.py   scripts/   -        -       -

没有覆盖的项就是一个缺口;报告它。除非被要求,否则不要编写完整的新文档页面。

3. 新行为的测试和文档

对于每个新增或变更的行为:

  • 一个测试 执行它,在所属的层上,以及它更改的失败路径。优先使用仓库现有的测试模式和能够捕捉回归的最窄测试。
  • 文档 在描述旧行为的任何地方描述它:参考、示例以及任何教授旧方式的指南。
  • 只有当你能够命名它具体会捕捉到的失败时,才报告缺少测试。跳过猜测和未触及的覆盖债务。

4. 检查器要大声失败

对于每个新增或变更的检查器、linter、验证器或检查脚本:

  1. 已接入。 找到仓库使用的每个入口点:.pre-commit-config.yaml、.github/workflows/*、Makefile、justfile、noxfile.py、tox.ini、pyproject.toml 或 package.json 脚本,以及任何调用其他检查的验证器。确认检查器至少从一个入口点被调用。如果没有,以与其同类相同的方式接入它,或标记它。
  2. 在错误输入上失败。 在有意的错误输入上运行它;它必须以非零退出。
  3. 在无输入上失败。 在空或缺失输入(无文件、无匹配、无解析内容)上运行它;它必须以非零退出或清楚说明它检查了无内容,绝不能静默通过。
  4. 有一个测试 涵盖 2 和 3。

为了以后保持这一点,添加一个接入测试,例如 references/test_checkers_wired.py。

5. 数字、版本和示例

列出差异触及的文件或描述它们的文档中的每个数字、版本、日期、URL、引用、命令和代码示例。对于每个:

  • 命名其来源: 产生它的代码或命令、配置值、数据集或带有确切版本的论文(arXiv v3、DOI)。
  • 重新检查它: 重新运行命令或重新读取来源。修复它,或者如果你无法检查则标记它。
  • 保持其条件: 数字成立的数据集、设置、机器或时间(“机器 M 上 T 小时内的 N 个点”,而不是“N 个点”)。
  • 将外部来源固定 到一个版本。
  • 不断变化的数字最好由代码生成(例如使用 cog,由 cog --check 检查),而不是手动输入;建议这样做。

6. 个人信息和凭证

检查分支添加的所有内容,以及即将添加的每个未跟踪文件,在它们离开机器之前。这是阻塞性的:下面的任何内容都不能通过“继续前进”来“修复”。

git diff "$base"...HEAD          # 已在分支上提交
git diff; git diff --cached      # 尚未提交
git status --short               # 可能被添加的未跟踪文件

查找:

  • 凭证: API 密钥、令牌、密码、带有密码的连接字符串、私钥(-----BEGIN … PRIVATE KEY-----)、云和 CI 密钥、会话 cookie。
  • 包含它们的文件: .env*、*.pem、*.key、id_rsa*、credentials*、secrets*、*.p12、服务账户 JSON、带有令牌的 .npmrc 或 .pypirc、本地设置文件。
  • 个人信息: 电子邮件地址、电话号码、家庭或邮寄地址、示例或测试数据中的真实姓名、账户或 ID 号码,以及关于其他人的可识别数据。
  • 机器细节: 绝对 home 路径(/Users/<name>、/home/<name>、C:\Users\<name>)、内部主机名、私有 IP 地址、日志或笔记本输出中的用户名。
  • 隐藏位置: 笔记本输出和元数据、日志、截图、夹具、生成的报告、提交消息,以及分支的完整历史,而不仅仅是其最终状态。

如果仓库有扫描器,运行它(gitleaks、detect-secrets、pre-commit run --all-files),并自己阅读差异;扫描器会漏掉个人数据。

当发现问题时:

  • 切勿在报告或提交消息中重复该值。 命名文件名、行号和项的类型(AWS 密钥、电子邮件地址)。
  • 尚未提交: 删除它,将其移动到被忽略的文件或环境变量,并如果是文件,将模式添加到 .gitignore。
  • 已在分支上提交: 停止并告知用户。曾经提交过的凭证即使重写历史后也必须撤销并替换,因为它可能已经被复制。不要重写共享历史而不告知用户。
  • 用户有意放置的个人信息(例如他们自己的公共姓名在许可证中):询问,不要删除。

7. 修复或标记

最小化编辑,使用文件自身的语气、结构和术语。在编辑文件之前完整阅读它。

不经询问直接修复:

  • 直接源自差异的事实性修正;
  • 过时的名称、路径、计数、版本和交叉引用;
  • 将新项添加到现有表格或列表;
  • 在其同类显示模式的地方接入检查器。

标记,或更改前询问:

  • 叙述性、设计性或策略性文本,以及任何与分支明显意图矛盾的内容;
  • 删除和大量重写;
  • 安全敏感更改;
  • CHANGELOG 条目和版本号提升;
  • 其他人或团队拥有的文件;
  • 需要设计决策的新测试。

切勿: 重写或重新生成现有的变更日志条目、静默提升版本、手动编辑生成的文件(使用其生成器),或粘贴密钥或真实凭证。

8. 用证据验证

没有来自本次会话的最新证据,没有声明:

  1. 命名证明该声明的命令。
  2. 完整运行它。
  3. 读取整个输出和退出代码。
  4. 用该证据陈述结果,或陈述实际状态。

运行仓库已有的内容:其测试、linter、pre-commit run --all-files、文档构建和链接检查。未安装的工具或已关闭的服务是一个验证缺口,作为缺口报告,绝不是通过。“应该通过”和代理的“完成”不是证据。

9. 报告

范围:<base>..HEAD,N 个文件,M 次提交

阻塞性
- 路径:行 — 凭证或个人信息的类型(值未显示),以及需要做什么

变更
- 路径:行 — 什么变了,以及为什么差异需要它

已标记(未修复)
- 路径:行 — 问题,为什么未修复,建议的修复

覆盖缺口
- 项 — 它应该在哪里有文档或测试

已验证
- `command` → 结果(退出代码)

未验证
- 什么,以及原因(缺少工具、外部服务、需要决策)

机械层

第 2–6 节大部分需要判断,但其中部分可以在每次提交时运行。对于没有它的仓库,在 references/pre-commit-config.yaml 中提供入门配置:文件卫生、ruff、codespell、私钥和密钥检测(gitleaks),以及提交时的 pytest 与 diff-cover。lychee 链接检查和路径门控的 CI 更适合在工作流中,而不是在提交钩子中。

致谢

经修改,改编自 MIT 许可的技能:docs-sync 和 review-test-coverage,作者 Jakub Merta(jMerta/codex-skills);document-release 的差异分类、覆盖图和修复或标记规则,作者 Garry Tan(garrytan/gstack);以及 verification-before-completion 的证据规则,作者 Jesse Vincent(obra/superpowers)。来自 Anthropic 的 pr-review-toolkit 代理(anthropics/claude-plugins-official)的想法,而非文本。许可证:THIRD_PARTY_NOTICES.md。

相关技能