actionable-review-format-standards

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Actionable Review Format Standards

可操作的审查格式标准

Standardized output format for code reviews ensuring consistent, actionable, and prioritized feedback across all reviewer agents.
确保所有审查Agent输出一致、可操作且经过优先级排序反馈的代码审查标准化输出格式。

When to Use This Skill

何时使用此技能

  • Generating code review reports
  • Formatting PR feedback
  • Creating security audit reports
  • Producing performance review outputs
  • Any review output requiring severity classification
  • 生成代码审查报告
  • 格式化PR反馈
  • 创建安全审计报告
  • 生成性能审查输出
  • 任何需要进行严重级别分类的审查输出场景

Core Principles

核心原则

  1. Every issue has a severity - Never leave findings unclassified
  2. Every issue has a location - Always include
    file:line
    references
  3. Every blocking issue has a fix - Provide code snippets for Critical/High
  4. Summary before details - Lead with counts and verdicts
  5. Categorize by concern - Group Security, Performance, Patterns separately

  1. 每个问题都有严重级别 - 绝不遗漏任何发现的分类
  2. 每个问题都有定位 - 始终包含
    file:line
    引用
  3. 每个阻塞问题都有修复方案 - 为Critical/High级别问题提供代码片段
  4. 先总结后细节 - 以统计数量和结论开头
  5. 按问题类型分类 - 将安全、性能、模式问题分开归类

Severity Classification

严重级别分类

Severity Levels

严重级别

LevelIconCriteriaAction Required
CRITICAL🔴Security vulnerabilities, data loss risk, system crashesMust fix before merge
HIGH🟠Significant bugs, missing authorization, performance blockersShould fix before merge
MEDIUM🟡Code quality issues, minor bugs, missing validationFix soon, not blocking
LOW🟢Style issues, minor improvements, suggestionsNice to have
INFO💡Educational comments, alternative approachesNo action required
级别图标判断标准所需操作
CRITICAL(关键)🔴安全漏洞、数据丢失风险、系统崩溃合并前必须修复
HIGH(高)🟠重大bug、缺失权限校验、性能阻塞合并前建议修复
MEDIUM(中)🟡代码质量问题、次要bug、缺失校验尽快修复,不阻塞合并
LOW(低)🟢风格问题、小幅改进、建议可选修复
INFO(信息)💡指导性注释、替代方案无需操作

Severity Decision Tree

严重级别判定树

Is it a security vulnerability?
├── Yes → CRITICAL
└── No → Can it cause data loss or corruption?
         ├── Yes → CRITICAL
         └── No → Can it cause system crash/downtime?
                  ├── Yes → HIGH
                  └── No → Does it break functionality?
                           ├── Yes → HIGH
                           └── No → Does it affect performance significantly?
                                    ├── Yes → MEDIUM
                                    └── No → Is it a code quality issue?
                                             ├── Yes → MEDIUM/LOW
                                             └── No → LOW/INFO
是否为安全漏洞?
├── 是 → CRITICAL
└── 否 → 是否会导致数据丢失或损坏?
         ├── 是 → CRITICAL
         └── 否 → 是否会导致系统崩溃/停机?
                  ├── 是 → HIGH
                  └── 否 → 是否破坏功能?
                           ├── 是 → HIGH
                           └── 否 → 是否严重影响性能?
                                    ├── 是 → MEDIUM
                                    └── 否 → 是否为代码质量问题?
                                             ├── 是 → MEDIUM/LOW
                                             └── 否 → LOW/INFO

Severity Examples

严重级别示例

markdown
🔴 CRITICAL - Security
- SQL injection vulnerability
- Missing authorization on delete endpoint
- Hardcoded credentials in source code
- PII exposure in logs

🟠 HIGH - Must Fix
- Missing null checks causing NullReferenceException
- N+1 query in frequently called method
- Business logic error causing wrong calculations
- Missing input validation on public API

🟡 MEDIUM - Should Fix
- Blocking async call (.Result, .Wait())
- Missing error handling
- Inefficient LINQ query
- Duplicate code that should be extracted

🟢 LOW - Nice to Have
- Variable naming improvements
- Missing XML documentation
- Code formatting inconsistencies
- Minor refactoring opportunities

💡 INFO - Educational
- Alternative pattern suggestion
- Performance optimization tip
- Best practice recommendation

