企业官网建设流程全解析

• 构建工具
• 开发工具

本文以 Gradle 开源仓库（gh_mirrors/gr/gradle）中内置的gradle-code-reviewSkill 为主线，讲解该仓库在代码评审（Code Review）场景下的完整落地机制：从"评审依据"到"只读 Git 脚本封装"，再到"范围解析 → 子代理分析 → 发现转述"的三阶段工作流。读完本文，你将掌握如何在 Gradle 仓库中执行一次规范、只读、聚焦正确性的代码评审，并能将其中的设计思想（评审判断与评审机制分离、上下文隔离、输出契约）复用到你自己的项目或 Agent 工作流中。

一、为什么 Gradle 仓库需要一套专门的评审 Skill

Gradle 是一个体量庞大的开源构建工具，其仓库包含上千个模块（可参见仓库根目录的 settings.gradle.kts 与platforms/、subprojects/目录结构）。对这样规模的项目而言，人工评审每一份贡献的成本极高。

仓库在 AI_POLICY.md 中明确指出了这种"不对称性"：AI 工具让提交大量代码变得很容易，却并不会让评审这些代码变得同样快。因此，评审预算（review budget）是稀缺资源，而 PR 是对话的开始而非成品——贡献者需要对提交内容负责，并与评审者持续协作。

正是出于这一背景，仓库在.claude/skills/gradle-code-review/下放置了gradle-code-reviewSkill，把"评审什么"与"如何评审"拆成两个层次：

• 评审判断（what to look for）：以 contributing/CodeReview.md 为唯一事实来源；
• 评审机制（how to review）：由 Skill 的 SKILL.md 与其配套脚本 gradle-code-review.sh 承载。

二、评审判断依据：聚焦正确性，忽略风格

仓库的评审判断由 contributing/CodeReview.md 定义，它极其精简，只有两条：

要报告的内容（What to look for）：

• Correctness bugs and logic errors（正确性缺陷与逻辑错误）
• API contract violations or misuse（API 契约违规或误用）
• Edge cases and error-handling gaps（边界情况与错误处理缺口）
• Security concerns（安全问题）

不要报告的内容（What NOT to report）：

• Style nits, formatting, or naming conventions（风格吹毛求疵、格式或命名约定）

这一原则在 .claude/rules/code-review.md 中被重申并明确适用于人类与 AI 评审者："It applies to human and AI reviewers alike."（对人和 AI 评审者一视同仁）。这意味着，无论评审者是谁，评审输出只应聚焦正确性、契约、边界与安全，不应为格式与命名这类主观问题浪费评审预算。

三、只读 Git 封装脚本：gradle-code-review.sh

Skill 规定：所有 git 访问都必须通过配套脚本gradle-code-review.sh，绝不允许直接调用git命令。这样设计的目的有两个：

1. 权限最小化：整个 Skill 只要求这一个脚本具备执行权限，而不是为每个 git 子命令单独授权；
2. 只读保障：脚本从不修改仓库状态（不暂存、不提交、不改文件），这是代码评审的安全底线。

3.1 四个子命令

脚本暴露四个子命令，完整签名与功能如下：

3.2 必须用仓库相对路径调用

SKILL.md 特别强调：必须严格以仓库根目录下的相对路径调用该脚本（Bash 从仓库根目录运行，因此相对路径可以解析），不要改写为绝对路径。原因很实际：项目的权限规则只允许相对路径形式，改为绝对路径将无法匹配权限规则并触发提示。

3.3 固定 git 配置：保证输出可预测

从源码看，脚本内部将所有 git 调用包装在一个固定配置的函数中（见 gradle-code-review.sh），强制以下-c参数：

• core.pager=cat：禁用分页器，输出可直接被后续程序消费；
• color.ui=false：禁用颜色，保证输出纯文本；
• diff.external=：清空外部 diff 工具，防止自定义 diff/pager 干扰；
• diff.mnemonicPrefix=false、diff.noprefix=false、diff.relative=false：固定 diff 前缀与相对路径行为；
• log.showSignature=false、log.decorate=false、format.pretty=medium：固定日志格式；
• status.relativePaths=false：固定状态输出路径；
• blame.showEmail=false、blame.showRoot=false：固定 blame 输出。

其目的是让脚本输出不依赖用户本地的全局/局部 git 配置（自定义日志格式、外部 diff/pager、颜色、前缀风格等），确保任何环境中评审输出都一致、可解析。除-c之外，命令级还叠加了--no-ext-diff、--no-textconv等无法通过-c强制的开关。

3.4 三个子命令的底层实现细节

scope（gradle-code-review.sh）依次输出：

