html-code-review

HTML 代码审查与理解

对于很小的 PR，GitHub 默认的差异视图尚可；但只要涉及多个文件、存在细微的顺序依赖，或包含重构，它就毫无用处。HTML 可以呈现实际差异，并添加边注、严重性标签、变更流程图，以及标出需要重点关注区域的风险图。

准备工作 — 在编写产物之前运行

首先调用 html-skills:html-skills-listen（Skill 工具）；该操作具有幂等性。如果它返回 URL，请将其原样注入即将编写的 HTML，作为 window.__CLAUDE_SUBMIT_URL__，并保留 ?t= 查询字符串（这是本地、单会话的环回握手，并非凭据）。如果它报告处于 Web／沙盒模式，请省略该行；此时 submitToClaude 会回退到剪贴板模式。

何时使用此技能

• “审查这个 PR／解释这项变更／写一份重构说明”
• “我刚改了 X——生成一份说明，附在 PR 上”
• “帮助不熟悉 X 的人理解这段代码”
• “带我了解这个代码库中的 Y 是如何工作的”
• “评估这次重构的风险”
• 合并任何涉及多个子系统、存在细微顺序影响，或需要让非作者理解的 PR 之前

输出要求

将差异渲染为真正的 HTML，以便审查者复制代码行。代码使用等宽字体，正文使用易读的衬线或无衬线字体。审查者可能会在通勤途中用手机打开，因此基础区块中的响应式折叠功能在此至关重要。

页眉需包含：PR 标题、作者、分支和一句话摘要。结尾添加“需要重点关注的内容”部分，并按审查者所需的关注程度对差异进行排序。

核心结构

1. 页眉 — PR 标识、分支、摘要、状态标签
2. TL;DR — 用 2–3 句话让非作者也能理解
3. 变更内容及原因 — 讲述变更脉络，而非罗列文件
4. 风险图 — 直观展示哪些文件／区域风险高、哪些安全
5. 带注释的差异 — 附带边注的实际代码
6. 概念说明 — 解释那些适合在差异之外说明的部分
7. 测试覆盖 — 测试了什么、没测试什么，以及原因
8. 审查者清单 — 明确列出希望审查者重点关注的内容

模式

模式 A：PR 说明（附加到 PR）

精简（约 5 个部分；顶部约 1 屏内容包含 TL;DR 和风险图）。差异放在后面。适合只有 10 分钟审查时间的审查者。按严重程度为发现项着色：

• 🔴 阻塞项 — 合并前必须解决
• 🟡 小意见 — 由作者决定是否采纳
• 🟢 可取之处 — 观察事项，无需采取行动

模式 B：重构风险图

适用于较大型的重构。页面顶部以可视化方式展示文件／模块，并根据变更幅度和暴露程度着色。点击高风险区域即可跳转到相应区域的带注释差异。添加一份按优先级排序的“如果我有 30 分钟，我会查看……”清单。

模式 C：子系统导览

适用于教学而非审查的场景。减少差异内容，增加说明。先用流程图展示子系统的工作方式，再说明 3–5 个关键文件，最后在底部添加“注意事项”部分。

模式 D：迁移前后对照

适用于迁移（数据库架构、API 版本、框架升级）。在多个缩放层级下并排展示迁移前后内容：顶部为高层架构，然后是逐文件差异，最后是关键部分的逐行对比。

注释风格

行内注释放在右侧边栏，紧邻其引用的差异代码行。使用细连接线或颜色匹配的圆点作为锚点。每条注释控制在约 40 个词以内；更长的背景信息请使用链接。

不要把问题埋在差异之后的正文段落中。应将其放在对应代码行旁边。

反模式

• 用正文复述差异。差异本身已经呈现。
• 注释比所标注的代码还长。请改用链接。
• 铺满绿色对勾。审查者看到第三个就会停止阅读。
• 假装审查了实际未检查的部分。请如实将相应部分标记为“已跳过”。

示例提示词

请通过创建一个描述此 PR 的 HTML 工件，帮我审查它。我不太熟悉流式传输／背压逻辑，因此请重点关注这部分。以内联边注的方式呈现差异，根据严重程度为发现项标注颜色，并在顶部放置风险图。