markdown
🔴 CRITICAL - 安全
- SQL注入漏洞
- 删除接口缺失权限校验
- 源代码中存在硬编码凭证
- 日志中暴露PII(个人可识别信息)

🟠 HIGH - 必须修复
- 缺失空值检查导致NullReferenceException
- 频繁调用方法中存在N+1查询
- 业务逻辑错误导致计算结果异常
- 公开API缺失输入校验

🟡 MEDIUM - 建议修复
- 阻塞式异步调用(.Result, .Wait())
- 缺失错误处理
- 低效LINQ查询
- 可抽取的重复代码

🟢 LOW - 可选优化
- 变量命名优化
- 缺失XML文档
- 代码格式不一致
- 小幅重构机会

💡 INFO - 指导性内容
- 替代模式建议
- 性能优化提示
- 最佳实践推荐

Location Format

定位格式

Standard Format

标准格式

{FilePath}:{LineNumber}
{文件路径}:{行号}

Examples

示例

markdown
✅ Good:
- `src/Application/PatientAppService.cs:45`
- `src/Domain/Patient.cs:23-28` (range)
- `src/Application/Validators/CreatePatientDtoValidator.cs:12`

❌ Bad:
- `PatientAppService.cs` (missing path)
- `line 45` (missing file)
- `src/Application/` (missing file and line)
markdown
✅ 规范示例:
- `src/Application/PatientAppService.cs:45`
- `src/Domain/Patient.cs:23-28`(范围)
- `src/Application/Validators/CreatePatientDtoValidator.cs:12`

❌ 不规范示例:
- `PatientAppService.cs`(缺失路径)
- `line 45`(缺失文件)
- `src/Application/`(缺失文件和行号)

Multi-Location Issues

多位置问题

When an issue spans multiple files:
markdown
**[MEDIUM]** Duplicate validation logic
- `src/Application/PatientAppService.cs:45`
- `src/Application/DoctorAppService.cs:52`
- `src/Application/AppointmentAppService.cs:38`

**Suggestion**: Extract to shared `ValidationHelper` class.

当问题跨多个文件时:
markdown
**[MEDIUM]** 重复校验逻辑
- `src/Application/PatientAppService.cs:45`
- `src/Application/DoctorAppService.cs:52`
- `src/Application/AppointmentAppService.cs:38`

**建议**: 抽取到共享的`ValidationHelper`类中。

Issue Format

问题格式

Single Issue Template

单个问题模板

markdown
**[{SEVERITY}]** `{file:line}` - {Category}

{Brief description of the issue}

**Problem**:
```{language}
// Current code
{problematic code}
Fix:
// Suggested fix
{corrected code}
Why: {Explanation of impact/risk}
undefined
markdown
**[{严重级别}]** `{file:line}` - {分类}

{问题简要描述}

**问题代码**:
```{语言}
// 当前代码
{问题代码片段}
修复方案:
// 建议修复代码
{修正后的代码}
原因说明: {影响/风险解释}
undefined

Compact Issue Format (for tables)

紧凑问题格式(用于表格)

markdown
| Severity | Location | Category | Issue | Fix |
|----------|----------|----------|-------|-----|
| 🔴 CRITICAL | `File.cs:42` | Security | Missing `[Authorize]` | Add `[Authorize(Permissions.Delete)]` |
| 🟠 HIGH | `File.cs:67` | Performance | N+1 query in loop | Use `.Include()` or batch query |

markdown
| 严重级别 | 定位 | 分类 | 问题 | 修复方案 |
|----------|----------|----------|-------|-----|
| 🔴 CRITICAL | `File.cs:42` | 安全 | 缺失`[Authorize]` | 添加`[Authorize(Permissions.Delete)]` |
| 🟠 HIGH | `File.cs:67` | 性能 | 循环中存在N+1查询 | 使用`.Include()`或批量查询 |

Report Structure

报告结构

Full Review Report Template

完整审查报告模板

markdown
undefined
markdown
undefined

Code Review: {PR Title}

代码审查: {PR标题}

Date: {YYYY-MM-DD} Reviewer: {agent-name} Files Reviewed: {count} Lines Changed: +{added} / -{removed}

日期: {YYYY-MM-DD} 审查者: {agent-name} 审查文件数: {数量} 代码变更行数: +{新增行数} / -{删除行数}

