code-review

代码审查技能

概述

对 Git 差异进行结构化代码审查。分析更改的正确性、安全性、复杂度、可维护性和特定语言的最佳实践，然后将审查结果保存为 Markdown 报告和独立的交互式 HTML 报告——采用与 diff-summary 和 diff-viewer 相同的产物模式。

HTML 报告为双语（韩语 + 英语，提供整页语言切换，默认显示韩语），并包含：严重性徽章、语法高亮（支持浅色／深色／自动主题和 8 种代码配色方案）、紧凑且可折叠／调整大小的侧边栏、每条审查结果的“复制 Markdown”功能、存储在浏览器中的逐条评论，以及“复制反馈”按钮（会生成用于优化审查结果的再生成载荷）。

核心原则： 输入差异，输出带严重性标签的审查结果，严格限定在更改内容的范围内。

命令

命令	技能	输出	使用时机
/code-review [scope]（或隐式触发）	code-review	.reviews/ 下的 Markdown 报告和双语 HTML，并在浏览器中打开	默认审查
/code-review-md [scope]	code-review-md	.reviews/<date>_<sha>.md 中的 Markdown 文件（无 HTML）	仅需 Markdown 记录，便于通过 Git 分享

命令示例

/code-review — Markdown + HTML

User: /code-review review PR #42
→ gh pr diff 42
→ diff_stats.py reports has_security_sensitive_files: true
→ Load python.md + common-vulnerabilities.md
→ Analyze; find SQL injection (CRITICAL)
→ Write .reviews/2026-05-03_a1b2c3d.md      (Korean, **Language:** ko)
→ Write .reviews/2026-05-03_a1b2c3d.en.md   (English, same IDs/structure)
→ python <skill-path>/scripts/generate_html_report.py .reviews/2026-05-03_a1b2c3d.md
→ open .reviews/2026-05-03_a1b2c3d.html     (Korean shown by default; toggle to English)
→ Report finding counts, risk, artifact paths, fresh verification, and browser-open result

User: 마지막 커밋 코드 리뷰해줘
→ git diff HEAD~1..HEAD
→ Analyze; write the Korean report and its English sibling
→ Generate + open the bilingual HTML report
→ Report finding counts, risk, artifact paths, fresh verification, and browser-open result

/code-review-md — 仅 Markdown

User: /code-review-md review staged changes
→ git diff --staged
→ Analyze
→ mkdir -p .reviews/
→ Write .reviews/2026-05-03_staged.md
→ Report finding counts, risk, report path, and fresh verification
→ If `.reviews/` is not ignored, suggest adding it to .gitignore (do NOT modify it)

确定审查范围

解析用户的请求，确定要审查的代码，然后运行相应的 Git 命令：

用户意图	Git 命令
“审查我的更改”／未指定范围	git diff（未暂存）+ git diff --staged（已暂存）
“审查已暂存的更改”	git diff --staged
“审查上一次提交”	git diff HEAD~1..HEAD
“审查提交 <sha>”	git diff <sha>~1..<sha>
“审查最近 N 次提交”	git diff HEAD~N..HEAD
“审查分支 X”／“与 main 比较”	git diff main...<branch>（三点语法，使用合并基础）
“审查 PR #N”	gh pr diff N

如果用户的意图不明确，默认审查已暂存和未暂存的更改。如果完全没有更改，请告知用户并说明可能的原因（忘了暂存？分支不对？）。

获取用于报告文件名的短 SHA：

• 对于特定提交：使用该提交的短 SHA
• 对于提交范围：使用最新提交的短 SHA
• 对于没有提交的已暂存／未暂存更改：使用 staged 或 working

审查流程

按顺序执行以下步骤：

1. 收集上下文

运行适当的 Git diff 命令。然后运行 diff 统计辅助脚本，获取机器可读的摘要：

git diff [range] --numstat | python <skill-path>/scripts/diff_stats.py

