Community编程与开发github.com

证据审查

对任何代码进行深入、基于证据的审查——包括整个项目(无差异对比)、特定路径、未提交的更改、分支或 GitHub PR / GitLab MR。能够复现发现而非猜测,像严格的维护者一样判断层次选择与复用,并编写包含ID、严重性、状态和验证的结构化报告。

证据审查 是什么?

该技能为AI代理提供一种严谨、可复现的代码审查方法,深度超过简单检查。它指导代理对代码进行全面的‘项目审计’,涵盖整个工作树或变更集,通过运行构建和测试、重现可疑发现来验证问题,并生成包含ID、严重性(严重、高、中、低)和清晰状态的结构化报告。该技能模拟‘严格维护者’的思维方式,重点评估变更是否属于正确的抽象层次,指向现有的辅助函数或扩展点,在所有调用视为安全之前追踪共享状态的每个读取者,并在任何依赖确立前明确约定。它支持多种作用域:无参数(整个仓库)、路径、差异、分支、GitHub PR和GitLab MR,并为大型代码库提供智能分区和子代理协作。该技能内置安全指导,包括安全执行未知代码、保护工作目录的完整性、避免生产环境,并优先发现真实、可复现证据的发现,而非推测性反馈。它适用于Claude Code和Cursor等AI编码代理,并提供可实施的审查规则。

兼容平台✓Claude Code✓Codex CLI✓Cursor
npx skills add https://github.com/avi-dev-user/evidence-review/tree/HEAD

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

在你喜欢的 AI 中提问

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

文档

证据审查 是做什么的?

你正在执行一位高级工程师在对其交付的内容负责时会进行的审查:他们会通读范围内的内容,运行相关工具,重现其怀疑的问题,并坦率说明无法检查的部分。两条标准定义了标杆:

  • 项目审计。 全面阅读范围内的代码,运行构建和测试,通过一次性脚本重现每个严重发现,使用清晰的严重性等级,状态会随着修复的落地而更新,以及一个诚实的“哪些部分状态良好”部分。
  • 严格维护者。 首先询问此更改是否属于该层次,通过文件和行号指向现有的辅助函数或扩展点,在将某些操作称为安全之前追踪共享状态的每个读取者,区分阻塞性和非阻塞性问题,并在任何依赖确立之前明确约定。

深度来自证据,而非数量。一份每项发现都真实存在的简短报告,胜过一份为了看起来全面而填充的长篇报告。

1. 解析作用域

给定的参数:"$ARGUMENTS"(空引号表示无参数)。如果这仍然像字面意义上的占位符,那么你的代理未替换参数:请改为从用户的请求中获取它们。

参数作用域模式输出
无整个仓库,当前工作树状态project报告文件
路径该路径的完整内容,外加其调用的定义(深度一级)project报告文件
diff暂存 + 未暂存的更改:git diff HEADchange聊天内
branch [base]git diff <base>...HEAD(三个点:从合并基点开始计算差异)change聊天内
pr <n|url>PR/MR 头部与其目标分支的对比change聊天内
--update <file>重新验证现有报告;仅限 project 模式,可带路径或不带update编辑该文件
  • branch 的基础分支:git symbolic-ref --short refs/remotes/origin/HEAD;如果失败,则使用 main,然后是 master;如果两者都不存在,则是一个开放性问题(第2节)。
  • project 模式下的脏工作树: 按原样审查工作树,并将 HEAD <sha> + 未提交更改 记录为修订版本。修改过的文件使用 path:line,而不是固定的链接。
  • 无参数且工作树脏污: 这是一个开放性问题(project 模式还是 diff 模式?)。
  • 单仓库: 对于路径,运行拥有它的包的命令(最近的 package.json / pyproject.toml / go.mod / Cargo.toml / *.csproj),并从仓库根目录向下到该包读取规则文件。

change 模式仍会审查周围代码。 审查的单位是更改的代码块 加上 它们所在的完整函数、每个被更改符号的调用者、更改所触及状态的每个读写者、覆盖这些更改的测试以及描述它们的文档。孤立地阅读差异正是代价高昂的错误得以通过审查的原因。

获取 PR 或 MR

绝不要检出覆盖用户的工作树。始终在一个独立的临时位置使用单独的工作树:

  • GitHub:git fetch origin pull/<n>/head:pr-<n>;GitLab:git fetch origin merge-requests/<n>/head:mr-<n>。然后执行 git worktree add <scratch>/pr-<n> pr-<n>。
  • 元数据:gh pr view <n> --json title,body,comments,reviews,baseRefName,headRefName 或 glab mr view <n> --comments。如果任一 CLI 不可用或未登录,则仅审查差异,并在标题中说明未读取讨论历史。
  • 为了运行基础分支以进行比较(第4节),在合并基点处添加第二个工作树。绝不要在头部工作树之间来回切换。
  • 在最后移除工作树(git worktree remove)。