Verdict

结论

{✅ APPROVE | 💬 APPROVE WITH COMMENTS | 🔄 REQUEST CHANGES}
Summary: {1-2 sentence overview}

{✅ 批准 | 💬 带评论批准 | 🔄 请求修改}
总结: {1-2句话概述}

Issue Summary

问题统计

SeverityCountBlocking
🔴 CRITICAL{n}Yes
🟠 HIGH{n}Yes
🟡 MEDIUM{n}No
🟢 LOW{n}No

严重级别数量是否阻塞
🔴 CRITICAL{n}
🟠 HIGH{n}
🟡 MEDIUM{n}
🟢 LOW{n}

🔴 Critical Issues

🔴 关键问题

{If none: "No critical issues found."}
{若无问题: "未发现关键问题。"}

[CRITICAL]
{file:line}
- {Title}

[CRITICAL]
{file:line}
- {标题}

{Description}
Problem:
{code}
Fix:
{code}

{描述}
问题代码:
{代码}
修复方案:
{代码}

🟠 High Issues

🟠 高优先级问题

{Issues in same format}

{采用相同格式的问题}

🟡 Medium Issues

🟡 中优先级问题

{Issues in same format or table format for brevity}

{采用相同格式或表格格式以简化内容}

🟢 Low Issues / Suggestions

🟢 低优先级问题 / 建议

  • {file:line}
    [nit]: {suggestion}
  • {file:line}
    [style]: {suggestion}

  • {file:line}
    [细节优化]: {建议内容}
  • {file:line}
    [风格]: {建议内容}

🔒 Security Summary

🔒 安全总结

CheckStatusNotes
Authorization✅ Pass / ❌ Fail{details}
Input Validation✅ Pass / ❌ Fail{details}
Data Exposure✅ Pass / ❌ Fail{details}
Secrets✅ Pass / ❌ Fail{details}

检查项状态备注
权限校验✅ 通过 / ❌ 失败{详情}
输入校验✅ 通过 / ❌ 失败{详情}
数据暴露✅ 通过 / ❌ 失败{详情}
敏感信息✅ 通过 / ❌ 失败{详情}

⚡ Performance Summary

⚡ 性能总结

CheckStatusNotes
N+1 Queries✅ Pass / ❌ Fail{details}
Async Patterns✅ Pass / ❌ Fail{details}
Pagination✅ Pass / ❌ Fail{details}
Query Optimization✅ Pass / ❌ Fail{details}

检查项状态备注
N+1查询✅ 通过 / ❌ 失败{详情}
异步模式✅ 通过 / ❌ 失败{详情}
分页✅ 通过 / ❌ 失败{详情}
查询优化✅ 通过 / ❌ 失败{详情}

✅ What's Good

✅ 亮点

  • {Positive observation 1}
  • {Positive observation 2}
  • {Positive observation 3}

  • {正面观察1}
  • {正面观察2}
  • {正面观察3}

Action Items

行动项

Must fix before merge:
  • {Critical/High issue 1}
  • {Critical/High issue 2}
Should fix soon:
  • {Medium issue 1}
  • {Medium issue 2}

合并前必须修复:
  • {关键/高优先级问题1}
  • {关键/高优先级问题2}
建议尽快修复:
  • {中优先级问题1}
  • {中优先级问题2}

Technical Debt Noted

记录的技术债务

  • {Future improvement 1}
  • {Future improvement 2}

---
  • {未来优化点1}
  • {未来优化点2}

---

Category Labels

分类标签

Use consistent category labels to classify issues:
CategoryDescriptionExamples
SecurityVulnerabilities, auth issuesMissing auth, SQL injection, XSS
PerformanceEfficiency issuesN+1, blocking async, missing pagination
DDDDomain design issuesPublic setters, anemic entities
ABPFramework pattern violationsWrong base class, missing GuidGenerator
ValidationInput validation issuesMissing validators, weak rules
Error HandlingException handling issuesSilent catch, wrong exception type
AsyncAsync/await issuesBlocking calls, missing cancellation
TestingTest quality issuesMissing tests, flaky tests
StyleCode style issuesNaming, formatting
DocumentationDoc issuesMissing comments, outdated docs

