html-effectiveness-review

02-review — 代码评审与理解

"Diffs and call-graphs are spatial information; markdown flattens them. Let the agent render the change as an annotated diff, draw the module as boxes and arrows, or write the PR description your reviewers actually want."

何时用

用户说	用哪个范式	模板
"review this PR / 评审一下 #312"	PR 评审 (reviewer 视角)	../../templates/diff.html
"帮我写 PR 描述 / write a PR writeup"	PR 写作 (author 视角)	../../templates/pr.html
"X 在这个 repo 怎么工作 / 调用栈是什么"	模块图	自建（见下）
"解释一下 auth flow / sync 是怎么转的"	模块图	同上

---

范式 2.1 · PR 评审（reviewer 视角）

空间形状：

• 顶部：一句话总结 + 文件风险地图（每文件一个圆点，颜色=风险，大小=改动量）
• 文件列表：每文件折叠区块；标题含 risk badge + diff 行数；展开看带行号 diff
• 行号 diff 必须等宽对齐

风险标签 3 档（不要再细分，用户记不住）：

• safe — 纯加法 / 类型扩展 / 测试 → 绿色
• worth a look — 行为微变 / 重构 → 黄色
• needs attention — 关键路径 / 新抽象 / 易错点 → 红色

HTML 骨架：

<header class="pr-summary">
  <h1>PR #247 — Review Summary</h1>
  <p>[一句话: what this PR does]</p>
</header>

<section class="risk-map">
  <h2>Risk map</h2>
  <svg viewBox="0 0 600 120">
    <g><circle cx="60"  cy="60" r="14" class="needs-attn" />
       <text x="60" y="95" text-anchor="middle">useOptimisticTasks.ts</text></g>
    <g><circle cx="160" cy="60" r="20" class="worth" />
       <text x="160" y="95" text-anchor="middle">TaskList.tsx</text></g>
    <!-- ... 圆点大小 = LOC log；位置随便排但保持视觉密度 -->
  </svg>
</section>

<section class="files">
  <details open>
    <summary>
      <code>src/hooks/useOptimisticTasks.ts</code>
      <span class="badge danger">needs attention</span>
      <span class="muted">+58 −0</span>
    </summary>
    <pre class="diff"><div class="line added"><span class="ln">12</span><span>+ ...</span></div></pre>
  </details>
</section>

关键 CSS（diff 行号）：

.diff { font-family: var(--font-mono); font-size: 12.5px; line-height: 1.55; }
.diff .line { display: grid; grid-template-columns: 56px 1fr; gap: 0; }
.diff .ln { color: var(--gray-500); padding: 0 12px; text-align: right;
            background: var(--gray-100); user-select: none; }
.diff .added   { background: rgba(120, 140, 93, 0.12); }
.diff .removed { background: rgba(176, 74, 74, 0.10); }