2. 上下文,以及一轮提问

收集以下信息,并保留在报告头部:

  • 修订版本(完整 SHA)、分支、远程仓库 URL。如果没有远程仓库,则跳过本条的其余内容,使用 path:line。否则先运行 git fetch --quiet,然后运行 git branch -r --contains <sha>;如果获取失败,则将 SHA 视为未推送。仅当 SHA 已推送且主机为 GitHub 或 GitLab 时,链接才固定到该 SHA(将 SSH 远程仓库转换为 https):
    • GitHub https://github.com/<o>/<r>/blob/<sha>/<path>#L<a>-L<b>
    • GitLab https://<host>/<group>/<repo>/-/blob/<sha>/<path>#L<a>-<b>
    • 其他情况:path:line。
  • 项目规则:CLAUDE.md、AGENTS.md、CONTRIBUTING.md、lint/类型配置、PR 模板以及父目录中的规则文件。发现首先依据项目自身规则判断,其次才是一般性品味。
  • 系统的用途:README、文档、部署清单、CI 配置、入口点。
  • 对于 PR:其描述、关联的问题、现有的审查评论及其解决情况、以及目标分支。阅读早期的审查轮次,以免重复提出已解决的问题,并检查请求的更改是否已实际完成。
  • 意图。 用一句话说明代码或更改正在解决什么问题。如果你无法做到,那是一个开放性问题,因为答案可能会改变其应有的实现方式。

报告语言,首个匹配项优先:用户明确请求;项目规则文件;父目录中的规则;受众(上游开源 PR 使用英语);项目现有文档的语言。如果均不适用,则是一个开放性问题。

开放性问题。 收集来自第1节和第2节的所有开放性问题(作用域、基础分支、受众、请求者希望涵盖的关注点、语言、意图),并在 一条消息中一并提问。不要询问任何你自己能找到答案的问题。如果无人能回答(非交互式运行,或用户表示不要提问),则使用以下默认值,并在报告头部的“假设”下列出每一项:无参数时使用 project 模式;受众为维护者;英语;未命名关注点;意图为 PR 描述或 README 中的说明。

请求者命名的关注点,将在报告中单独列出一个小节,无论其严重性如何。

3. 预算与分类

在逐行阅读任何内容之前,确定“范围内”的含义。

  • 排除在逐行阅读之外: 锁定文件、vendor/、node_modules/、dist//build/、生成的代码、压缩文件、二进制文件、快照、大型测试夹具、API 集合。使用 grep 或粗略浏览以查找重要内容(固定的易受攻击版本、密钥、端点列表)。
  • 统计剩余内容, 仅计数非测试源文件。如果文件超过大约40个或8000行,则将代码拆分为多个区域,并分派只读子代理,每个区域一个,以收集 候选 发现(含 file:line 和推理)。在此规模下这是必需的,而非可选:一个上下文无法阅读所有内容,沉默的粗略浏览比诚实的拆分更糟糕。每个候选都在主线程中验证(第7节)。如果你的代理没有子代理,则每轮审查一个区域,在轮次之间维护一个书面的候选列表,并在作用域中说明工作是如何拆分的。
  • 测试: 完整阅读覆盖最高风险路径的测试,以及任何发现所依赖的模拟的测试;粗略浏览其余测试以了解设置和覆盖范围,并在作用域中说明。
  • 按风险排序: 入口点和身份验证优先,然后是所有写入数据存储的操作,接着是出站调用,最后是其余部分。
  • 诚实地记录覆盖范围。 报告的作用域部分说明哪些内容被完整阅读、哪些被粗略浏览以及哪些被跳过。绝不要声称你未完成的完整阅读。

4. 基准健康

运行任何内容前的安全事项

  • 你未编写的代码(来自分支或未知贡献者的 PR,刚交给你的仓库):安装、构建和测试会执行它,包括安装钩子和测试设置。列出你打算运行的命令及其执行的内容,并先询问。如果无人能回答,则不要执行:进行静态审查,并在头部说明。
  • 检查测试的目标。 阅读测试设置和环境文件。如果测试套件会触及 localhost 之外的任何内容(共享数据库、staging API、真实队列),则不要运行它;记录原因。
  • 保持检出目录干净。 使用尊重锁定文件的命令进行安装(npm ci,pip install -r(尽可能使用哈希值),uv sync --frozen)。将构建和覆盖率输出发送到检出目录之外,或确认已通过 gitignore 忽略(测试运行器通常默认将覆盖率写入仓库:请传递输出目录,例如 jest --coverageDirectory <scratch>)。最后,git status 必须显示未发生任何由你引起的更改。
  • 绝不要针对生产或共享环境运行任何内容。生产检查应成为带确切命令的建议(例如对实时数据库的查询计划)。

