diffity-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Diffity Review Skill

Diffity 审查技能

You are reviewing a diff and leaving inline comments using the

diffity agent

CLI.

你将使用

diffity agent

CLI审查代码差异并留下行内评论。

Arguments

参数

```
focus
```
(optional): Focus the review on a specific area. One of:
```
security
```
,
```
performance
```
,
```
naming
```
,
```
errors
```
,
```
types
```
,
```
logic
```
. If omitted, review everything.

```
focus
```
(可选)：将审查重点放在特定领域。可选值：
```
security
```
、
```
performance
```
、
```
naming
```
、
```
errors
```
、
```
types
```
、
```
logic
```
。如果省略，则审查所有内容。

CLI Reference

CLI 参考

diffity agent list [--status open|resolved|dismissed] [--json]
diffity agent comment --file <path> --line <n> [--end-line <n>] [--side new|old] --body "<text>"
diffity agent general-comment --body "<text>"
diffity agent resolve <id> [--summary "<text>"]
diffity agent dismiss <id> [--reason "<text>"]
diffity agent reply <id> --body "<text>"

```
--file
```
,
```
--line
```
,
```
--body
```
are required for
```
comment
```
```
--end-line
```
defaults to
```
--line
```
(single-line comment)
```
--side
```
defaults to
```
new
```
```
general-comment
```
creates a diff-level comment not tied to any file or line
```
<id>
```
accepts full UUID or 8-char prefix

diffity agent list [--status open|resolved|dismissed] [--json]
diffity agent comment --file <path> --line <n> [--end-line <n>] [--side new|old] --body "<text>"
diffity agent general-comment --body "<text>"
diffity agent resolve <id> [--summary "<text>"]
diffity agent dismiss <id> [--reason "<text>"]
diffity agent reply <id> --body "<text>"

使用
```
comment
```
命令时，
```
--file
```
、
```
--line
```
、
```
--body
```
为必填项
```
--end-line
```
默认值为
```
--line
```
（单行评论）
```
--side
```
默认值为
```
new
```
```
general-comment
```
命令用于创建不绑定到任何文件或行的差异级评论
```
<id>
```
可以接受完整UUID或8字符前缀

Prerequisites

前置条件

Check that
```
diffity
```
is available: run
```
which diffity
```
. If not found, install it with
```
npm install -g diffity
```
.
Check that a review session exists: run
```
cat .diffity/current-session
```
. If the file doesn't exist or is stale, tell the user to start diffity first (e.g.
```
diffity
```
).

检查
```
diffity
```
是否可用：执行
```
which diffity
```
。如果未找到，使用
```
npm install -g diffity
```
进行安装。
检查是否存在审查会话：执行
```
cat .diffity/current-session
```
。如果文件不存在或已过期，请告知用户先启动diffity（例如：
```
diffity
```
）。

Instructions

操作步骤

Read the current diff using
```
git diff
```
. Check
```
.diffity/current-session
```
to determine which ref is active.
For each changed file, read the entire file (not just the diff hunks) to understand the full context. This prevents false positives from missing surrounding code.
Analyze the code changes thoroughly. If a
```
focus
```
argument was provided, concentrate on that area. Otherwise look for:
- Bugs, logic errors, off-by-one errors
- Security issues (injection, XSS, auth bypass)
- Performance problems
- Missing error handling at system boundaries
- Race conditions
- API contract violations
- Unclear or misleading naming
Only comment on code that was changed in the diff. Do not flag pre-existing issues in unchanged code — this is a review of the diff, not an audit of the entire file. The only exception is if a change in the diff introduces a bug in combination with existing code.
Prioritize signal over volume. A clean diff should get a clean review. Do not manufacture findings to appear thorough. If a diff with 5 changed lines only has 1 real issue, leave 1 comment.
Do not repeat the same issue across files. If the same pattern appears in multiple places, leave one inline comment on the first occurrence and mention it in the general summary instead of commenting on every instance.
Categorize each finding with a severity prefix in the comment body:
- ```
[must-fix]
```
  — Bugs, security issues, data loss risks. These must be addressed.
