GitHub 深度审查
像 Peter 一样审查:高置信度、证据优先、代码感知,并愿意在证据不足时表示“未经证实”。目标不是生成泛泛的摘要。目标是理解错误类,尽可能找到真正的原因,在阅读足够代码后决定最佳修复方案,并指出更大的重构是否会改进设计。
开始
使用 gh,而非网页浏览,来处理 GitHub 引用:
gh issue view <n> --json number,title,state,author,body,comments,labels,updatedAt,url
gh pr view <n> --json number,title,state,author,body,comments,reviews,files,commits,statusCheckRollup,mergeStateStatus,headRefName,headRepositoryOwner,url
gh pr diff <n> --patch
对于 PR,默认收集作者上下文,除非作者是 Peter(steipete 或明显由 Peter 拥有的账户)。使用 ~/Projects/agent-scripts/skills/github-author-context/SKILL.md 中的本地工作流,并在审查顶部附近添加一个简短的 Author context: 块(当作者不是 Peter 时)。
在合并/拒绝/关闭/审查后,使用相同的作者上下文工作流添加贡献者注记,仅当交互产生持久的未来审查信号时。
对于仓库本地审查,还需检查:
git status --short --branch
git fetch origin
git log --oneline --decorate -20
rg "<key symbol/error/config/endpoint>"
如果仓库包含本地说明、Issue/PR 技能、文档列表、测试指南或维护者操作手册,请先阅读这些内容再做决定。
审查合同
始终明确回答以下问题:
- URL/引用:Issue 或 PR 编号以及受影响的表面。
- 正在修复的错误或行为是什么?
- 能否确定根本原因?如果能,在代码中的何处以及为什么。如果不能,缺少什么证据?
- 对于回归问题,是谁/什么引入的,以及何时引入的?包括可追溯有限历史的提交/PR 来源;不要猜测,而是说明未知。
- 当前/提议的修复在阅读相邻代码后是否是最佳修复?
- 更大的重构是否会提高正确性、清晰性或未来的可维护性?
- 存在哪些证据:测试、实机复现、CI 检查、文档、依赖文档/源码、已发布/当前行为。
- 哪些仍存在风险或未经证实。
代码阅读深度
阅读超越第一个触及的文件。遵循真实的调用路径:
- 入口点 -> 验证/解析 -> 路由/分发 -> 所有者模块 -> 共享助手 -> 持久化/网络/运行时边界
- 配置/模式/文档 -> 运行时使用 -> 诊断/迁移/修复路径
- 提供者/通道/插件所有者代码 -> 通用核心接口,仅在多个所有者需要时
- 围绕触及表面的测试以及相邻的回归测试
当行为依赖于依赖项时,先阅读上游文档/源码/类型或当前包契约,再做出假设。
优先使用当前源码和可执行的证据,而非 Issue 评论。将过时的评论、旧的 CI 和旧版本发布行为视为提示,直到重新验证。
来源追溯
对于错误/回归审查,在可行时包含一个紧凑的 Provenance: 答案:
- 使用
git log -S/-G、git blame、关联的 PR/Issue 和测试。 - 当作者、提交者/合并者以及当前 PR 作者不同时,分别说明。
- 表述为
introduced by(由...引入)、made visible by(由...显现)或carried forward by(由...延续)。 - 包含置信度:
clear(明确)、likely(可能)或unknown(未知)。 - 对于功能、文档、重构或不可追溯的错误,写
N/A或说明缺少什么证据。
修复质量标准
好的修复通常:
- 位于错误所属的所有权边界处
- 保留公共/向后兼容的行为,除非 Issue 是关于废弃该行为
- 在最小的有意义接口处添加回归测试
- 避免广泛的特殊情况、隐藏的迁移、语义化的标记以及在通用核心中引入提供者/通道 ID
- 当用户可见的行为发生变化时,更新文档/变更日志
- 在运行时路径中明确失败,并通过诊断/迁移路径进行修复(如果这是已建立的契约)
当修复仅仅是症状级别时,请指出。如果稍微大一点的重构能使不变量更明显并减少未来错误,则推荐它。如果重构增加了风险而没有改善错误类别,请说明。
PR 审查格式
审查 PR 时以发现点开头。发现点需要文件/行/符号引用以及具体的失败模式。避免模糊的“考虑”评论。
如果没有阻塞性问题:
- 说明未发现阻塞的正确性问题
- 列出已检查的最有力的证据
- 指出残留风险/测试缺口
- 回答设计是否是目前最佳的形式
除非用户要求该操作,否则不要批准、评论、关闭、合并、推送或提交。
Issue 审查格式
对于错误/Issue:
- 重建报告者的场景和受影响的版本/表面。
- 检查当前
main是否已经修复了它。 - 在可行时复现或创建最小的本地/实机证据。
- 如果明确,确定根本原因和建议的修复方案。
- 如果在
main上已解决,仅在用户要求时评论/关闭;包括证据以及已知的规范提交/PR。
如果无法复现,请准确说明什么阻碍了它,以及什么证据能使决策可靠。
输出模板
当用户询问“这是关于什么的”、“这是最佳修复吗”或“我们修复了什么”时,使用以下格式:
Ref: #123 / PR #456
Surface: <runtime/CLI/provider/channel/docs>
Bug: <一两句话>
Cause: <代码路径 + 置信度>
Provenance: <由提交/PR/日期引入/显现/延续,或 N/A/未知>
Best fix: <应该改变什么以及为什么>
Refactor: <是/否,具体形式>
Proof: <测试/实机/CI/源码/依赖文档>
Risk: <剩余不确定性>
保持简洁,但不要跳过原因/修复/重构/证据的决策。