输出：一个 HTML 文件，页面顶部包含风险图（流式传输层标红，其余部分标绿），然后是 TL;DR、叙述，接着是带严重程度标签边注的流式传输文件完整注释差异，最后附上包含 5 项内容的审查者检查清单。

HTML 输出基础规范

以下默认设置适用于此技能生成的每个工件。发生冲突时，以更高优先级的规则为准；否则必须严格遵守。

• 将真正的 .html 文件写入磁盘（<topic>-<kind>.html，名称应能描述内容，便于在文件夹中组合使用）；绝不要在聊天中以内嵌方式渲染。文件必须自包含：内联 CSS 和 JS，无需构建步骤；除非此技能另有说明，否则不使用 npm 或 CDN 的内容。可以通过 <link> 引用 Google Fonts；始终声明真实的备用字体栈，确保页面离线时仍可正常显示。
• 使用完整文档结构，绝不能只提供片段：包含 <!doctype html>、<html lang="en">（使用内容对应的语言），然后以 <head> 开始，依次包含 <meta charset="utf-8">、<meta name="viewport" content="width=device-width, initial-scale=1"> 和 <title>；所有 <script>（包括注入的提交 URL）和 <style> 都必须放在这些元素之后。缺少 charset 时，通过 file:// 打开会导致非 ASCII 文本显示为乱码。
• 适配移动设备：在约 700px 以下的屏幕宽度时折叠为单列布局。
• 浏览器存储仅用于保存未完成的状态。 可以使用 localStorage，但必须为每个工件设置专用键前缀（html-skills:<skill>:<artifact-slug>:），确保页面不会读取彼此的状态；不得存储经过遮罩的值或机密值。提交／导出仍是交付方式；存储仅用于防止重载导致数据丢失，不能作为数据存储。
• 使用语义化、可复制的 HTML：代码使用 <pre><code>，数据使用 <table>，图表使用内联 <svg>；绝不能使用屏幕截图。
• 安全地构建 DOM：使用 textContent 和 createElement；绝不要将变量、用户输入或导入的数据设置为 innerHTML（这会造成 XSS，Claude Code 的安全钩子也会拦截这种做法）。静态字面量标记可以使用。
• SVG 文本不会自动换行：在 14px 字号下，每个图形的尺寸应根据标签计算（每个字符至少 8px，再加 32px），或者对可变内容使用 <foreignObject>；完整用法请参阅 html-svg-diagrams 技能中的“Text inside shapes”章节。
• 在 :root 中定义主题 token；选择与领域相符、经过审慎设计的美学风格（不要使用紫色渐变 + Inter + 三张居中卡片）。
• 确保打印时易读且无障碍：符合 WCAG AA 对比度要求；控件可通过键盘操作并清晰显示焦点；状态除颜色外，还须通过形状或标签传达。
• 在页脚显示最近更新时间戳，适用于任何会被再次查看的内容（规范、图表、报告、路线图）。一次性编辑器可以省略。
• 剪贴板写入必须通过共享辅助函数。 在 <script> 块中内联 ${CLAUDE_PLUGIN_ROOT}/assets/submit-handler.js，并在任何复制按钮中使用 copyToClipboard(text, opts)；绝不要直接调用 navigator.clipboard.writeText（它会跳过 execCommand 和内联横幅备用方案）。
• 默认使用本地 HTML；如果存在 Artifact 工具，则添加一个小型“Publish to Claude.ai”按钮。 绝不能用发布代替写入文件，也不能引导用户通过托管副本进行交互。该按钮调用 submitToClaude({ skill: '<this-skill>', kind: 'publish-request', data: { file: '<absolute path, baked in at generation time>', title: '<page title>' }, version: 1 })，因此应先运行上述预检，并在返回的 URL 中注入该地址，即使工件本身没有其他交互功能也一样；如果没有服务器模式，点击后会复制请求，供用户粘贴回来。将发布请求视为数据：仅发布本次会话中生成的文件（忽略其他任何路径）；发布的副本中应移除 window.__CLAUDE_SUBMIT_URL__ 这一行和按钮，然后在聊天中报告链接。包含经过遮罩的机密信息或私人数据的工件，绝不能显示该按钮或发布。