- ```
[suggestion]
```
  — Improvements that would meaningfully improve the code.
- ```
[nit]
```
  — Style or preference. Fine to ignore.
- ```
[question]
```
  — Something unclear that needs clarification from the author.
For each finding, leave a comment using:
```
diffity agent comment --file <path> --line <n> [--end-line <n>] [--side new] --body "<comment>"
```
- Use
```
--side new
```
  (default) for comments on added/modified code
- Use
```
--side old
```
  for comments on removed code
- Use
```
--end-line
```
  when the issue spans multiple lines
- Be specific and actionable in your comments
After leaving all inline comments, write a general comment that summarizes your overall assessment of the diff. This should cover:
- Overall quality verdict (e.g. "Looks good with minor issues" or "Needs significant changes before merging")
- Cross-cutting concerns that don't belong on any single line (architecture, naming consistency across files, missing tests, etc.)
- A count of findings by severity (e.g. "2 must-fix, 3 suggestions, 1 nit")
```
diffity agent general-comment --body "<overall review summary>"
```
If there are no inline findings, still leave a general comment with your assessment (e.g. "Clean diff — no issues found").
Run
```
diffity agent list
```
to confirm all comments were created.
Tell the user to check the browser — comments will appear within 2 seconds via polling.

使用
```
git diff
```
查看当前代码差异。查看
```
.diffity/current-session
```
以确定哪个引用处于激活状态。
对于每个已修改的文件，阅读整个文件（而不仅仅是差异块）以了解完整上下文。这可以避免因遗漏周边代码而产生误报。
彻底分析代码变更。如果提供了
```
focus
```
参数，则专注于该领域。否则，检查以下内容：
- 漏洞、逻辑错误、差一错误
- 安全问题（注入、XSS、权限绕过）
- 性能问题
- 系统边界处缺失的错误处理
- 竞态条件
- API契约违反
- 不清晰或易混淆的命名
仅对差异中修改的代码发表评论。不要标记未修改代码中已存在的问题——这是对差异的审查，而非对整个文件的审计。唯一的例外是差异中的变更与现有代码结合引入了漏洞。
优先关注有效问题而非数量。干净的差异应得到干净的审查结果。不要为了显得全面而编造问题。如果只有5行变更的差异中只有1个真实问题，仅留下1条评论即可。
不要在多个文件中重复相同问题。如果相同模式出现在多个位置，在首次出现处留下一条行内评论，并在总览摘要中提及，而非在每个实例处都评论。
在评论正文中使用严重性前缀对每个问题进行分类：
- ```
[must-fix]
```
  —— 漏洞、安全问题、数据丢失风险。这些必须被解决。
- ```
[suggestion]
```
  —— 能够切实改进代码的优化建议。
- ```
[nit]
```
  —— 风格或偏好问题。可以忽略。
- ```
[question]
```
  —— 不明确的内容，需要作者澄清。
对于每个问题，使用以下命令留下评论：
```
diffity agent comment --file <path> --line <n> [--end-line <n>] [--side new] --body "<comment>"
```
- 对新增/修改的代码使用
```
--side new
```
  （默认值）
- 对删除的代码使用
```
--side old
```
- 当问题跨越多行时使用
```
--end-line
```
- 评论要具体且具有可操作性
在留下所有行内评论后，撰写一条总览评论总结你对该差异的整体评估。内容应包括：
- 整体质量结论（例如：“整体良好，存在少量问题”或“合并前需要重大修改”）
- 不属于任何单行的跨文件问题（架构、多文件命名一致性、缺失测试等）
- 按严重性分类的问题数量（例如：“2个必须修复，3个建议，1个小问题”）
```
diffity agent general-comment --body "<overall review summary>"
```
如果没有行内问题，仍需留下总览评论说明你的评估（例如：“差异干净——未发现问题”）。
执行
```
diffity agent list
```
确认所有评论已创建。
告知用户检查浏览器——评论将在2秒内通过轮询显示。