SuperAPI AI Directory

req-code-review

Coding & development

View repository

Updated 10-16 09:30

About this skill

Req Code Review

Initiate a systematic code review oriented toward delivery quality. The review must be based on requirements and design evidence, not just the surface of the code; it must use SubAgents to execute in parallel, and then the main agent consolidates the conclusions, deduplicates them, and writes them to disk.

When To Request Review

Prefer to initiate at these times:

  • After completing a relatively large implementation task
  • Before merging into the main branch
  • After completing a refactor or cross-module changes
  • After fixing a complex issue, when you want to confirm no regressions were introduced
  • When you need to determine whether the current implementation meets the plan and acceptance requirements

If you are only making very small local changes, do not skip the review outright; at least do a lightweight scope review.

Core Rules

  1. First define the "review semantic inputs", then map them to specific files, branches, commit ranges, or directories. Do not hardcode project-specific file names in the skill.
  2. Read the implementation plan first, then look at other materials and code.
  3. Define review roles dynamically according to the project situation; do not mechanically apply fixed job titles. Roles must cover design consistency, correctness, maintainability, testing, and release risk.
  4. You must use SubAgents to initiate the review. For medium-to-large tasks, default to 3 to 5 SubAgents in parallel; for small tasks, at least 2.
  5. Only output issues that have evidence. Each issue must give impact, severity level, location, and actionable recommendations.
  6. The final result must be saved as a Markdown file.

Quick Request

When initiating, first quickly fill in these three types of inputs:

  • implementation_plan: the basis for this implementation
  • output_dir: the review document output directory
  • other: other materials, including design documents, acceptance criteria, historical review records, code directories, branches, commit ranges

If the user does not explicitly give a code scope, infer it first from the current branch or the most recent complete change scope. If the user does not specify an output directory, determine it in the following order:

  1. Reuse a review output directory that already exists in the repository
  2. If a general documentation directory exists, create within it the reviews/ subdirectory
  3. If it still cannot be determined, fall back to ./docs/reviews/

Step 1. Build Review Context

First organize the user input into the following three categories, then parse the actual files:

  • implementation_plan: implementation plan
  • output_dir: output directory
  • other: all other materials, including supplementary design documents, acceptance criteria, historical review records, code scope, branches, commit ranges, module directories, etc.

If the user gives specific file paths, classify them directly into the above three categories; if the user gives directories or wildcard patterns, first resolve candidate files, then filter for materials directly related to this implementation.

If not specified output_dir, infer in the following order:

  1. If a review output directory already exists in the repository, reuse it directly
  2. If a documentation directory exists in the repository, such as docs/, then use the reviews/ subdirectory under it
  3. If it still cannot be determined, fall back to ./docs/reviews/

The classification priority order is as follows:

  1. The implementation plan explicitly given by the user
  2. The output directory explicitly given by the user
  3. All remaining inputs are classified into other

Step 2. Read Evidence Before Reviewing

Establish the evidence chain in the following order:

  1. Read the implementation plan and extract functional points, key constraints, boundary conditions, and explicit prohibitions.
    • If missing implementation_plan, by default stop the formal review and prompt the user to supplement it.
    • Only when the user explicitly accepts a "lightweight review based on the current code" may you continue without an implementation plan.
  2. Read other materials directly relevant to this implementation, prioritizing design documents, acceptance criteria, historical review records, and the current code scope.
  3. If other contains historical review records, split them into:
    • Fixed issues
    • Unclosed legacy issues
    • Recurring issue patterns
  4. If other contains the current code scope:
    • If the user provides a commit range, look at the diff first, then the full text of key files
    • If the user provides a directory or module, first identify the entry points, core services, data access layer, tests, and configuration
  5. If other is empty or has no materials directly relevant to this implementation:
    • Clearly record the scope of insufficient evidence
    • Only allow continuing with a limited review based on the existing code scope, and do not disguise it as a "complete review"
  6. If the code scope cannot be inferred from the branch, commit range, directory, or user input:
    • First output the scope to be confirmed
    • Do not start SubAgents for now, until the scope is supplemented or the user explicitly accepts a limited review

Output a brief "review baseline summary" for subsequent SubAgents to share. The summary must at least include:

  • The goal of this implementation
  • Key design constraints that must be met
  • High-risk areas
  • Code scope
  • Focus points from historical issues

Step 3. Define Review Roles Dynamically

Do not preset fixed role names. Based on the project type, change scope, and risk points, select from role-playbook.md and customize 3 to 5 review roles.

Role definition principles:

  • Each role is responsible for a complementary perspective, avoiding repeated review of the same dimension
  • Each role must know the goal of this implementation, the review scope, and the output format
  • Each role must have clear "key inspection items" and "scope that does not need to be expanded"