该脚本会输出 JSON，其中包含已更改的文件、检测到的语言，以及是否涉及安全敏感文件。

2. 加载参考资料

根据 diff_stats.py 检测到的语言，读取相关参考文件。只加载所需文件，不要一次性读取全部文件：

• .py 文件 → 读取 references/python.md
• .js、.ts、.jsx、.tsx 文件 → 读取 references/javascript-typescript.md
• .go 文件 → 读取 references/go.md（如果存在）
• .rs 文件 → 读取 references/rust.md（如果存在）
• .java、.kt 文件 → 读取 references/java.md（如果存在）

始终读取 references/review-criteria.md，了解审查框架和严重性定义。

如果 diff_stats.py 报告 has_security_sensitive_files: true，还要读取 references/common-vulnerabilities.md。

3. 分析差异

阅读每个已更改文件的差异，并从以下五个维度进行分析：

1. 正确性 — 代码是否实现了作者的意图？检查逻辑错误、边界情况、类型不匹配和错误处理缺陷。
2. 安全性 — 检查注入风险、身份验证缺口、敏感数据泄露、加密不安全和输入验证问题。
3. 复杂度与一致性 — 是否增加了认知负担？是否破坏了现有模式或命名约定？
4. 可维护性 — 未来的开发者能否理解？是否存在紧密耦合、公共 API 缺少文档、魔法值或难以测试等问题？
5. 最佳实践 — 语言或框架特定的惯用法和反模式（参考已加载的参考文件）。

为每项发现分配严重性：

严重性	含义	所需操作
CRITICAL	生产环境中的数据丢失、安全漏洞或崩溃	合并前必须修复
HIGH	Bug、漏洞或严重的设计缺陷	合并前应修复
MEDIUM	代码异味、不一致或中等风险	建议修复
LOW	风格、命名或细微改进	可选改进
INFO	已核实且会实质影响评审决策的背景信息，但无需修改代码	无需操作

切勿仅因不确定或出于赞扬而使用 INFO。只有当缺少的证据会改变严重性或所需操作时，才将其列为一个具体的 Open Questions 条目；否则省略。

每项发现的标题都必须包含稳定 ID：#### [CR-001] ...、[CR-002]，依此类推。HTML 报告会根据此 ID 关联每项发现的评论，因此两个语言版本中同一项发现必须使用相同的 ID（参见 Report Language）。ID 保持英文；切勿在不同语言版本间重新编号。

证据优先写作规范

本规范适用于 Markdown 和 HTML 评审。

• 对于每项可操作的发现，按以下顺序撰写：观察到的行为 → 实际影响 → 范围最小且有依据的修正。
• 在提出主张前，引用已更改的路径和行号，并且只摘录足以证明问题的最少内容。
• 直接陈述已核实的事实。对于影响重大的推断，使用 Inference: 前缀，并将其与引用的证据关联。
• 文字篇幅应与证据相称。不要复述代码、重复结论、凭空编造 INFO 条目，也不要添加“扎实”“健壮”“干净”或“结构良好”等泛泛的赞扬。
• 如果没有可操作的发现，请直接说明，并且只列出重要的剩余风险或验证缺口。
• 两种输出模式都不得添加公告、泛泛的前言、祝贺或整体质量评价。

持久化报告模式（/code-review 和 /code-review-md）

• 报告以标题和具有解析意义的元数据开头，然后列出发现。
• 生成后仅提供事实性说明：各严重性级别的发现数量、整体风险、生成的文件路径、最新验证情况，以及浏览器打开结果或 HTML 警告。
• 不要重复报告正文，也不要承诺固定的发现数量。
• 仅当生成了持久化产物且 .reviews/ 尚未被忽略时，才可以在此说明中建议将 .reviews/ 加入忽略规则。

4. 编写 Markdown 报告

如果仓库根目录中不存在 .reviews/ 目录，请创建该目录。使用以下最简报告结构；省略发现数量为零的严重性标题：

