关于 honest-review
用于审查会话改动、指定路径、拉取请求、提交范围或完整代码库的研究驱动型代码审查 Skill。它以证据验证问题、评定严重性与置信度,并在修复前要求批准。
主要功能
- 01四阶段分流与审查流程
- 02外部证据验证
- 03严重性与置信度评分
- 04多种审查视角
- 05修复前的批准关卡
- 06输出 SARIF 和 Conventional Comments
适用场景
- 01审查当前会话中的改动
- 02审计代码库或指定路径
- 03评估拉取请求改动
- 04管理审查结果与误报记录
安装
复制下面的命令,在终端中运行。
npx skills add https:/ / github.com/ wyattowalsh/ agents --skill honest-review安装后在 Claude Code 中输入/honest-review确认已加载。
包含的文件
除 SKILL.md 外,安装时一起下载的参考资料和脚本。
evals/agentic-verification.jsonapproval-gate.jsonauto-fix-dry-run.jsonconventional-comments.jsondegraded-mode.jsondependency-context.jsondiff-mode.jsonempty-no-diff-menu.jsonfinding-quality-validation.jsonfull-codebase-audit.jsongit-range-review.jsonhealthy-codebase.jsonhistory-mode.jsonlearnings-loop.jsonmonorepo-review.jsonmulti-pass-review.jsonpost-review-fix-pass.jsonpr-review.jsonreasoning-chain.jsonreasoning-first-output.jsonscoped-review.jsonself-verification.jsonsession-review-changes.jsonsession-review.jsonreferences/auto-fix-protocol.mdchecklists.mdci-integration.mdconventional-comments.mddependency-context.mdjudge-protocol.md详细介绍
诚实审查
以研究为驱动的代码审查。每项发现都经过证据验证。 4 波流程:分诊 → 分析 → 研究 → 评判。
范围: 以代码审查和审计为先。不得用于功能开发、一般性说明或基准测试。只有在选定发现通过审批关卡后,才允许规划或执行审查后的修复。
规范术语
在两种模式中始终准确使用以下术语:
| 术语 | 定义 |
|---|---|
| 分诊 | Wave 0:对文件进行风险分级(HIGH/MEDIUM/LOW),并在分析前确定专家触发条件 |
| 阶段 | 一个流水线阶段:Wave 0(分诊)、Wave 1(分析)、Wave 2(研究)、Wave 3(裁定) |
| 发现项 | 一项独立的代码问题,包含严重性、置信度分数、证据和引用 |
| 置信度 | 每项发现的分数为 0.0-1.0;>=0.7 则报告,0.3-0.7 则标记为未确认,<0.3 则丢弃(P0/S0 除外) |
| 严重性 | 对发现项影响的优先级(P0-P3)和范围(S0-S3)进行分类 |
| 裁定 | Wave 3 协调:规范化、聚类、去重、筛选、解决冲突并排列发现项优先级 |
| 视角 | 一种创造性的审查视角:反转、删除、新手、事件、演进、对手、合规、依赖、成本、可持续性 |
| 影响范围 | 发现项中的缺陷可能影响多少文件、用户或系统 |
| 虚构依赖包名攻击 | AI 幻觉生成的依赖包名称——安全关键问题,在 Wave 2 中优先检查 |
| 研究验证 | 核心差异化优势:使用外部证据(Context7、WebSearch、DeepWiki、gh)确认每一项非平凡发现。证据分为两类:事实证据(Grep),用于代码复用/简化类发现;假设证据(外部研究),用于正确性、安全性和非显而易见的设计类发现。 |
| 系统性发现 | 出现在 3 个或更多文件中的模式,在裁定协调期间从个别发现项提升而来 |
| 审批关卡 | 呈现发现项后的强制暂停——未经用户同意,绝不实施修复 |
| 轮次 | 内部队友阶段(轮次 A:扫描,轮次 B:深入分析,轮次 C:研究)——与流水线阶段不同 |
| 自我验证 | Wave 3.5:对重点发现项进行对抗式审查,以减少误报(references/self-verification.md) |
| 约定感知 | 检查 AGENTS.md/CLAUDE.md/.cursorrules——依据项目自身的 Agent 指令进行审查 |
| 代码复用发现 | 新编写的代码重复了现有功能;必须引用现有实现的文件:行号。 |
| 事实证据 | 确认代码库中存在/不存在 X 的 Grep 结果。足以支持代码复用/简化类发现——无需外部研究。 |
| 假设证据 | 确认某种模式有害的外部研究(WebSearch、Context7)。正确性、安全性和非显而易见的设计类发现必须提供此类证据。 |
| 降级模式 | 研究工具不可用时的运行模式——根据工具应用置信度上限 |
| 审查深度 | honest-review 始终以最大深度运行——涵盖所有视角、进行完整研究验证并使用完整团队;团队组成会根据内容自适应(文件类型决定专家选择)。 |
| 推理链 | 必须在发现项陈述之前解释原因。可减少误报。 |
| 引用锚点 | [file:start-end] 引用,将发现项关联到特定源代码行。经过机械验证。 |
| 约定式评论 | 结构化 PR 输出标签:赞扬/吹毛求疵/建议/问题/待办/疑问/想法,并附带(阻塞)/(非阻塞)标记。 |
| 依赖关系图 | 在 Wave 0 分诊期间构建的导入/导出映射。用于判断影响范围和跨文件影响。 |
| 经验记录 | 用于抑制未来类似发现项的已存储误报驳回记录。按项目限定。 |
分派
| $ARGUMENTS | 模式 |
|---|---|
| 空参数 + 会话中有更改(git diff) | 审查会话中更改的文件 |
| 空参数 + 没有更改 | 显示模式菜单;完整代码库审计必须明确指定 audit |
| 文件或目录路径 | 对指定路径进行范围审查 |
| "audit" | 强制执行完整代码库审计 |
| PR 编号/URL | 审查 PR 更改(gh pr diff) |
| Git 范围(HEAD~3..HEAD) | 审查该范围内的更改 |
| "history" [project] | 显示项目的审查历史 |
| "diff" 或 "delta" [project] | 比较当前审查与上一次审查 |
--format sarif(适用于任何模式) | 以 SARIF v2.1 格式输出发现项(references/sarif-output.md) |
| "learnings" [command] | 管理误报经验(add/list/clear) |
--format conventional(适用于任何模式) | 以 Conventional Comments 格式输出发现项 |
| "fix" / "apply" 已批准的发现项 | 审查后修复流程,参见 references/auto-fix-protocol.md |
| 无法识别的输入 | 请求澄清 |
自动检测启发式规则
如果未提供明确的模式关键词:
- 空参数 +
git diff --name-only HEAD中存在已更改文件 -> 会话审查 - 空参数 + 没有已更改文件 -> 显示模式菜单;未明确指定
audit时,不要启动完整审计 - 已存在的文件或目录路径 -> 范围审查
- PR 编号/URL -> PR 审查;Git 范围(
HEAD~3..HEAD)-> 范围审查 --format sarif或--format conventional会修改所选审查模式;它们本身不会选择审查范围- 一般性研究、策略讨论、解释、基准测试或纯粹的简化请求 -> 转至相应的技能,或在继续前先询问
- 目标不明确或缺失 -> 在分诊前请求澄清
审查立场
按项目类型校准严重程度:
- 原型:仅报告 P0/S0。跳过风格、结构和优化方面的问题。
- 生产项目:对所有级别和严重程度进行完整审查。
- 库:进行完整审查,并重点关注公共 API 表面的向后兼容性。
按置信度校准报告: 每项发现都包含一个置信度分数(0.0-1.0)。置信度 ≥ 0.7:报告。 置信度 0.3-0.7:标记为“未经确认”后报告。置信度 < 0.3:舍弃(P0/S0 除外)。 评分标准:references/research-playbook.md § Confidence Scoring Rubric。
肯定优势: 指出设计良好的模式、简洁的抽象和周到的设计。 每个审查范围至少指出一项优势。优势说明属于报告内容,不属于缺陷发现,也无需修复。
正面与建设性内容的比例: 目标比例为 3:1。避免报告一味负面。如果比例偏向负面, 请重新评估是否值得报告低严重程度的发现。 例外:存在 3 项或更多 P0/P1 发现时,报告所有关键发现,不要为了满足比例而减少它们——绝不会为了平衡而压下关键问题。
尊重惯例的立场: 按照代码库自身的标准进行审查,而非理想化标准。
肯定健康的代码库: 如果没有 P0/P1 或 S0 发现,请明确说明这一点。简短的报告也可以是好的报告。
扩展约定
- 范围较小的审查仍使用完整的内容自适应审查者集合;只有分诊深度会降低。
- 会话审查和完整审计共用一条核心扩展规则:最大审查深度、内容自适应审查者,且不采用仅内联审查的捷径。
- 大型全代码库审计可以按领域或风险级别划分职责,但这不会削弱证据验证要求,也不会改变以推理为先的输出约定。
- 只读审查的输出仅限于发现的问题、优点和后续步骤建议。只有在获得明确批准并单独进行修复后,才会提供实施总结。
审查级别(两种模式均适用)
三个抽象层级,每个层级都会检查缺陷和不必要的复杂性:
正确性(能否正常工作?): 错误处理、边界条件、安全性、API 误用、并发、资源泄漏。 简化:虚设的错误处理、针对不可能状态的防御性检查、无效的错误处理路径。TOCTOU 反模式:操作前检查是否存在会造成竞态条件——直接执行操作并处理错误。
设计(是否构建良好?): 抽象质量、耦合、内聚、测试质量、认知复杂度。 简化:死代码、一对一包装器、仅使用一次的抽象、过度设计。字符串类型化(有常量或枚举可用时却使用原始字符串)。参数泛滥(新增参数而非重构结构)。冗余状态(重复已有状态或可由已有状态推导)。复制粘贴式变体(几乎相同但应统一的代码块)。
效率(是否经济?): 算法复杂度、N+1 问题、数据结构选择、资源使用、缓存。 简化:不必要的序列化、重复计算、过早优化。热路径臃肿(在启动路径或每请求路径上执行阻塞工作)。遗漏并发(独立操作按顺序运行)。操作范围过大(只需读取子集时却读取整个文件或集合)。无界数据结构/事件监听器泄漏。
依上下文触发的检查项(按需应用):
- 安全性:身份验证、支付、用户数据、文件 I/O、网络
- 可观测性:服务、API、长时间运行的进程
- AI 代码异味:LLM 生成的代码、不熟悉的依赖项
- 配置和机密:环境配置、凭据、.env 文件
- 弹性:分布式系统、外部依赖项、队列
- i18n 和无障碍性:面向用户的 UI、本地化内容
- 数据迁移:架构变更、数据转换
- 向后兼容性:公共 API、库、共享契约
- 基础设施即代码:云资源、容器、CI/CD、部署配置
- 需求验证:变更是否符合既定意图、PR 描述、工单 完整检查清单:阅读 references/checklists.md
创意思维视角
每个审查范围至少应用 2 种视角。对于安全敏感代码,必须使用「对抗者」视角。
- 反转:假设代码有问题——最先会出什么故障?
- 删除:移除每个单元——其他部分会察觉到吗?
- 新手:以首次贡献者的视角阅读——哪里会让你困惑?
- 事故:设想凌晨 3 点收到告警——是什么路径导致了问题?
- 演进:快进到 6 个月后的功能增长——什么会变得脆弱?
- 对抗者:攻击者会如何利用这段代码?
- 合规性:这段代码是否满足监管要求?
- 依赖项:依赖关系图是否健康?
- 成本:运行这段代码需要多少成本?
- 可持续性:能否在成本不随规模线性增长的情况下扩展?
参考:阅读 references/review-lenses.md
查找结构
每条发现都必须遵循以下顺序:
- 引用锚点:
[file:start-end]— 精确的源代码位置 - 推理链:为什么这是个问题(2-3 句话,必须写在发现内容之前)
- 发现陈述:问题是什么(1 句话)
- 证据:外部验证来源(Context7、WebSearch 等)
- 修复方案:建议的处理方法
陈述发现之前,必须先解释推理过程。 引用锚点会经过机械验证——引用的行必须存在,且包含所描述的代码。如果验证失败,请舍弃该发现。
研究验证
这是最核心的差异化所在。不要仅凭大模型的知识报告发现。对于每条非平凡的发现,都必须通过研究进行验证:
每个审查范围分为三个阶段:
- 标记阶段:分析代码并生成假设
- 验证阶段:报告之前,通过工具调用确认假设:
- 使用 Grep 搜索发现中声称的实际用法模式
- 阅读实际文件,确认引用的行及上下文
- 检查测试文件是否覆盖了被标记的代码路径
- 如果代码与假设不符,立即舍弃该发现
- 确认阶段:启动研究子 Agent,提供证据以确认:
- Context7:库文档,用于验证 API 是否正确
- WebSearch(Brave、DuckDuckGo、Exa):最佳实践、安全公告
- DeepWiki:了解不熟悉的仓库架构和设计模式
- WebFetch:包注册表(npm、PyPI、crates.io)
- gh:未解决的问题、安全公告
- 根据置信度评分标准为每条发现分配置信度分数(0.0-1.0)
- 仅报告有证据支持的发现,并注明来源。
两类证据: 事实证据——Grep 确认代码库中存在或不存在 X;对于复用和简化类发现,这已足够。假设证据——通过外部研究确认某种模式有害;对于正确性、安全性和不明显的设计问题,这是必需的。如有疑问:如果仅凭阅读代码库就能完全证实或推翻该发现,事实证据便已足够。
研究操作指南:阅读 references/research-playbook.md
模式 1:会话审查
会话步骤 1:分流(第 0 波)
运行 git diff --name-only HEAD,记录变更。收集 git diff HEAD 作为上下文。
从会话历史中确定任务意图。
检测约定文件(AGENTS.md、CLAUDE.md、.cursorrules)——参阅 references/triage-protocol.md。
对于 6 个或更多文件:按照 references/triage-protocol.md 进行分流:
- 运行
uv run python skills/honest-review/scripts/project-scanner.py [path]获取项目概况 - 分析 Git 历史(热点文件、近期变更、相关问题)
- 按风险对所有变更文件分级(高/中/低)
- 确定专业审查触发条件(安全性、可观测性、需求)
- 检测单体仓库工作区,并为每个包指定审查人员
对于 1-5 个文件:进行轻量分流——划分风险等级并检测内容类型;不要跳过完整的团队构成。(注意:始终采用最大深度的原则适用于团队投入;小型审查的分流仍可跳过 Git 历史分析步骤,以节省时间。)
会话步骤 2:扩展并启动(第 1 波)
| 范围 | 策略 |
|---|---|
| 任意范围 | 内容自适应团队(见下文)。始终采用最大深度。不使用仅行内模式。 |
内容自适应团队组成:
始终启动:
- 正确性审查员 → 第 A/B/C 轮
- 设计审查员 → 第 A/B/C 轮
- 效率审查员 → 第 A/B/C 轮
- 代码复用审查员 → 第 A/B/C 轮
- 测试质量审查员 → 第 A/B/C 轮(始终启动 — 范围取决于实际内容 — 见模板)
根据分诊内容检测结果,在触发时启动:
- 安全专家 → 存在认证/支付/加密/用户数据/外部 I/O 代码时
- 可观测性专家 → 存在服务/API/长时间运行进程代码时
- 需求验证员 → 自动检测到规范时(PR 描述、关联 issue、SPEC.md、docs/、提交消息)
- 数据迁移专家 → 存在架构变更文件时
- 前端专家 → 存在 UI/组件文件(tsx、jsx、css、vue)时
[Lead: triage (Wave 0), Judge reconciliation (Wave 3), final report]
|-- Correctness Reviewer → Passes A/B/C
|-- Design Reviewer → Passes A/B/C
|-- Efficiency Reviewer → Passes A/B/C
|-- Code Reuse Reviewer → Passes A/B/C
|-- Test Quality Reviewer → Passes A/B/C
|-- [Security Specialist if triage triggers]
|-- [Observability Specialist if triage triggers]
|-- [Requirements Validator if spec auto-detected]
|-- [Data Migration Specialist if schema changes present]
|-- [Frontend Specialist if UI/component files present]
每位审查员执行 3 轮内部审查(参见 references/team-templates.md § 内部审查轮次结构):
- 第 A 轮:快速扫描所有文件(opus,每个子 Agent 处理 3-5 个文件)
- 第 B 轮:深入检查已标记的高风险文件(opus,每个文件 1 个)
- 第 C 轮:通过研究验证发现(按 research-playbook.md 分批处理)
提示词模板:阅读 references/team-templates.md
会话步骤 3:研究验证(第 2 波)
对于小范围审查:负责人收集所有发现并派发验证波次。 对于团队审查:每位队友在内部处理验证(第 C 轮)。
按验证类型对发现进行分批。派发顺序:
- Slopsquatting 检测(安全关键,opus)
- 高风险发现(2 个以上来源,sonnet)
- 中风险发现(1 个来源,opus)
- 跳过明显的低风险问题
批次大小:每个子 Agent 处理 5-8 项发现(最佳)。参见 references/research-playbook.md § 批次优化。
会话步骤 4:评审裁决与协调(第 3 波)
执行 8 步评审裁决协议(references/judge-protocol.md):
- 规范化发现(scripts/finding-formatter.py 分配 HR-S-{seq} ID)
- 按根本原因聚类
- 在各聚类中去重
- 置信度筛选(≥0.7 则报告,0.3-0.7 则标记为未确认,<0.3 则丢弃)
- 解决相互矛盾发现之间的冲突
- 检查相互影响(修复 A 会加重 B 吗?修复 A 会一并修复 B 吗?)
- 将出现在 3 个以上文件中的模式提升为系统性发现
- 按分数排序 = 严重性权重 × 置信度 × 影响范围
如果有 2 项以上发现通过筛选,则运行自我验证(第 3.5 波):references/self-verification.md
会话步骤 5:呈现并执行
呈现所有发现及其证据、置信度分数和引用。 呈现发现后,询问:“应为哪些发现创建修复计划?[全部 / 按 ID 选择 / 跳过]” 如果获批:加载 references/auto-fix-protocol.md,并针对所选发现单独启动审查后的修复轮次。使用模式 E 生成编排实施计划。并行派发彼此独立的修复;同一文件的编辑按顺序执行。所有任务完成后进行验证(构建、测试、行为)。 输出格式:阅读 references/output-formats.md SARIF 输出:阅读 references/sarif-output.md
模式 2:完整代码库审计
审计步骤 1:分诊(第 0 波)
按照 references/triage-protocol.md 进行完整分诊:
- 使用
uv run python skills/honest-review/scripts/project-scanner.py [path]获取项目概况 - 分析 Git 历史(3 个并行的 opus 子 Agent:热点文件、近期变更、相关 issue)
- 对所有文件进行风险分级(高/中/低)
- 汇总上下文(项目类型、架构、测试覆盖率、PR 历史)
- 确定团队组成所需的专家触发条件
对于 500 个以上文件:优先检查高风险、近期修改、入口点和公共 API。 在报告中说明范围限制。
审计步骤 2:设计与启动团队(第 1 波)
使用分诊结果选择团队组成。采用与会话审查相同的内容自适应团队。 根据风险分层分配文件所有权——高风险文件由领域审查员和专家共同负责。
| 范围 | 策略 |
|---|---|
| 任意范围 | 内容自适应团队(见下文)。始终采用最大深度。不使用仅内联模式。 |
内容自适应团队组成:
始终启动:
- 正确性审查员 → 阶段 A/B/C
- 设计审查员 → 阶段 A/B/C
- 效率审查员 → 阶段 A/B/C
- 代码复用审查员 → 阶段 A/B/C
- 测试质量审查员 → 阶段 A/B/C(始终启动——范围取决于现有内容——见模板)
在分诊内容检测触发时启动:
- 安全专家 → 存在身份验证/支付/加密/用户数据/外部 I/O 代码时
- 可观测性专家 → 存在服务/API/长时间运行进程代码时
- 需求验证员 → 自动检测到规范时(PR 描述、关联问题、SPEC.md、docs/、提交消息)
- 数据迁移专家 → 存在架构变更文件时
- 前端专家 → 存在 UI/组件文件(tsx、jsx、css、vue)时
[Lead: triage (Wave 0), cross-domain analysis, Judge reconciliation (Wave 3), report]
|-- Correctness Reviewer → Passes A/B/C
|-- Design Reviewer → Passes A/B/C
|-- Efficiency Reviewer → Passes A/B/C
|-- Code Reuse Reviewer → Passes A/B/C
|-- Test Quality Reviewer → Passes A/B/C
|-- [Security Specialist if triage triggers]
|-- [Observability Specialist if triage triggers]
|-- [Requirements Validator if spec auto-detected]
|-- [Data Migration Specialist if schema changes present]
|-- [Frontend Specialist if UI/component files present]
*大型代码库的仅审计范围界定(500 个或更多文件):*核心审查员(正确性、设计、效率)按风险等级划分文件所有权;代码复用审查员的范围限定为已更改/高风险文件以及抽样的交叉部分(按扇入度和 LOC 排名最高的 50 个文件),而非整个代码库;测试质量审查员重点检查覆盖已更改/高风险代码的测试文件。负责人继续并行开展跨领域分析(审计步骤 3——不变)。500 个或更多文件的拆分规则不适用于会话审查模式(该模式始终针对范围有限的差异进行审查)。
每位队友运行 3 个内部阶段(references/team-templates.md § Internal Pass Structure)。 扩展规则:references/team-templates.md § Scaling Matrix。
审计步骤 3:跨领域分析(负责人,与第 1 波并行)
队友审查期间,负责人启动并行子 Agent,开展以下分析:
- 架构:模块边界、依赖关系图
- 数据流:端到端追踪关键路径
- 错误传播:系统各处的一致性
- 共享模式:重复代码与必要抽象
审计步骤 4:研究验证(第 2 波)
每位队友在内部处理研究验证(阶段 C)。 负责人单独验证跨领域发现。 批处理优化:references/research-playbook.md § Batch Optimization。
审计步骤 5:评判与协调(第 3 波)
收集所有队友的发现及跨领域分析结果。 运行 8 步评判协议(references/judge-protocol.md)。 跨领域去重:涉及多个领域的发现 → 提升为系统性问题。
审计步骤 6:报告
输出格式:阅读 references/output-formats.md 必需章节:严重、重要、跨领域、健康状况摘要、 三大建议、统计数据。所有发现均须包含证据和引用。
审计步骤 7:执行(如获批准)
呈现发现后,询问:“您希望我为哪些发现制定修复计划?[全部 / 按 ID 选择 / 跳过]” 如获批准:加载 references/auto-fix-protocol.md,并针对选定的发现单独启动审查后的修复阶段。使用模式 E 生成编排实施计划。并行分派彼此独立的修复;同一文件的编辑则按顺序执行。所有任务完成后进行验证(构建、测试、行为)。
状态管理
状态是可选的,仅用于保存审查历史记录或误报经验。将其保存在 ~/.{gemini|copilot|codex|claude}/honest-reviews/ 下。除非用户要求保存历史记录、比较运行结果或管理经验,否则不要在常规只读审查期间写入状态。
| 需求 | 命令 |
|---|---|
| 保存审查 JSON | `cat findings.json |
| 查看历史记录 | uv run python skills/honest-review/scripts/review-store.py list --project <slug> |
| 比较审查结果 | uv run python skills/honest-review/scripts/review-store.py diff --project <slug> --old previous --new latest |
| 检查经验 | `cat findings.json |
| 管理经验 | `uv run python skills/honest-review/scripts/learnings-store.py <add |
如果 history 或 diff 没有先前的审查记录,请报告“no stored baseline”,并继续只读操作。
参考文件
每次只加载一个参考文件。不要将所有参考文件预加载到上下文中。
| 文件 | 读取时机 | ~Tokens |
|---|---|---|
| references/triage-protocol.md | Wave 0 分类期间(两种模式) | 1500 |
| references/checklists.md | 分析期间或编写队友提示词时 | 2800 |
| references/research-playbook.md | 设置研究验证时(Wave 2) | 2200 |
| references/judge-protocol.md | Judge 仲裁期间(Wave 3) | 1200 |
| references/self-verification.md | Judge 之后(Wave 3.5)——减少对抗性误报 | 900 |
| references/auto-fix-protocol.md | 获批后实施修复时 | 800 |
| references/output-formats.md | 生成最终输出时 | 1100 |
| references/sarif-output.md | 为 CI 工具输出 SARIF 格式时 | 700 |
| references/supply-chain-security.md | 审查依赖安全性时 | 1000 |
| references/team-templates.md | 设计团队时(模式 2 或大型模式 1) | 2200 |
| references/review-lenses.md | 应用创意审查视角时 | 1600 |
| references/ci-integration.md | 在 CI 流水线中运行时 | 700 |
| references/conventional-comments.md | 生成 PR 评论或 CI 注释时 | 400 |
| references/dependency-context.md | Wave 0 分类期间进行跨文件依赖分析时 | 500 |
| 脚本 | 运行时机 |
|---|---|
skills/honest-review/scripts/project-scanner.py | Wave 0 分类——确定性项目分析 |
skills/honest-review/scripts/finding-formatter.py | Wave 3 Judge——将发现规范化为结构化 JSON(支持 --format sarif) |
skills/honest-review/scripts/review-store.py | 保存、加载、列出、比较审查历史 |
skills/honest-review/scripts/sarif-uploader.py | 将 SARIF 结果上传到 GitHub Code Scanning |
skills/honest-review/scripts/learnings-store.py | 管理误报经验(添加、检查、列出、清除) |
| 模板 | 渲染时机 |
|---|---|
| templates/dashboard.html | Judge 仲裁后——将发现结果 JSON 注入 data 标签 |
关键规则
- 绝不跳过分诊(Wave 0)——风险分类决定后续所有工作
- 每项非平凡发现都必须有研究证据,否则应予以舍弃
- 置信度 < 0.3 = 舍弃(P0/S0 除外——应标注为未确认)
- 不要对风格偏好吹毛求疵——遵循代码库的约定。例外:违反 AGENTS.md/CLAUDE.md 中 Agent 行为规则(工具链、身份验证、机密信息、安全关键指令)的情况,应作为“约定违规”层级的发现报告。绝不审查纯风格规则(格式、命名)。
- 不要报告需要不可能条件才能触发的虚构 Bug
- 发现超过 12 项时,必须重新确定优先级——5 项经验证的发现胜过 50 项推测
- 绝不跳过 Judge 协调(Wave 3)
- 实施前务必先展示方案(审批关卡)
- 实施后务必验证(构建、测试、行为)
- 绝不分配重叠的文件所有权
- 保持正面与建设性反馈的比例为 3:1——如果比例偏负面,应重新审视低严重性发现;但若存在 3 项或更多 P0/P1 发现,则应报告所有关键发现,不受比例限制。
- 肯定健康的代码库——如果没有 P0/P1 或 S0 发现,应明确说明
- 每个审查范围至少应用 2 种创造性视角——对安全敏感代码,必须使用对抗者视角
- 每次只加载一个参考文件——不要将所有参考文件预先加载到上下文中
- 根据代码库自身的约定进行审查,而非理想标准
- 当 Judge 后仍有 2 项或更多发现时,运行自我验证(Wave 3.5)——发现少于 2 项或处于完全降级模式时则跳过
- 实施修复时遵循自动修复协议——未经差异预览和用户确认,绝不应用修复
- 分诊期间检查约定文件(AGENTS.md、CLAUDE.md、.cursorrules)——依据项目声明的规则验证代码
- 每项发现都必须先给出推理链(WHY),再陈述发现内容(WHAT)
- 每项发现都必须包含引用锚点
[file:start-end],并通过机械方式对照源文件验证 - 在 Judge 第 3 波的第 4 步检查经验库——抑制与已存储的误报排除记录相匹配的发现
- 每个审查范围都必须运行代码复用审查者——始终为现有等效实现注明 file:line。
- 对代码复用和简化类发现,事实证据(Grep)已足够;除非需要确认该模式为何有害,否则无需 WebSearch。
- 不得只进行内联审查——无论文件数量多少,都必须启动完整的内容自适应团队。
- 始终启动测试质量审查者——范围内包含测试文件时,进行完整的 4 维审查;范围内不含测试文件时,搜索覆盖率缺口(用 Grep 查找覆盖已更改函数的测试;将未经测试的代码标记为发现)。
- AGENTS.md/CLAUDE.md 中 Agent 行为规则(工具链、身份验证、机密信息、安全)的违规应作为发现报告——严重性依据 checklists.md 中的“约定违规”层级确定。根据规则 4,仍不审查纯风格偏好(格式、命名)。
- 批准后的执行必须生成编排计划(模式 E)——绝不按顺序逐项应用修复;应并行处理所有相互独立的更改。