使用统一的分类标签对问题进行归类:
分类描述示例
Security(安全)漏洞、权限问题缺失权限校验、SQL注入、XSS
Performance(性能)效率问题N+1查询、阻塞式异步、缺失分页
DDD领域设计问题公共setter、贫血实体
ABP框架模式违规错误的基类、缺失GuidGenerator
Validation(校验)输入校验问题缺失校验器、规则不严谨
Error Handling(错误处理)异常处理问题静默捕获、错误的异常类型
Async(异步)Async/await问题阻塞调用、缺失取消令牌
Testing(测试)测试质量问题缺失测试、不稳定测试
Style(风格)代码风格问题命名、格式
Documentation(文档)文档问题缺失注释、文档过时

Feedback Language

反馈语言

Use Constructive Language

使用建设性语言

markdown
❌ Bad:
"This is wrong."
"You should know better."
"Why didn't you use X?"

✅ Good:
"Consider using X because..."
"This could cause Y. Here's a fix:"
"Have you considered X? It would improve Y."
markdown
❌ 反面示例:
"这是错的。"
"你应该更清楚。"
"为什么不用X?"

✅ 正面示例:
"考虑使用X,因为..."
"这可能会导致Y问题。以下是修复方案:"
"你是否考虑过X?它可以提升Y。"

Differentiate Blocking vs Non-Blocking

区分阻塞与非阻塞问题

markdown
🚫 [blocking]: Must fix before merge
💭 [suggestion]: Consider for improvement
📝 [nit]: Minor style preference, not blocking
📚 [learning]: Educational note, no action needed

markdown
🚫 [blocking(阻塞)]: 合并前必须修复
💭 [suggestion(建议)]: 考虑优化
📝 [nit(细节)]: 次要风格偏好,不阻塞合并
📚 [learning(学习)]: 指导性说明,无需操作

Quick Reference

快速参考

Minimum Requirements

最低要求

Every review output MUST include:
  1. Verdict - Approve/Request Changes
  2. Issue count by severity
  3. All Critical/High issues with fixes
  4. File:line references for all issues
  5. At least one positive observation
每个审查输出必须包含:
  1. 结论 - 批准/请求修改
  2. 按严重级别统计的问题数量
  3. 所有Critical/High级别问题及修复方案
  4. 所有问题的File:Line引用
  5. 至少一个正面观察

Severity Quick Guide

严重级别速查

If you find...Severity
Security vulnerability🔴 CRITICAL
Missing authorization🔴 CRITICAL
Data corruption risk🔴 CRITICAL
Null reference exception🟠 HIGH
N+1 query pattern🟠 HIGH
Blocking async🟡 MEDIUM
Missing validation🟡 MEDIUM
Naming issues🟢 LOW
Missing docs🟢 LOW

发现问题类型严重级别
安全漏洞🔴 CRITICAL
缺失权限校验🔴 CRITICAL
数据损坏风险🔴 CRITICAL
空引用异常🟠 HIGH
N+1查询模式🟠 HIGH
阻塞式异步调用🟡 MEDIUM
缺失输入校验🟡 MEDIUM
命名问题🟢 LOW
缺失文档🟢 LOW

Example Output

输出示例

markdown
undefined
markdown
undefined

Code Review: Add Patient CRUD API

代码审查: 新增患者CRUD API

Date: 2025-12-13 Reviewer: abp-code-reviewer Files Reviewed: 5 Lines Changed: +245 / -12

日期: 2025-12-13 审查者: abp-code-reviewer 审查文件数: 5 代码变更行数: +245 / -12

Verdict

结论

🔄 REQUEST CHANGES
Summary: Good implementation of Patient CRUD with proper ABP patterns. Found 1 critical security issue (missing authorization) and 2 performance concerns that need attention.

🔄 请求修改
总结: 患者CRUD的实现符合ABP模式规范,整体良好。发现1个关键安全问题(缺失权限校验)和2个性能问题需要处理。

Issue Summary

问题统计

SeverityCountBlocking
🔴 CRITICAL1Yes
🟠 HIGH2Yes
🟡 MEDIUM1No
🟢 LOW2No

严重级别数量是否阻塞
🔴 CRITICAL1
🟠 HIGH2
🟡 MEDIUM1
🟢 LOW2

🔴 Critical Issues

🔴 关键问题