要运行的内容

在 package.json 脚本 / pyproject.toml / Makefile / CI 配置中找到真实命令,然后运行并记录每个命令及其确切结果:类型检查、lint、构建、带每文件覆盖率的测试,以及生态系统的依赖审计(npm audit、pip-audit、cargo audit、govulncheck、bundle audit、dotnet list package --vulnerable;osv-scanner 作为备用方案)。审计需要网络和锁定文件;如果缺少任一,则记录下来。大多数审计工具在发现安全公告时以非零状态退出:这是一个结果,而不是失败的命令。

  • 一个没有测试、构建或 linter 的项目:记录一次“未配置任何内容”。这算作一条发现,而不是每个文件一条。
  • 仅当存在已知漏洞、已过生命周期或阻碍所需升级时,才报告过期的依赖项。
  • 无法安装的私有依赖:记录下来,对照可用的代码(已安装的副本、供应商副本)进行审查,并说明哪些库行为未经验证。

在 change 模式下,在头部运行测试套件,并在某处失败时也在基础分支(在其自己的工作树中)上运行,以便每个失败都被标记为 新增 或 预先存在。

5. 映射系统

在逐行阅读之前,为自己写下:

  • 入口点:HTTP 路由、协议处理器(WebSocket、gRPC、电话等)、CLI 命令、队列消费者、定时任务、迁移、启动。
  • 信任边界:谁可以访问每个入口点,调用者如何被认证,以及租户/用户身份的来源。
  • 数据存储、其索引,以及哪些路径读取和写入每个集合或表。
  • 出站调用:超时、TLS、重试、模糊失败的含义。
  • 中间可能失败的、需要多步骤的操作。
  • 数据的真实形状。 从 README、API 文档、测试夹具、种子数据和 API 集合中收集示例值:路径格式、日期格式、ID 格式、大小写。稍后将每个解析器和路径辅助函数对照所有这些格式运行。

在 change 模式下,改为绘制爆炸半径:使用 grep 搜索更改所触及的每个调用者和每个读取者,并附带 file:line。

6. 深度阅读

立即阅读 reviewer-lens.md。它是一个问题清单,而非配额:大多数小节对大多数文件无话可说,无话可说的小节则不写任何内容。仅报告具有具体触发场景的候选问题。

完整阅读范围内的每个文件,而非节选。包括代码所依赖的库中,在接口行为重要的部分(例如客户端库在对等方断开后的行为,框架在响应发送后处理错误的方式)。许多真实 bug 就在那里。

不要豁免好的代码。 看起来设计良好的部分也会接受与其他部分相同的机械检查:其热点查询的查询计划、通过其解析器的真实数据形状、其共享状态的读取者。看起来仔细的代码中隐藏着没人关注的 bug。

维护一个运行中的候选列表,每个包含:位置、出什么问题、具体的触发场景(触发它的输入和状态),以及你将如何证明它。

同时维护一个做得好的事项列表,并附带证据。“已验证工作正常”的声明需要与发现相同的严谨性:你检查了读取者、运行了测试、阅读了库代码。

7. 验证

对于可能为高或严重的每个候选,以及任何代价较低的候选:

  • 使用临时目录中的一次性脚本进行重现,绝不要在仓库内进行。优先在实际依赖关系的小规模上(内存或容器化数据库,在 HTTP 边界处存根的上游)重现,而不是使用被审查代码的模拟。
  • 对于性能声明,进行测量:查询计划(explain()、EXPLAIN ANALYZE)、之前和之后的计时,在能显示问题的数据规模下。
  • 对于“这是安全的”关于共享状态的声明,列出每个读取者和写入者。
  • 限制努力: 每个候选大约15分钟或5次尝试。超出后,标记它并继续,附带原因。一旦每个关键/高严重性的候选都有标签,停止重现。

为每个发现的证据标记标签:

  • yes:通过运行代码重现。
  • partly:声明的一部分已重现;该节说明是哪部分。
  • artifact:通过文件、清单、镜像层或提交显示,此处无法运行(例如缺少的部署变量、历史记录中的密钥)。
  • no:尝试过但无法重现;说明为何仍然报告,或将其删除。
  • not tried:仅基于推理。

然后要诚实:

  • 在此部署中没有合理触发条件的候选将被删除,而不是归档为低。
  • 推理保持标记为推理(“可能”、“我无法从此处检查”)。
  • 仅因模拟返回了真实代码永远不返回的值而通过的测试,是关于测试本身的发现,而不是关于代码的证据。

8. 分类

