actionable-review-format-standards
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseActionable 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
核心原则
- Every issue has a severity - Never leave findings unclassified
- Every issue has a location - Always include references
file:line - Every blocking issue has a fix - Provide code snippets for Critical/High
- Summary before details - Lead with counts and verdicts
- Categorize by concern - Group Security, Performance, Patterns separately
- 每个问题都有严重级别 - 绝不遗漏任何发现的分类
- 每个问题都有定位 - 始终包含引用
file:line - 每个阻塞问题都有修复方案 - 为Critical/High级别问题提供代码片段
- 先总结后细节 - 以统计数量和结论开头
- 按问题类型分类 - 将安全、性能、模式问题分开归类
Severity Classification
严重级别分类
Severity Levels
严重级别
| Level | Icon | Criteria | Action Required |
|---|---|---|---|
| CRITICAL | 🔴 | Security vulnerabilities, data loss risk, system crashes | Must fix before merge |
| HIGH | 🟠 | Significant bugs, missing authorization, performance blockers | Should fix before merge |
| MEDIUM | 🟡 | Code quality issues, minor bugs, missing validation | Fix soon, not blocking |
| LOW | 🟢 | Style issues, minor improvements, suggestions | Nice to have |
| INFO | 💡 | Educational comments, alternative approaches | No 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/INFOSeverity 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 recommendationmarkdown
🔴 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}
undefinedmarkdown
**[{严重级别}]** `{file:line}` - {分类}
{问题简要描述}
**问题代码**:
```{语言}
// 当前代码
{问题代码片段}修复方案:
// 建议修复代码
{修正后的代码}原因说明: {影响/风险解释}
undefinedCompact 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
undefinedmarkdown
undefinedCode 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
问题统计
| Severity | Count | Blocking |
|---|---|---|
| 🔴 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}
{file:line}[CRITICAL] {file:line}
- {标题}
{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
🟢 低优先级问题 / 建议
- [nit]: {suggestion}
{file:line} - [style]: {suggestion}
{file:line}
- [细节优化]: {建议内容}
{file:line} - [风格]: {建议内容}
{file:line}
🔒 Security Summary
🔒 安全总结
| Check | Status | Notes |
|---|---|---|
| Authorization | ✅ Pass / ❌ Fail | {details} |
| Input Validation | ✅ Pass / ❌ Fail | {details} |
| Data Exposure | ✅ Pass / ❌ Fail | {details} |
| Secrets | ✅ Pass / ❌ Fail | {details} |
| 检查项 | 状态 | 备注 |
|---|---|---|
| 权限校验 | ✅ 通过 / ❌ 失败 | {详情} |
| 输入校验 | ✅ 通过 / ❌ 失败 | {详情} |
| 数据暴露 | ✅ 通过 / ❌ 失败 | {详情} |
| 敏感信息 | ✅ 通过 / ❌ 失败 | {详情} |
⚡ Performance Summary
⚡ 性能总结
| Check | Status | Notes |
|---|---|---|
| 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:
| Category | Description | Examples |
|---|---|---|
| Security | Vulnerabilities, auth issues | Missing auth, SQL injection, XSS |
| Performance | Efficiency issues | N+1, blocking async, missing pagination |
| DDD | Domain design issues | Public setters, anemic entities |
| ABP | Framework pattern violations | Wrong base class, missing GuidGenerator |
| Validation | Input validation issues | Missing validators, weak rules |
| Error Handling | Exception handling issues | Silent catch, wrong exception type |
| Async | Async/await issues | Blocking calls, missing cancellation |
| Testing | Test quality issues | Missing tests, flaky tests |
| Style | Code style issues | Naming, formatting |
| Documentation | Doc issues | Missing 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 neededmarkdown
🚫 [blocking(阻塞)]: 合并前必须修复
💭 [suggestion(建议)]: 考虑优化
📝 [nit(细节)]: 次要风格偏好,不阻塞合并
📚 [learning(学习)]: 指导性说明,无需操作Quick Reference
快速参考
Minimum Requirements
最低要求
Every review output MUST include:
- Verdict - Approve/Request Changes
- Issue count by severity
- All Critical/High issues with fixes
- File:line references for all issues
- At least one positive observation
每个审查输出必须包含:
- 结论 - 批准/请求修改
- 按严重级别统计的问题数量
- 所有Critical/High级别问题及修复方案
- 所有问题的File:Line引用
- 至少一个正面观察
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
undefinedmarkdown
undefinedCode 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
问题统计
| Severity | Count | Blocking |
|---|---|---|
| 🔴 CRITICAL | 1 | Yes |
| 🟠 HIGH | 2 | Yes |
| 🟡 MEDIUM | 1 | No |
| 🟢 LOW | 2 | No |
| 严重级别 | 数量 | 是否阻塞 |
|---|---|---|
| 🔴 CRITICAL | 1 | 是 |
| 🟠 HIGH | 2 | 是 |
| 🟡 MEDIUM | 1 | 否 |
| 🟢 LOW | 2 | 否 |
🔴 Critical Issues
🔴 关键问题
[CRITICAL] src/Application/PatientAppService.cs:67
- Security
src/Application/PatientAppService.cs:67[CRITICAL] src/Application/PatientAppService.cs:67
- 安全
src/Application/PatientAppService.cs:67Missing 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
src/Application/PatientAppService.cs:34[HIGH] src/Application/PatientAppService.cs:34
- 性能
src/Application/PatientAppService.cs:34N+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
🔒 安全总结
| Check | Status | Notes |
|---|---|---|
| Authorization | ❌ Fail | DeleteAsync missing |
| Input Validation | ✅ Pass | FluentValidation in place |
| Data Exposure | ✅ Pass | DTOs properly scoped |
| Secrets | ✅ Pass | No hardcoded values |
| 检查项 | 状态 | 备注 |
|---|---|---|
| 权限校验 | ❌ 失败 | DeleteAsync缺失 |
| 输入校验 | ✅ 通过 | 已实现FluentValidation |
| 数据暴露 | ✅ 通过 | DTO范围设置合理 |
| 敏感信息 | ✅ 通过 | 无硬编码值 |
⚡ Performance Summary
⚡ 性能总结
| Check | Status | Notes |
|---|---|---|
| N+1 Queries | ❌ Fail | Loop in GetListAsync |
| Async Patterns | ✅ Pass | Proper async/await |
| Pagination | ✅ Pass | Using PageBy |
| Query Optimization | ✅ Pass | WhereIf 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 to DeleteAsync
[Authorize] - Fix N+1 query in GetListAsync
Should fix soon:
- Add XML documentation to public methods
undefined合并前必须修复:
- 为DeleteAsync添加
[Authorize] - 修复GetListAsync中的N+1查询
建议尽快修复:
- 为公共方法添加XML文档
undefined