At minimum cover these dimensions:

  • Design consistency
  • Architecture and maintainability
  • Correctness, robustness, and security
  • Performance, testing, and engineering standards

If there are many historical review records, add a "historical issue regression" role; if databases, permissions, external interfaces, or migrations are involved, prioritize adding the corresponding specialized role.

Step 4. Launch SubAgents

Use SubAgents to launch reviews in parallel. Each SubAgent only receives:

  • The review role definition it is responsible for
  • The review baseline summary
  • The necessary original documents and code scope
  • Output format requirements

Do not tell the SubAgent your conclusions in advance. Let it judge independently.

The task given to each SubAgent must include:

  1. Role objective
  2. Required checklist
  3. Severity level definitions:Critical | High | Medium | Low
  4. Evidence requirements:
    • Document or code location
    • Impact explanation
    • Fix suggestions
  5. Output restrictions:
    • Only report real issues
    • Avoid generic suggestions
    • Prioritize high-risk issues

See the prompt skeleton at subagent-review-template.md. Instantiate the template first, then launch the SubAgent.

Step 5. Merge And Normalize Findings

The main agent is responsible for merging all SubAgent results:

  1. Deduplication: when the same issue is found by multiple roles, keep the entry with the most complete evidence and use the rest as cross-corroboration.
  2. Unify severity levels:
    • Critical: functional errors, data corruption, security vulnerabilities, release blockers
    • High: clear deviation from the design, missing key scenarios, major testing gaps, significant stability risks
    • Medium: poor maintainability, incomplete boundary handling, less critical performance issues, engineering standards issues
    • Low: non-blocking optimization items, readability and consistency improvements
  3. Group by category: design consistency, architecture and maintainability, code quality, robustness and boundary handling, performance and resource usage, test quality, engineering standards, security.
  4. Compare against historical review records and mark:
    • Recurring issues
    • Resolved issues
    • Newly introduced issues

If multiple SubAgents have conflicting conclusions on the same issue:

  • Favor the side with more complete evidence and more accurate localization
  • If it still cannot be determined, explicitly record it in the final document as an issue pending confirmation; do not force it into a definite conclusion

Step 6. Write The Review Document

Save the final result under output_dir . If the user did not specify, infer the directory according to the aforementioned rules; if there is still no more suitable location, save it to:

./docs/reviews/YYYY-MM-DD-<topic>-code-review.md

Before saving, also handle the following branches:

  1. If output_dir does not exist, create the directory first and then write
  2. If directory creation or file writing fails, output the complete review report directly in the session and clearly explain the reason it could not be written to disk and the originally planned path
  3. Before writing to disk, state in the conclusion the review scope and output path actually used this time, to avoid the user misjudging the coverage.

The output structure must be fixed as:

## 1. 总体评价(Summary)
- 整体评价:优秀 / 良好 / 存在风险 / 不可接受
- 核心问题概览(3~5 条)

## 2. 详细问题列表(Findings)
### [类别]
- 问题描述
- 影响范围
- 严重级别
- 定位信息
- 建议修改方案

## 3. 与历史审查对比(Diff Review)
- 重复出现的问题
- 已解决的问题
- 新引入的问题

## 4. 风险评估(Risks)
- 主要上线风险点
- 是否建议阻止上线(Yes / No + 理由)

## 5. 整改 Checklist
- [ ] ...

## 6. 建议改进(Nice-to-have)
- ...

When writing the conclusion, follow these rules:

  • The summary must be supported by evidence; do not reach a conclusion first and then look for reasons.
  • The Checklist must be actionable and directly correspond to Findings
  • If a certain type of issue is not found, it is better to omit that type of Findings than to fabricate them.

After Review

After receiving the review conclusion, handle it according to severity level:

  • Critical: fix immediately; block release or merge by default
  • High: fix before release or merge, unless there is a clear exemption reason
  • Medium: include in this round's remediation plan, and at least record the handling decision in the document
  • Low: treat as an optimization item for subsequent iterations

If you believe a certain review comment does not hold, you need to provide technical grounds, code evidence, or test results, rather than simply ignoring it.

Step 7. Final Sanity Check

Self-check before saving:

  1. Whether key review dimensions are covered
  2. Whether there are unsupported issues
  3. Whether historical issue comparison is omitted
  4. Whether a clear release recommendation is given
  5. Whether the Checklist can directly guide remediation

If the review scope is too large, first explain the covered scope and the uncovered scope, then output the report, to avoid creating the illusion of a "full review".

Red Flags

Do not do this:

  • Skip the review because "the changes are not large"
  • Only read the code without comparing it against the implementation plan
  • Let the SubAgent see conclusions already formed by the main agent
  • Giving vague advice without evidence
  • When there are Critical or unresolved High issues, giving a vague release conclusion