1. Target branch：解析出的目标分支及其来源（explicit argument / auto-detected）；
2. Fork point：目标分支与 HEAD 的 merge-base；
3. Commits since fork point：<base>..HEAD范围内、--abbrev=12的提交列表（%h %s格式）；
4. Files changed (committed)：git diff --stat统计；
5. Working tree (uncommitted)：git status --porcelain输出；若干净则打印clean。

diff（gradle-code-review.sh）分为三部分输出：

1. Committed changes ($base..HEAD, target $target)；
2. Uncommitted changes (working tree vs HEAD)；
3. Untracked files：通过git ls-files --others --exclude-standard -z列出，再对每个未跟踪文件执行git diff --no-index -- /dev/null <file>将其完整内容作为新增展示（--no-index返回退出码 1 是预期行为，脚本用|| true吞掉，全程只读、不暂存）。

log 与 blame：log输出指定路径在$base..HEAD内的git log -p（含补丁）；blame直接对路径执行git blame --。二者主要用于对微妙代码补充历史上下文。

3.5 TARGET_REF 的目标分支检测机制

TARGET_REF即"变更最终要合入的目标分支"。省略时脚本自动检测，优先级如下（见 gradle-code-review.sh 的detect_target）：

1. PR 基础分支（确定性来源）：若本机装有ghCLI 且当前分支存在打开的 PR，通过gh pr view --json baseRefName -q .baseRefName获取 PR 的基础分支名，再经resolve_branch_ref映射为跟踪引用（优先目标远程，其次任意远程，最后本地分支）；
2. Fork 父分支推断（无 PR 时）：在候选分支中选取 HEAD 真正"fork 出来"的那个——即与 HEAD 的 merge-base 最晚的候选；平局时按候选顺序master>release>release<N>x（按数字降序）打破。

scope命令会打印实际使用的目标及选择方式（如open PR base branch、inferred fork parent (no PR)）。目标远程的识别（gradle_remote）通过正则匹配远程 URL 是否指向github.com/gradle/gradle，因此远程名不一定是origin；找不到时回退upstream→origin→ 第一个远程。

若自动检测失败（既无打开 PR，目标远程上也找不到候选分支），脚本会报错并退出码 2，提示显式传入TARGET_REF，例如scope upstream/master。

四、核心工作流：三阶段评审

整个评审流程在 SKILL.md 中被设计为三个明确的阶段。其总体设计思想是：本会话只负责"范围解析"与"结果转述"，真正的 diff 阅读与代码分析被委托给一个拥有全新上下文的子代理（sub-agent），从而避免读 diff 和读文件撑爆当前会话的上下文窗口。

Step 1 — 解析评审范围（本会话执行）

运行gradle-code-review.sh scope <target>，查看目标分支、fork 点、其后的提交、变更文件以及工作区是否脏。

核心原则是：所有最终会合入目标分支的内容都需要评审——即自 fork 点以来的提交，加上未提交/未跟踪的变更。但部分提交可能已被推送并评审过，因此实际评审区间可以更窄。

关键约束：如果范围存在歧义，或不确定是否应包含未提交的工作，必须先询问用户要评审哪个区间再继续。这一步必须在当前会话完成，因为子代理无法向用户提问。在进入下一步前，必须明确两件事：目标 ref 是什么、未提交工作是否在范围内。

Step 2 — 将分析委托给全新上下文的子代理

启动一个子代理（Agent 工具）在它自己的上下文中执行评审，并给它一个自包含（self-contained）的提示词，其中必须包含：

1. Step 1 的范围：目标 ref，以及未提交/未跟踪变更是否在范围内；
2. 通过配套脚本收集变更：运行gradle-code-review.sh diff <target>获取完整 diff；对微妙代码用gradle-code-review.sh log <path> <target>/gradle-code-review.sh blame <path>获取历史上下文；子代理同样不得直接调用 git；
3. 先读评审依据：要求子代理首先阅读contributing/CodeReview.md并应用其中的关注点与排除项，同时参考相关的CLAUDE.md与contributing/指南；
4. 只读约束：只允许使用配套脚本、Read、Glob、Grep 四类能力——不要构建、类型检查或修改代码（构建信号由 CI 另行处理）；
5. 输出契约（见下文）——子代理只返回发现（findings），不返回中间阅读过程、推理过程或变更摘要，以保证当前会话上下文保持精简。

本会话自己不要去读 diff 或受影响的文件——那是子代理的职责，在当前会话读会破坏上述设计目的。Agent 工具调用会直接把子代理的发现作为返回值返回，无需等待或轮询。

Step 3 — 转述发现（本会话执行）

将子代理的发现逐字呈现给用户（可做轻度排版）。每条发现必须符合输出契约（详见下节）。

五、输出契约：只报告发现，不发表综述

