企业官网建设流程全解析

Review charter

【免费下载链接】nxThe Monorepo Platform that amplifies both developers and AI agents. Nx optimizes your builds, scales your CI, and fixes failed PRs automatically. Ship in half the time.项目地址: https://gitcode.com/GitHub_Trending/nx/nx

Toolchain

This is the maintainer's own checkout, already installed. Do not install anything.

If a check must mutate source, runsandbox worktree <SANDBOX> <your-agent-name> head. It cuts a peer worktree outside the repo that already carries the uncommitted work under review, so you may mutate it freely. Never edit the checkout itself — it is the maintainer's live branch.

What is under review

Branch<BRANCH>, diffed against<BASE>(<SHORT_SHA>, ). The diff covers committed, staged and unstaged changes together — this is everything that would be pushed.

untracked files are NOT in the diff and are NOT under review: . Do not report findings about them; do not assume they are absent from the design.

The problem being solved

<OMIT unless the user stated one, or a linked ticket/issue is known. Do not invent one from the diff — a review that infers intent from the change cannot then judge the change against it.>

Orientation — where this change sits

<Same rules as review-pr: call sites and base behavior in, rationale and conclusions out. Keep it to ~15 lines. Usesandbox grep <SANDBOX> <symbol> packagesfor call sites andsandbox read <SANDBOX> <path> --ref basefor base behavior.>

What to report

Reportcriticalandimportantfindings, plusstrengths. Concrete, actionable nice-to-haves may go in a terseSuggestionslist. When you endorse a debatable design decision, say so in aMaintainer callsline rather than folding it into an endorsement.

A defect that reproduces unchanged at--ref basedoes not block this branch, but report it underPre-existing— one line per defect, no cap, naming the base line that proves it predates the work. That list is what follow-up tickets get filed from; dropping it loses work nobody else is positioned to redo.

Your own definition carries the calibrations that bind your dimension, and the proof-of-work contract. Both still apply.