[CRITICAL]
src/Application/PatientAppService.cs:67
- Security

[CRITICAL]
src/Application/PatientAppService.cs:67
- 安全

Missing authorization on DeleteAsync
Problem:
csharp
public async Task DeleteAsync(Guid id)
{
    await _repository.DeleteAsync(id);
}
Fix:
csharp
[Authorize(ClinicManagementSystemPermissions.Patients.Delete)]
public async Task DeleteAsync(Guid id)
{
    await _repository.DeleteAsync(id);
}
Why: Any authenticated user can delete patients without permission check.

DeleteAsync接口缺失权限校验
问题代码:
csharp
public async Task DeleteAsync(Guid id)
{
    await _repository.DeleteAsync(id);
}
修复方案:
csharp
[Authorize(ClinicManagementSystemPermissions.Patients.Delete)]
public async Task DeleteAsync(Guid id)
{
    await _repository.DeleteAsync(id);
}
原因说明: 任何已认证用户都可无权限校验删除患者。

🟠 High Issues

🟠 高优先级问题

[HIGH]
src/Application/PatientAppService.cs:34
- Performance

[HIGH]
src/Application/PatientAppService.cs:34
- 性能

N+1 query pattern in GetListAsync
Problem:
csharp
foreach (var patient in patients)
{
    patient.Appointments = await _appointmentRepository.GetListAsync(a => a.PatientId == patient.Id);
}
Fix:
csharp
var patientIds = patients.Select(p => p.Id).ToList();
var appointments = await _appointmentRepository.GetListAsync(a => patientIds.Contains(a.PatientId));
var grouped = appointments.GroupBy(a => a.PatientId).ToDictionary(g => g.Key, g => g.ToList());
foreach (var patient in patients)
{
    patient.Appointments = grouped.GetValueOrDefault(patient.Id, new List<Appointment>());
}

GetListAsync中存在N+1查询模式
问题代码:
csharp
foreach (var patient in patients)
{
    patient.Appointments = await _appointmentRepository.GetListAsync(a => a.PatientId == patient.Id);
}
修复方案:
csharp
var patientIds = patients.Select(p => p.Id).ToList();
var appointments = await _appointmentRepository.GetListAsync(a => patientIds.Contains(a.PatientId));
var grouped = appointments.GroupBy(a => a.PatientId).ToDictionary(g => g.Key, g => g.ToList());
foreach (var patient in patients)
{
    patient.Appointments = grouped.GetValueOrDefault(patient.Id, new List<Appointment>());
}

🔒 Security Summary

🔒 安全总结

CheckStatusNotes
Authorization❌ FailDeleteAsync missing
[Authorize]
Input Validation✅ PassFluentValidation in place
Data Exposure✅ PassDTOs properly scoped
Secrets✅ PassNo hardcoded values

检查项状态备注
权限校验❌ 失败DeleteAsync缺失
[Authorize]
输入校验✅ 通过已实现FluentValidation
数据暴露✅ 通过DTO范围设置合理
敏感信息✅ 通过无硬编码值

⚡ Performance Summary

⚡ 性能总结

CheckStatusNotes
N+1 Queries❌ FailLoop in GetListAsync
Async Patterns✅ PassProper async/await
Pagination✅ PassUsing PageBy
Query Optimization✅ PassWhereIf pattern used

检查项状态备注
N+1查询❌ 失败GetListAsync中的循环
异步模式✅ 通过正确使用async/await
分页✅ 通过使用PageBy
查询优化✅ 通过使用WhereIf模式

✅ What's Good

✅ 亮点

  • Excellent entity encapsulation with private setters
  • Proper use of
    GuidGenerator.Create()
  • Clean FluentValidation implementation
  • Good separation of concerns

  • 实体封装良好,使用私有setter
  • 正确使用
    GuidGenerator.Create()
  • FluentValidation实现简洁
  • 关注点分离清晰

Action Items

行动项

Must fix before merge:
  • Add
    [Authorize]
    to DeleteAsync
  • Fix N+1 query in GetListAsync
Should fix soon:
  • Add XML documentation to public methods
undefined
合并前必须修复:
  • 为DeleteAsync添加
    [Authorize]
  • 修复GetListAsync中的N+1查询
建议尽快修复:
  • 为公共方法添加XML文档
undefined