这是整个评审工作流中最需要严格遵守的部分，它同时约束子代理的返回内容和最终呈现：

每条发现包含三要素：

• path:Lstart-Lend：从仓库根目录出发的文件路径加行号区间，例如platforms/jvm/scala/.../ScalaForkOptions.java:L40-L52；
• 清晰的问题描述：引用问题代码，或包含相关数据流路径、前置条件、非预期副作用；
• 严重级别（severity）：critical/major/minor/suggestion四档。

输出纪律：

• 只输出发现——不加前言、不总结变更内容、不做总体结论或收尾评价；
• 若子代理未发现正确性问题，只输出一行"无可报告"并停止——严禁编造发现或凑字数。

这一契约与 .claude/rules/code-review.md 中"report findings only……Do not add a summary of the change or an overall verdict"的要求完全一致，属于仓库层面统一的评审输出规范。

六、Skill 的发现与调用方式

gradle-code-reviewSkill 以 Claude Code 的 Skill 格式书写（SKILL.md带 frontmatter），但其正文是任何 Agent 都能阅读和遵循的纯 Markdown。根据 .claude/rules/code-review.md 的说明，它的两种使用方式为：

• 若你的工具支持 Claude Code Skills，该 Skill 会被自动发现，通过/gradle-code-review直接调用；
• 否则，直接阅读 SKILL.md 与 contributing/CodeReview.md，按其说明手动执行即可。

Skill 的 frontmatter 中声明了触发条件：当用户要求评审代码、执行代码评审、评审某个 change/diff/branch/PR，或在变更合入目标分支前进行检查时触发，并明确"在本仓库工作时优先于任何通用 code-review skill"。

七、与仓库其他治理机制的配合

这套评审工作流并非孤立存在，它与仓库的 Agent/贡献治理体系相互咬合：

• AGENTS.md：面向任何厂商 AI 编码 Agent 的仓库总指引，要求所有 Agent 在仓库内工作前先阅读并遵循它，人类贡献者则应从 CONTRIBUTING.md 开始；
• CLAUDE.md：将 AGENTS.md 指认为仓库内工作的必读入口；
• .claude/rules/code-review.md：将评审规则（关注点、范围、输出格式、工具说明）固化为规则文件，与 Skill 形成"规则定义 + 机制实现"的分工；
• AI_POLICY.md：从政策层面解释了为何评审如此重要——AI 让提交变容易但没让评审变快，因此评审输出必须聚焦、诚实、由人类最终决策，且重大 AI 参与需要在 PR 对话中披露（而非提交元数据）。

从源码结构看，这套工作流与仓库"平台化、模块化"的治理思路一脉相承：评审判断（CodeReview.md）、评审规则（rules/code-review.md）、评审机制（skills/gradle-code-review/）三个层次各司其职，均可独立演进。

八、把该工作流迁移到自己的项目

虽然gradle-code-review是为 Gradle 仓库量身定制的，但其设计模式完全可以迁移：

1. 判断与机制分离：把"评审关注什么"（正确性、契约、边界、安全）写成一份极简的CodeReview.md，把"如何执行"（脚本、步骤、输出格式）单独成文，二者解耦、各自可独立维护；
2. 只读脚本收敛 git 访问：用一个 bash 脚本封装所有 git 调用，固定-c配置保证输出确定性，并通过scope/diff/log/blame四个子命令覆盖评审所需能力，实现权限最小化；
3. 目标分支自动检测：优先利用 PR 元数据（gh），无 PR 时用 merge-base 时间推断 fork 父分支，并支持显式覆盖；
4. 上下文隔离：范围解析与结果转述在主会话，深度分析交给全新上下文的子代理，防止大 diff 撑爆上下文；
5. 输出契约：统一path:Lstart-Lend+ 描述 + severity 的格式，只输出发现、不给总体结论，无问题就明说——这既节省评审预算，也让输出可被机器解析、被工具链消费。

将这套工作流用于你自己的仓库时，只需替换目标远程匹配逻辑（gradle-code-review.sh 的gradle_remote正则）与候选分支列表（master/release/release<N>x），其余机制可原样复用。

九、总结

Gradle 仓库的gradle-code-reviewSkill 是一套将"评审判断、评审规则、评审机制"三层分离的完整工程实践：以 contributing/CodeReview.md 定义评审聚焦点，以 gradle-code-review.sh 实现只读、确定性的 git 访问封装，以 SKILL.md 组织"解析范围 → 委托子代理 → 转述发现"的三阶段流程，并以严格的输出契约保证评审输出聚焦、可信、可解析。这套设计不仅服务于 Gradle 仓库自身的评审预算保护，也为任何重视 AI 协作质量的开源项目提供了一个可以直接借鉴的评审工作流范本。

• 构建工具
• 开发工具