PR 整理 是做什么的?
对分支进行一致性清扫,是在其成为拉取请求之前。它查看差异更改了什么,然后查看差异本应更改的所有内容。
只处理分支自身的更改。除非差异使其错误,否则保留仓库中其他地方的未触及债务不变。
0. 范围
-
首先阅读仓库的说明:
AGENTS.md、CLAUDE.md、CONTRIBUTING*、README*,以及它们指向的任何文档。 -
找到基础分支和差异:
base=$(git merge-base origin/main HEAD) # 或仓库的默认分支 git log --oneline "$base"..HEAD git diff --stat "$base"...HEAD git diff --name-only "$base"...HEAD -
检查工作树(
git status)。保留未提交的更改。如果您要做的编辑与它们重叠,请停止并询问。 -
如果您在默认分支上且没有可比较的内容,请停止并说明。
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、验证器或检查脚本:
- 已接入。 找到仓库使用的每个入口点:
.pre-commit-config.yaml、.github/workflows/*、Makefile、justfile、noxfile.py、tox.ini、pyproject.toml或package.json脚本,以及任何调用其他检查的验证器。确认检查器至少从一个入口点被调用。如果没有,以与其同类相同的方式接入它,或标记它。 - 在错误输入上失败。 在有意的错误输入上运行它;它必须以非零退出。
- 在无输入上失败。 在空或缺失输入(无文件、无匹配、无解析内容)上运行它;它必须以非零退出或清楚说明它检查了无内容,绝不能静默通过。
- 有一个测试 涵盖 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. 用证据验证
没有来自本次会话的最新证据,没有声明:
- 命名证明该声明的命令。
- 完整运行它。
- 读取整个输出和退出代码。
- 用该证据陈述结果,或陈述实际状态。
运行仓库已有的内容:其测试、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。