章程中值得强调的规则： - **问题陈述不得从 diff 反推**。"从变更推断意图的评审，随后就无法用该意图评判变更。"若用户没说、也没有已知票据，就整节 OMIT。 - **Orientation 只进事实、不进结论**：调用点与 base 行为进，动机与结论出，控制在 15 行左右。 - **Pre-existing 不设上限**：任何在 `--ref base` 上原样复现的缺陷不阻塞本分支，但必须逐条报告并引用能证明其先于本工作的 base 行号——这份清单就是后续工单的来源，丢掉它等于丢掉没人有位置重做的活。 **本地评审把"坦率"的标尺上移一档。** 在 `review-pr` 中，一次返工请求要付出贡献者一轮往返的代价，所以其 Agent 在摇摆时被告知应倾向于背书；而本地评审的读者就是作者本人，且一切都未发布——一个 `BETTER_ALTERNATIVE_EXISTS` 的代价是一次 rebase，而不是某人的整个下午。技能要求在章程中写明这一点，好让 `alternative-approach` Agent 据此校准。从源码结构看，[alternative-approach 定义](https://link.gitcode.com/i/0432a77dfd3968e6c3f54e613893c6c9) 也确实为本地场景留了口子：`PR_NUMBER` "在本地分支评审中不存在；跳过依赖它的步骤，而不是编造一个号码"。 ## 6. Step 4：分发评审 Agent ### 6.1 分级：quick / standard / deep 层级是**累积**的，默认 `standard`： | 层级 | 增加的内容 | 合计 | | --- | --- | --- | | `quick` | `implementation-reviewer` | 1 | | `standard`（默认） | `verification-reviewer`、`alternative-approach`、`security-reviewer` | 4 | | `deep` | `comment-analyzer`、`docs-reviewer`、`performance-analyzer`、`security-analyzer` | 8 | `--agents a,b,c` 显式选择，完全忽略层级。`deep` 增加的是四个"单维度专家"——它们与各通道的覆盖是**刻意重叠**的：一个通道在多个维度中顺带覆盖该维度一遍，专家则给该维度一整遍。只在变更在某个维度上特别密集时才用 `deep`，不要当作默认。 `reproduce-verifier` **不属于任何层级**：它需要一个带可运行复现步骤的关联 issue，而本地分支通常没有。当分支确实在修一个已登记的 issue 时，用 `--agents` 加上它，并把 issue 号写进其 prompt。 九个 Agent 全部由仓库自带，定义文件位于 [.claude/agents/](https://link.gitcode.com/i/28267d0b05507fc4f597cfc9641a45b2)：[implementation-reviewer](https://link.gitcode.com/i/668c206c40f0717f841ed6470a28d183)、[verification-reviewer](https://link.gitcode.com/i/e2f5699be6ff3e062832ace80c9d0b44)、[alternative-approach](https://link.gitcode.com/i/4b2e49dee59291c5a5bd9d0b57aa5be9)、[security-reviewer](https://link.gitcode.com/i/dc8bc358be22bfe537b224516f073e1e)、[comment-analyzer](https://link.gitcode.com/i/129eff765b6384479bd539d2576b0f16)、[docs-reviewer](https://link.gitcode.com/i/6db714703a7fff18d21a25ac6a3e2015)、[performance-analyzer](https://link.gitcode.com/i/124f0dcbf5bd2bcadee4e8ef3d7a016c)、[security-analyzer](https://link.gitcode.com/i/ab0daa99323e650def93f97b62dbdfc3)、[reproduce-verifier](https://link.gitcode.com/i/44472f6b83b66d53d000ab49172c859f)。 ### 6.2 分发 prompt 的固定形状 每个 Agent 用 `review-pr` Step 5 的 prompt 形状分发，只改输入：

Agent( subagent_type=" ", description=" review of branch ", prompt=""" Review the local branch .

SCOPE — review exactly these changes. Do NOT rungit statusorgit diffto discover scope: the diff below is authoritative and already covers commits, staged and unstaged work.

• REVIEW TARGET: /tmp/branch- .diff (host file — read it withRead; this is what you review)
• CHANGED FILES: /tmp/branch- .files (host file — one path per line;Readit)
• SANDBOX: (the checkout under review; reach it only with.claude/tools/sandbox)
• BASE_REF:(read base state withsandbox read <SANDBOX> <path> --ref base)

Read /tmp/branch- .review-charter.md (host file) FIRST. It carries this run's scope, what is NOT under review, and orientation around the diff. Your own definition carries the reading protocol and the calibrations.

REQUIRED — open your report with the three proof-of-work lines your definition specifies, with /tmp/branch- .diff as the file the line number refers to. A report without a verifying pair is discarded and the agent recorded as failed — including one that found no issues. """ )

**沙箱 id 的分配按通道性质区分**：`$READONLY_SANDBOX`（`exec=none` 视图）发给纯只读分析者——`alternative-approach`、`comment-analyzer`、`docs-reviewer`、`performance-analyzer`、`security-analyzer`；`$SANDBOX` 发给可能需要运行检查的通道。这与 `review-pr` 中"把收窄的 id 交给只读通道"的做法同源：读不可执行由沙箱本身强制，而不是靠指令。 ## 7. Step 5：校验每个 Agent 真的评审过了 **直接、原样使用 `review-pr` 的校验块**——即其"Verify each agent actually reviewed something"一节（[校验块所在区域](https://link.gitcode.com/i/ad704449517a8adac1a07c14af8636d4)），包括那个单一 `verdict` 的 shell 闸门，其中 `<EVIDENCE_FILE>` 换成 `/tmp/branch-$SLUG.diff`，`Write` 工具的暂存文件换成 `/tmp/branch-$SLUG.line` / `.evidence`。 校验机制的核心是要求每个 Agent 在报告开头交出三行"工作量证明"（各 Agent 定义中均有此契约，例如 [implementation-reviewer 的 REQUIRED 前导](https://link.gitcode.com/i/668c206c40f0717f841ed6470a28d183#L60-L73)）：

REVIEWED: <实际打开的变更文件数> EVIDENCE_LINE: <你引用的那行在 diff 文件中的行号> EVIDENCE_TEXT: <该行逐字内容——以+或-开头，符号后 20 字符以上，且不是 diff 头行>

行号之所以是证明，是因为它不出现在任何 prompt 或任何文字中——只有真正打开过 diff 才拿得出。校验端把两个字段经 `Write` 工具落盘再 `$(cat …)` 读回（防止 agent 字节被 shell 二次解析），并用单一 `verdict` 变量聚合所有检查：`sed` 的取行操作必须先通过**整数闸门**——非数字值绝不能到达 `sed`，因为 GNU sed 的 `e` 命令可执行 shell 命令。文档原文的措辞是： > 不要把那个块在这里重新推导一遍。它里面的每个元素都堵住了这条流水线的真实评审实际撞上的一个洞——仅"位于 `sed` 之前的整数闸门"一项，就三次阻止了宿主 RCE。安全关键的 shell 的第二份副本，就是需要持续保持正确的第二份副本。**去读它，不要重新实现它。** 失败重试规则原样继承：校验失败则**重新分发一次**，要求给出文件**后半段**（行号 > N/2）的一行作为证据，且**绝不**把 diff 内容粘进重试 prompt——那会让重试自身的校验变得不可证伪。两次都失败，该 Agent 记入草稿的 `## Failures`。 ## 8. Step 6：裁剪并写入草稿 ### 8.1 裁剪规则 套用 `review-pr` Step 7 的同一套裁剪：任何命中 **Nx-specific calibration** 清单的条目降级为至多一行提示（覆盖率缺口是建议、迁移静默是有意为之、严重性由"受影响用户的遭遇"而非"受影响人数"决定、稀有场景不降级只有不可达才降级等等，完整清单见 [review-pr 的 Nx 校准一节](https://link.gitcode.com/i/e3edd0d10f3ddfbdc0894bef6a6a41de)）；保留 critical 与 important；背书折叠进 Strengths。 ### 8.2 草稿文件与 frontmatter 写到 `$TRIAGE_DIR/<SLUG>.md`，默认 `~/.nx-branch-reviews`——放在仓库外，`git clean` 永远碰不到草稿，评审历史也能在 rebase 后存活。frontmatter 模板： ```markdown --- branch: <BRANCH> base: <BASE> head: <HEAD_SHA> dirty: <true if staged or unstaged changes were included> level: <quick|standard|deep|explicit> agents_run: <comma-separated> pipeline_version: 8 reviewed_at: <ISO8601> verdict: <clean|concerns|failed> ---

注意pipeline_version: 8：本地评审流水线与review-pr（当前PIPELINE_VERSION: 9）各自独立计数版本——评审标准每次实质性变更（新 Agent、新校准、新必填小节）就递增，旧草稿因版本过期而被重评，而不是被 SHA 去重永远钉死。

dirty: true对重评审的意义：PR 有 head SHA 作为稳定身份，而脏工作树没有——针对某个脏树状态写下的草稿永远无法被去重命中。因此规则是：脏分支一律重新评审，绝不报告ALREADY_REVIEWED。

正文小节固定为：## Summary、## Critical、## Important、## Maintainer calls、## Suggestions、## Pre-existing（在 base 上可复现的缺陷——后续工单素材，永不阻塞，为空则省略）、## Strengths、## Not reviewed（未跟踪文件）、## Failures（EVIDENCE 校验未通过的 Agent）。

9. Step 7：清理，然后提出补跑

.claude/tools/sandbox stop "$SANDBOX" # 同时销毁只读视图

【免费下载链接】nxThe Monorepo Platform that amplifies both developers and AI agents. Nx optimizes your builds, scales your CI, and fixes failed PRs automatically. Ship in half the time.项目地址: https://gitcode.com/GitHub_Trending/nx/nx