# Code Review Report

**Date:** YYYY-MM-DD
**Reviewer:** automated review
**Scope:** [e.g., "Staged changes", "Commits a1b2c3d..f4e5d6a on branch feature-auth"]
**Repository:** [repo name]
**Language:** en
**Risk:** LOW / MEDIUM / HIGH / CRITICAL
**Findings:** N critical, N high, N medium, N low, N info

## Findings

### HIGH

#### [CR-001] Short title describing the finding
**File:** `path/to/file.py` (lines 42-58)
**Category:** Security | Correctness | Complexity | Maintainability | Best Practice

**Evidence excerpt:**
\```python
# smallest excerpt needed to support the claim
\```

**Observed behavior:** [What the changed code demonstrably does.]
**Practical consequence:** [The concrete failure mode, risk, or maintenance cost.]
**Smallest justified correction:** [The narrowest change supported by the evidence.]

条件章节

• Decision Summary： 仅当跨领域风险需要用一句不重复的陈述说明决策时添加。
• Positive Observations： 仅当存在具体且有证据支持的模式，能够降低风险或减少评审工作时添加。
• Open Questions： 仅当缺少的证据会改变严重性或所需操作时添加；针对该缺口仅列一个具体问题。
• File Summary： 仅当有助于读者浏览多个文件且不会重复发现时添加。

省略填充内容、空标题，以及已在某项发现中说明过的结论。

保存到：.reviews/<YYYY-MM-DD>_<short-sha>.md

5. 生成 HTML（默认；/code-review-md 跳过）

这是 /code-review 的默认行为，也适用于隐式触发；仅通过 code-review-md 技能或 /code-review-md 调用时才跳过此步骤。HTML 报告为双语：撰写韩文报告和英文报告（参见“报告语言”），然后将它们合并为一个 HTML 文件。

文件名——主韩文报告，以及结构完全相同的 .en.md 伴随文件（使用相同的问题 ID 和代码块）：

.reviews/<YYYY-MM-DD>_<short-sha>.md      # Korean (main)
.reviews/<YYYY-MM-DD>_<short-sha>.en.md   # English

对主文件运行生成器；它会自动检测 .en.md 伴随文件，并生成一个独立完整的 HTML：

python <skill-path>/scripts/generate_html_report.py .reviews/<report>.md
open .reviews/<report>.html

HTML 包含：全页面语言切换（默认显示韩文）、浅色／深色／自动主题和代码语法配色方案选择器、可折叠的紧凑侧边栏、每项问题的“复制 Markdown”按钮、每项问题的评论（存储在浏览器中），以及“复制反馈”按钮，该按钮会生成一个重新生成用的内容——将其粘贴到新的 /code-review 运行中，即可根据审阅者的评论修改审查结果。

如果只有一种语言的文件，生成器仍可正常工作，且会隐藏语言切换（单语言回退）。使用 --alt <path> 指定译文，或使用 --theme／--code-scheme 更改默认设置。

6. 根据输出模式完成

• Markdown + HTML（/code-review）： 应用上述仅基于事实的交接要求，包括浏览器打开结果或警告。唯一允许添加的内容是有条件的 .reviews/ 忽略建议。
• 仅 Markdown（/code-review-md）： 应用相同的仅基于事实的交接要求，但不包括 HTML 产物或浏览器打开情况。

报告语言

使用与用户提示相同的语言撰写报告。如果用户使用韩文，则报告应使用韩文；如果使用英文，则使用英文。语言不明确时，默认使用英文。

酌情翻译叙述性标题、问题描述、条件性文字以及表格标题或内容。

以下对解析器有特殊意义的元数据键必须保持英文：Date、Reviewer、Scope、Repository 和 Language。酌情翻译其值，并在韩文报告中设置 **Language:** ko。

以下内容始终使用英文：

• 对解析器有特殊意义的元数据键：Date、Reviewer、Scope、Repository、Language
• 问题 ID：CR-001、CR-002 等
• 严重性标签：CRITICAL、HIGH、MEDIUM、LOW、INFO
• 代码片段（代码就是代码）
• 文件路径和技术标识符

在报告元数据标题中添加 **Language:** 字段，以便 HTML 生成器设置正确的 lang 属性：

**Language:** ko

使用 BCP 47 语言标签：en、ko、ja、zh 等。

双语 HTML 报告（/code-review）

默认情况下，HTML 报告为双语：生成韩文报告和英文报告，以便读者切换语言。默认显示韩文。

• 两个文件的结构必须完全相同——标题、问题 ID（[CR-001]）和代码块都相同。仅翻译文字内容（标题、描述、摘要、表格标签）；代码、ID、文件路径和严重性标签保持原样。
• 在每个文件中设置 **Language:** 标头（主文件中为 ko，.en.md 中为 en）。
• 主文件使用 <YYYY-MM-DD>_<short-sha>.md 命名；译文文件名添加语言后缀（.en.md）。
• HTML 中的每项问题评论都以问题 ID 为键；两种语言的 ID 保持一致，读者切换语言时评论才能继续对应原问题。

如果用户明确要求使用单一语言，则只生成一个文件——生成器会回退为单语言报告，不提供语言切换。

快速参考

文件名约定：

• 基于提交：.reviews/2026-04-08_a1b2c3d.md
• 暂存区：.reviews/2026-04-08_staged.md
• 工作树：.reviews/2026-04-08_working.md

**报告语言：**叙述性文字应与用户提示语言一致。元数据键 Date、Reviewer、Scope、Repository 和 Language 保持英文；发现 ID（CR-001）、严重性标签、代码和文件路径保持英文。添加 **Language:** <bcp47>，以便 HTML 生成器正确设置 lang。

**大型差异（>1000 行）：**重点关注 CRITICAL/HIGH。按模式归类相似的 MEDIUM/LOW 发现（例如“12 处未使用的导入”），而不是逐条列出。

常见错误

没有位置的泛泛发现

• 问题：“考虑添加错误处理”，但没有文件/行号
• **修正：**每条发现都应引用文件和行范围，展示当前代码并提出修正建议

审查未更改的代码

• **问题：**评论差异范围以外的代码
• **修正：**审查范围仅限差异。不要扩大到整个仓库。

在细微差异中凭空捏造发现

• **问题：**针对仅有空白字符或版本号变更的差异编造问题
• **修正：**直接说明已核实没有发现问题。不要凑数。

加载所有参考文件

• **问题：**差异仅涉及 JS，却读取 python.md
• **修正：**仅加载 diff_stats.py 所报告语言对应的参考文件

将误报当作事实陈述

• **问题：**无法核实却断言“这是一个 bug”
• **修正：**如果缺失的证据会影响严重性或处理方式，请在 Open Questions 下提出一个具体问题；否则省略该说法。

把泛泛的赞扬当作发现

• **问题：**赞扬会占用注意力，却不会改变审查决定
• **修正：**除非某种具体模式确实能降低风险或减少审查工作量，否则不要提及。

警示事项

绝不：

• 为 /code-review-md 生成 HTML 报告（仅限 Markdown）
• 自动修改 .gitignore（提出建议，不要直接应用）
• 评论差异范围以外的代码
• 为了凑篇幅而编造发现
• 用 INFO 代替证据

始终：

• 每条发现都注明文件和行范围
• 仅引用最精简的证据片段，并提出有充分依据的最小修正
• 叙述性文字应与用户提示语言一致
• 持久化报告中的解析器关键元数据键保持英文

集成

搭配使用：

• git-commit — 提交前进行审查，作为最终质量关卡
• 通过插件命令触发；针对任意 git diff 输出运行，因此适用于任何有 Git 历史的仓库