严重性,根据在此部署中的影响和可达性判断。当可达性取决于你无法检查的内容(网络 ACL、谁可以访问端口)时,按照假设可达的严重性归档,并在旁边说明什么条件下可以降低。

  • 关键:现在即可利用,后果严重。
  • 高:数据丢失、跨租户或跨用户访问、或核心功能损坏。
  • 中:一个真实的 bug 或风险,但需要特定条件。
  • 低:卫生、可维护性、文档、依赖项漂移。

对于库,根据对典型消费者的影响判断。对于单用户工具,数据丢失仍为高,安全发现需要现实的攻击者。

在 change 模式下,还需为每个发现打上标签:

  • 新:由当前更改引入。
  • 预先存在:在合并基础分支中存在。
  • 放大的:预先存在,但因当前更改而更易触发或后果更严重。

状态。每个发现都有一个演进状态:

  • 已确认:已记录,待操作。
  • 已修复:代码已更改。重新运行了构建和相关测试;复现脚本已作为测试添加。
  • 已拒绝:审查了拒绝理由,并存档该理由。
  • 无法重现:尝试过但无法复现;环境中可能不同。
  • 推迟:已记录但未立刻解决;附带表述同意的注释。

9. 编写报告

文件为一个 .md 文件,项目模式下的路径为 evidence-report-<package-or-repo-name>.md;更新模式则编辑现有文件。变更模式下的报告写入聊天。

# 证据审查:<标题>

**版本:** <full SHA> 或 <SHA + 未提交更改>
**分支:** <分支>
**当前主机:** `hostname`
**模式:** project | change | update
**语言:** …
**受众:** 维护者 | 作者 | 审阅者
**作用域:** 完整阅读 <n> 个文件,略读 <m> 个,跳过 <k> 个。覆盖范围:入口点、认证、数据存储。

### 假设

- …

### 未验证

应检查但无法检查的内容:网络访问权限、生产查询计划、不可用的私有依赖项的行为。

### 开头页面

当存在外部 PR 讨论时提供一个链接(“此报告应与 PR 讨论一并阅读”),以及一个可选的简短摘要。如果审核的是 PR,此处包含检查清单:

- [ ] 所有要求的更改已应用
- [ ] 所有审查评论已解决
- [ ] 构建通过
- [ ] 测试通过(覆盖率 <X>%)
- [ ] 所有关键/高发现已确认已修复
- [ ] 没有新的关键/高发现

### <命名关注点>(如果存在)

(任何按请求者明确名称的、单独的严重发现。)

### 良好状态

按区域。与发现相同的标准:经过验证的声明带有证据。

### 发现

FIND-001 | 高 | 新 | 已确认

位置: path/to/file.rb:42 path/to/file.rb:88(调用者)

什么出错: 当输入为 nil 时,UserFinder 返回所有用户。

场景: /api/users 端点未经认证的调用,且 params[:id] 缺失。

依据: ruby -e 'puts UserFinder.new(nil).call.count' 返回 > 0。

修复: 在传入 find 前验证参数存在。

影响: 暴露所有用户:跨租户访问。


每条发现后接以下内容:

- 修复的验证,当修复落地时(状态变为已修复)
- 或拒绝理由(状态变为已拒绝)

按严重性排序(关键优先),然后按状态排序(已确认优先于已修复)。

### 检查清单总结

| ID | 位置 | 严重性 | 标签 | 状态 | 描述 |
|---|---|---|---|---|---|
| FIND-001 | file:42 | 高 | 新 | 已确认 | 认证绕过 |
| … |

**关键:** <n> | **高:** <n> | **中:** <n> | **低:** <n>

**新增:** <n> | **预先存在:** <n> | **放大的:** <n>

**已确认:** <n> | **已修复:** <n> | **已拒绝:** <n> | **无法重现:** <n> | **推迟:** <n>

结束

  • 下次审查备注: 指向任何更改后药丸。
  • 未解决职责: 指向需要操作的事项。
  • 签名: 审查由 <agent> 使用证据审查标准执行

10. 迭代和更新

当报告通过 --update 定位时:

  1. 重新读取范围内的文件(如果给定新路径,则重新读取该路径)。
  2. 重新运行构建和测试。
  3. 检查每个列为已确认的发现。那些不再触发、代码已更改的:标为已修复,如果适用则添加测试。那些仍然触发的:将其立足点移到新的行号并更新状态。
  4. 检查针对相似风险领域的新发现。这些作为新的 FIND-NNN 插入。
  5. 更新检查清单、统计信息和版本。

不要从报告中删除已修复的发现——它记录了已解决的问题。将其标为已修复,必要时添加注释。

在 PR 的整个生命周期中,该报告作为一个权威的(但可变的事实来源)存在。变更模式下的通信是快照式的,但如果需要,用户可能会要求重新验证特定发现。

相关技能