Gradle 仓库 AI 代码评审工作流审查规范、输出契约与工具链解析【免费下载链接】gradleAdaptable, fast automation for all项目地址: https://gitcode.com/gh_mirrors/gr/gradle本篇技术指南以 Gradle 仓库的.agents/code-review.md为骨架系统讲解该仓库面向人机一致的代码评审规范评审该看什么、忽略什么评审范围如何界定发现以何种path:Lstart-Lend契约格式输出以及配套的gradle-code-reviewskill 与只读 companion 脚本如何支撑整个流程。读完你将掌握一套可直接复用的、适用于 AI Agent 与人类评审者的 Gradle 代码审查实战方案。评审判断标准What to Look For / What NOT to Report仓库将评审判断力收敛在 contributing/CodeReview.md 中它是what to look for看什么与what to ignore忽略什么的唯一事实来源source of truth。该文件短小精悍明确定义了两个清单应当报告的问题What to look for正确性缺陷与逻辑错误Correctness bugs and logic errorsAPI 契约违规或误用API contract violations or misuse边界情况与错误处理缺口Edge cases and error-handling gaps安全问题Security concerns明确不报告的内容What NOT to report风格吹毛求疵、格式问题与命名约定Style nits, formatting, or naming conventions.agents/code-review.md特别强调这份判断标准适用于人类评审者和 AI 评审者 alike一视同仁。这意味着即使评审由 Agent 执行也不得偏离该清单——不因工具是 AI 而放宽正确性要求也不因是 AI 而放大对风格问题的关注。仓库在 AGENTS.md 中同样要求任何厂商的 AI coding agent 在动手前遵循 CONTRIBUTING.md 及相应主题规范如 ErrorMessages.md、JavadocStyleGuide.md、Nullability.md、Testing.md可见评审标准先行是该仓库对 agent 的基本约束。评审范围Scope一切会进入目标分支的变更.agents/code-review.md对评审范围给出了明确原则Scope: review everything that will reach the target branch — the commits since this branchs fork point, plus uncommitted and untracked changes.即评审对象是自本分支 fork 点以来的全部提交加上未提交uncommitted与未跟踪untracked的变更。之所以这样界定是因为这些内容最终都会合并进目标分支是真正需要把关的部分而已被合入目标分支的历史提交则不在评审范围之内。同时规范给出了兜底处理如果预期评审范围不明确ambiguous应当询问用户要评审哪个范围而不是自行猜测。这一要求在 skill 工作流中进一步被强化为强制步骤见下文 Step 1。输出契约只报发现不给结论.agents/code-review.md对评审输出做了非常具体的规定这是整套规范中最具可操作性的部分只报告发现findings不输出变更摘要也不给出总体结论verdict每个发现必须以path:Lstart-Lend的格式给出文件路径与行号区间每个发现附带简短描述在有用时引用违规代码或所违反的规则每个发现必须标注严重级别取值固定为四档严重级别含义critical严重问题通常涉及正确性、安全或契约破坏必须修复major主要问题影响功能正确性或稳定性应当修复minor次要问题可修复可不修复suggestion建议性意见非必须如果没有正确性问题用一句话说明没有需要报告的内容并停止——严禁虚构发现或注水输出SKILL.md 中同样强调 do not invent findings or pad the output。这种契约式输出的设计目的是保持会话上下文精简评审方只回传结构化发现不携带中间阅读过程与推理便于在长会话中规模化执行。工具链gradle-code-review skill 与只读 companion 脚本.agents/code-review.md的 Tooling notes 指出仓库在 .claude/skills/ 下提供了一个名为gradle-code-review的 skill用 Claude Code 的 skill 格式带 frontmatter 的SKILL.md编写但其指令是纯 Markdown任何 Agent 都可以直接阅读并照做。两种接入方式若你的工具支持 Claude Code skillsskill 会被自动发现直接以/gradle-code-review调用否则手动阅读 .claude/skills/gradle-code-review/SKILL.md 与 contributing/CodeReview.md按其说明手工执行。Skill 的三步工作流SKILL.md 将整个评审过程拆解为三个职责清晰的步骤Step 1 — 解决范围当前会话执行。运行gradle-code-review.sh scope target查看目标分支、fork 点、fork 以来的提交、变更文件以及工作区是否脏。若范围不明确、或不确定是否要纳入未提交的工作——必须在此刻询问用户因为子 Agent 无法提问。本步骤结束时必须明确目标 ref 是什么、未提交工作是否在范围内。Step 2 — 将分析委托给全新上下文的子 Agent。在独立上下文窗口中启动一个子 Agent 执行实际审查向其传递包含以下要素的自包含提示词Step 1 确定的范围目标 ref、未提交/未跟踪变更是否纳入指示通过 companion 脚本收集变更gradle-code-review.sh diff target获取完整 diff对存疑代码用gradle-code-review.sh log path target/gradle-code-review.sh blame path获取历史上下文严禁直接调用git指示先阅读contributing/CodeReview.md并应用其关注点与排除项同时参考相关CLAUDE.md与contributing/指南只读约束仅允许使用 companion 脚本、Read、Glob、Grep——不构建、不类型检查、不修改代码构建信号由 CI 另行处理输出契约见上节——子 Agent 只返回发现不返回中间阅读或推理也不返回变更摘要。当前会话自己不要去读 diff 或被改动文件——那是子 Agent 的职责由本会话代劳会背离该设计目的保护主会话上下文不被撑爆。Step 3 — 中继发现当前会话执行。将子 Agent 的发现原样呈现给用户可做轻度格式化每个发现包含path:Lstart-Lend、清晰描述引用违规代码或相关数据流、前置条件、意外副作用、严重级别。只输出发现无开场白、无变更摘要、无总体结论。若无正确性问题报告一行无可报告内容并停止。Companion 脚本的四个命令所有 git 访问都经由配套脚本 .claude/skills/gradle-code-review/gradle-code-review.sh 完成因此只需给这一个脚本授予执行权限而无需逐个放行 git 命令。脚本只读绝不改动仓库。它暴露四个子命令命令用法作用scopegradle-code-review.sh scope [TARGET_REF]输出范围内内容摘要目标分支、fork 点、自 fork 点以来的提交、变更文件、工作区状态diffgradle-code-review.sh diff [TARGET_REF]输出完整审查 diff已提交 工作区 未跟踪文件loggradle-code-review.sh log PATH [TARGET_REF]输出某个路径的提交历史含补丁blamegradle-code-review.sh blame PATH输出某路径的git blame整文件刻意不做范围限制脚本必须以仓库相对路径原样调用Bash 从仓库根目录运行相对路径必然可解析不要改写成绝对路径——项目的权限规则只匹配相对路径形式绝对路径会触发权限提示。TARGET_REF 自动检测TARGET_REF是变更在 gradle/gradle 上最终合入的目标分支。省略时自动检测优先级如下当前分支的 open PR 的基础分支通过gh pr view获取否则在候选集成分支中推断 fork 父分支——依次探测master、release、releaseNx按 N 降序选择与 HEAD 的 merge-base 最近的候选最近一次分叉处候选顺序只在平局时起决定作用。也可以显式传入覆盖例如origin/release。scope命令会打印实际使用的目标 ref 及其来源如 open PR base branch (auto-detected) 或 inferred fork parent (no PR)。只读与确定性设计脚本通过set -euo pipefail保证健壮性并将每次 git 调用包裹在固定配置的 wrapper 中-c core.pagercat、-c color.uifalse、禁用外部 diff/pager 工具、固定--prettymedium等使输出不依赖用户全局/局部的 git 配置自定义 log 格式、外部 diff 工具、着色、前缀风格等保证不同环境评审输出一致。diff命令对未跟踪文件通过与/dev/null做--no-index对比的方式展示为新增内容全程只读、不暂存任何东西。配套的权限模型可在 .claude/settings.json 中看到显式allow了Bash(.claude/skills/gradle-code-review/gradle-code-review.sh:*)、Read(.agents/**)及一系列只读 Bash 命令cat、find、grep、ls、wc、gh api等同时deny了对master/release分支的git push——从权限层面封死了评审工具链对受保护分支的写操作。落地实践在 Gradle 仓库中跑一次 AI 代码评审综合上述规范与工具一次标准流程可以这样执行对任何支持读文件和运行命令的 Agent 均适用确定范围运行gradle-code-review.sh scope查看自动检测到的目标分支与 fork 点、提交列表、变更文件及工作区状态若范围不明例如不清楚是否纳入未提交工作先向用户确认阅读判断标准通读 contributing/CodeReview.md只关注正确性缺陷、API 契约违规、边界/错误处理缺口与安全问题忽略风格、格式与命名收集变更运行gradle-code-review.sh diff target获取完整 diff对语义微妙的历史代码用gradle-code-review.sh log path target和gradle-code-review.sh blame path补充上下文只读约束全程只读、不构建、不修改代码构建信号交由 CI 判断按契约输出每个发现严格为path:Lstart-Lend 简短描述必要时引用违规代码或规则 四档严重级别之一不输出变更摘要与总体结论无正确性问题则一句话说明并停止。这套流程的价值在于判断标准CodeReview.md、范围界定fork point 未提交变更、输出契约path:Lstart-Lend severity与执行机制skill 只读脚本四者解耦又相互咬合既保证了人机一致的评审质量又通过子 Agent 隔离上下文与只回传发现的契约保持了长会话的可扩展性。对于任何希望在大型代码仓库中落地 AI 辅助代码评审的团队这份.agents/code-review.md及其配套工具链都是一份可借鉴的完整范本。【免费下载链接】gradleAdaptable, fast automation for all项目地址: https://gitcode.com/gh_mirrors/gr/gradle创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考