cobol-java-v3/.claude/skills/code-review/SKILL.md

---
name: code-review
description: Use when reviewing AI-generated backend code, or when user says "review", "审查", "验收", "audit this code", "检查代码".
---

# code-review

> All file paths in checklist references are relative to this skill's directory (`code-review/references/`).

## Overview

Three-layer progressive review that catches AI-generated code defects AI commonly misses — transaction consistency, idempotency, distributed locks, parameter validation, SQL performance, concurrency safety, sensitive data masking, permission control, and error fallback. Outputs a scored text report with auto-fix and manual review gates, plus an exported standalone HTML report (`code-review-report.html`).

## Invocation

Two paths into this skill:

- **Auto-trigger:** After AI generates or modifies any backend code (controllers, services, data access, utilities, middleware, config), automatically enter review.
- **Manual trigger:** User says "审查", "review", "验收", "audit this code", "检查代码", "code review".

## Skip & Risk Alert

User may skip review with "跳过审查" or "不用审查". Before skipping, check if the change touches high-risk areas: authentication, payment, permissions, database schema changes, or data migration. If yes, issue a brief risk alert:

> ⚠️ 检测到高风险模块变更（{area}），建议执行审查后再合并。

If user still chooses to skip, respect it.

## When NOT to Use

- **Trivial changes** — single-line fixes, comment changes, formatting-only diffs
- **Frontend-only code** — this skill is scoped for backend code review
- **User explicitly declines** — user says "跳过审查", "no review needed", "skip review"
- **Throwaway prototypes** — experimental code that won't reach CI/CD or production

## Review Tier Configuration

Check for `.code-review.yaml` in the project root to determine the review tier. If absent, default to **standard**.

```yaml
# .code-review.yaml
tier: standard  # fast | standard | strict
```

| Tier | Scope | Behavior |
|------|-------|----------|
| **fast** | Prototypes, non-critical modules | Layer 1 scan + 🔴 blocker check only. Skip 🟡 and 🔵. |
| **standard** (default) | Regular business code | All three layers. 🔴 + 🟡 issues must be fixed. |
| **strict** | Core: payment, permissions, data migration | Full review + mandatory manual review + 🔴🟡 fixes require per-item user confirmation. |

Single-invocation override: "快速审查" → fast, "严格审查" → strict.

## Review Flow

### Step 0: Determine Scope

Analyze the changes to determine review granularity:

- **Change-level** (default): Only review AI-generated/modified code blocks and affected adjacent logic.
- **File-level**: When change involves file reorganization.
- **Service-level**: When cross-service call changes exist, associate upstream/downstream.
- **Chain-level**: When the full call chain is affected (DB → DAO → Service → Controller).

Declare scope at the top of the review report.

---

### Layer 1: Chain Decomposition & Inspection

Decompose code into seven categories. For each, identify high-risk gaps that AI commonly misses:

1. **Interface Layer** — Parameter validation, response conventions, HTTP status codes, rate limiting
2. **Business Layer** — Business logic alignment with requirements, state machine correctness, idempotency design, distributed locks
3. **Data Layer** — SQL injection, query performance, index usage, transaction boundaries and consistency
4. **Utility Layer** — Input validity, no side effects, error return values
5. **Error Handling** — Exception classification, fallback logic, error message sanitization, retry strategies
6. **Security** — AuthN/AuthZ, sensitive data masking, permission control, CSRF/XSS prevention
7. **Performance** — N+1 queries, caching strategy, connection pooling, batch operations

Also verify: does not deviate from requirements; does not violate architecture conventions.

For each category, mark: ✅ Clean / ⚠️ Issues Found / — Not Applicable.

---

### Layer 2: Quantitative Quality Analysis

Evaluate against measurable metrics. No subjective assessment.

| Metric | How to Measure |
|--------|---------------|
| **Requirement Coverage** | Map requirement items → code implementation. Flag uncovered items. |
| **Logic Alignment** | Compare against requirement docs (or baseline if no docs). Accuracy of business rules. |
| **Exception Branch Coverage** | Count normal paths vs. exception paths. Flag gaps. |
| **SQL Performance Risk** | Detect slow queries, missing indexes, full table scans. |
| **Code Redundancy Rate** | Identify extractable common logic, copy-paste code. |
| **Vulnerability Risk Rate** | Check against OWASP / security standards. |
| **High-Risk Scenario Coverage** | Concurrency, transactions, data consistency, race conditions. |

**No-Requirements Baseline:** When no requirement document exists, use:
1. Industry standards (OWASP, RESTful conventions, SQL best practices)
2. Similar business best practices (by project type: ecommerce/social/SaaS)
3. Previously accumulated prompt knowledge
4. Existing architecture conventions in the project

Mark the report with "No requirements doc — reviewed against generic baseline" and reduce weights of requirement coverage and logic alignment.

**Output Classification:**

- **Ready** — Passes review, ready for use
- **Needs Fix** — Has issues but fixable, with fix plan attached
- **Unusable** — Cannot be used, needs rewrite, with reason stated

---

### Layer 3: Optimization & Acceptance Standards

#### Standards Enforcement

- **Code standards** — naming, structure, comments
- **Security standards** — input validation, output encoding, permission checks
- **Performance standards** — query optimization, caching, async processing

#### Tool Scanning (if applicable to the language/ecosystem)

- Code scanning (linter, static analysis) — run and report
- SQL check (EXPLAIN, slow queries, index suggestions) — run and report
- Vulnerability detection (dependency vulnerabilities, injection points) — run and report

#### Manual Review Checklist

High-risk modules are force-flagged for manual review. Load the specialized checklist from `references/manual-review/{module}.md` when relevant:

| Module | File |
|--------|------|
| Payment | `references/manual-review/payment.md` |
| Order | `references/manual-review/order.md` |
| Inventory | `references/manual-review/inventory.md` |
| Permission | `references/manual-review/permission.md` |
| Distributed Lock | `references/manual-review/distributed-lock.md` |
| Data Migration | `references/manual-review/data-migration.md` |

#### Knowledge Accumulation

After each review, identify patterns for prompt accumulation:
- **Business Rules** (same module repeating same logic errors) → suggest accumulation
- **Historical Pitfalls** (same error pattern ≥2 occurrences) → suggest accumulation
- **Architecture Constraints** (violations of project architecture conventions) → suggest accumulation

Propose accumulation items at the end of the report. User confirms before adding to prompt library.

**Accumulation workflow:**
```text
Review findings → auto-extract high-frequency/high-risk issues
    → ask user to confirm (avoid noise)
    → record to prompt library (categorized: business rules / pitfalls / architecture constraints)
    → next AI generation auto-loads matched prompts
    → compare issue rates over time to verify effectiveness
```

Unconfirmed accumulations do not auto-activate.

#### Acceptance Gate

```text
AI draft → Skill review (auto) → Manual review & fix → Code review → Deploy
                                        ↑
                              AI raw code must NOT go directly to production
```

---

### Step 4: Export HTML Report

After the review is complete and all fixes are applied, generate a standalone HTML report. Follow the instructions in the [HTML Report Export](#html-report-export) section below.

---

## Severity Levels

| Level | Meaning | Examples |
|-------|---------|----------|
| 🔴 Blocker | Must fix immediately. Cannot merge/deploy. | SQL injection, hardcoded secrets, missing transaction causing data inconsistency, auth bypass |
| 🟡 Major | Should fix before merge. | Missing input validation, missing error fallback, N+1 query, unmasked sensitive data |
| 🔵 Minor | Can optimize later. | Non-standard naming, duplicate code, missing comments, optimizable loop |

**Rule:** If any 🔴 blocker exists → verdict is ❌ FAIL regardless of other scores.

---

## Auto-Fix Strategy

Fix order: 🔴 Blocker → 🟡 Major → 🔵 Minor

### Fix Boundary Rules

| Issue Type | Auto-Fix | Manual Only |
|-----------|----------|-------------|
| Missing parameter validation | ✅ Add validation | — |
| SQL injection | ✅ Parameterized queries | — |
| N+1 queries | ✅ Batch queries | — |
| Sensitive data masking | ✅ Apply masking | — |
| Transaction boundaries | ⚠️ Single-table/single-DB transactions | Cross-DB/nested/distributed |
| Idempotency design | — | ❌ Business confirmation needed |
| Distributed locks | — | ❌ Architecture confirmation needed |
| Permission model | — | ❌ Product confirmation needed |

### Post-Fix Regression

After each fix:
1. **Regression scope:** Re-run Layer 1 scan on all modified files
2. **Re-check metrics:** Re-run affected Layer 2 metrics
3. **Rollback condition:** If fix introduces new 🔴 or 🟡 issue → auto-rollback, mark as "Fix Failed", list under manual review
4. **Fix report:** Each fix marked "Fix Success / Fix Failed / Rolled Back"
5. **Re-export HTML:** Regenerate `code-review-report.html` after all fixes in the batch are applied

### Before Fixing

Always present the fix plan to the user and wait for confirmation before executing.

---

## HTML Report Export

After all review layers and fixes are complete, generate a standalone HTML report file.

### HTML Generation

1. Load the HTML template from `references/report-template.html`
2. Populate the template placeholders (`{{PLACEHOLDER}}`) with actual review data
3. Write the output as `code-review-report.html` in the project root directory

### Template Placeholders

| Placeholder | Description |
|-------------|-------------|
| `{{SCOPE}}` | Review scope level |
| `{{TIER}}` | Review tier |
| `{{TIMESTAMP}}` | Current timestamp |
| `{{FILES}}` | Comma-separated file list |
| `{{BASELINE}}` | Review baseline (requirements doc / generic) |
| `{{VERDICT}}` | `✅ PASS` or `❌ FAIL` |
| `{{VERDICT_CLASS}}` | CSS class: `pass` or `fail` |
| `{{L1_*}}` | Layer 1 status: `✅ Clean` / `⚠️ Issues Found` / `— N/A` |
| `{{L1_*_CLASS}}` | CSS class: `status-clean` / `status-issues` / `status-na` |
| `{{REQ_COVERAGE}}` | Requirement coverage percentage |
| `{{REQ_COV_CLASS}}` | CSS class: `metric-good` / `metric-warn` |
| `{{LOGIC_ALIGNMENT}}` | Logic alignment percentage |
| `{{EXC_COVERAGE}}` | Exception coverage percentage |
| `{{EXC_COV_CLASS}}` | CSS class |
| `{{SQL_RISK}}` | SQL risk level |
| `{{SQL_RISK_CLASS}}` | CSS class |
| `{{REDUNDANCY_RATE}}` | Redundancy rate |
| `{{VULN_RISK}}` | Vulnerability rate |
| `{{VULN_RISK_CLASS}}` | CSS class |
| `{{HRISK_COVERAGE}}` | High-risk scenario coverage |
| `{{HRISK_CLASS}}` | CSS class |
| `{{READY_COUNT}}` / `{{NEEDS_FIX_COUNT}}` / `{{UNUSABLE_COUNT}}` | Classification counts |
| `{{BLOCKER_COUNT}}` / `{{MAJOR_COUNT}}` / `{{MINOR_COUNT}}` | Severity counts |
| `{{ISSUES_LIST}}` | HTML markup for all issues, each as a `.issue` div |
| `{{MANUAL_REVIEW_SECTION}}` | HTML markup for manual review items, or empty string |
| `{{ACCUMULATION_SECTION}}` | HTML markup for knowledge accumulation suggestions, or empty string |

### Issue HTML Format

Each issue in `{{ISSUES_LIST}}` should follow this structure:

```html
<div class="issue issue-blocker">
  <span class="tag tag-blocker">🔴</span>
  <span class="category">[Data]</span>
  Missing transaction
  <div class="location">→ order-service.ts:156</div>
  <div class="fix">Fix: Added transaction wrap</div>
</div>
```

Use `issue-blocker` / `issue-major` / `issue-minor` and `tag-blocker` / `tag-major` / `tag-minor` accordingly.

### Manual Review HTML Format

```html
<div class="section">
  <h2>Manual Review Required</h2>
  <div class="manual-item">Payment callback idempotency</div>
  <div class="manual-item">Distributed lock timeout</div>
</div>
```

### Knowledge Accumulation HTML Format

```html
<div class="section">
  <h2>Knowledge Accumulation Suggestions</h2>
  <div class="accum-item">Business Rules — order status state machine errors</div>
  <div class="accum-item">Historical Pitfalls — missing transaction wrap in batch operations</div>
</div>
```

### File Output

The generated HTML file is saved as `code-review-report.html` in the project root directory. It is a fully self-contained file with all styles inlined — no external dependencies.

---

## Report Format (Text)

```text
╔══════════════════════════════════╗
║  Backend Code Review Report      ║
╠══════════════════════════════════╣
║  Scope: {change-level/file-level/service-level/chain-level} ║
║  Files: {file list}              ║
║  Time: {timestamp}               ║
║  Tier: {fast/standard/strict}    ║
║  Verdict: ✅ PASS / ❌ FAIL       ║
╠══════════════════════════════════╣
║  Layer 1 · Chain Decomposition   ║
║  Interface: ✅  Business: ⚠️       ║
║  Data: ✅  Utility: ✅             ║
║  Error: ⚠️  Security: ✅           ║
║  Performance: ✅                  ║
╠══════════════════════════════════╣
║  Layer 2 · Quantitative Metrics  ║
║  Requirement Coverage: 85% (3/5 uncovered) ║
║  Logic Alignment:     90%        ║
║  Exception Coverage:  60%  ⚠️    ║
║  SQL Risk:            Low        ║
║  Redundancy Rate:     12%        ║
║  Vulnerability Rate:  0%         ║
║  High-Risk Coverage:  Missing concurrency ║
╠══════════════════════════════════╣
║  Classification                  ║
║  Ready: 3  Needs Fix: 2  Unusable: 0 ║
╠══════════════════════════════════╣
║  🔴 Blocker: 1  🟡 Major: 3  🔵 Minor: 4 ║
╠══════════════════════════════════╣
║  Issues:                         ║
║  🔴 [Data] Missing transaction    ║
║     → order-service.ts:156       ║
║     → Fix: Added transaction wrap ║
║  🟡 [Security] Unvalidated input  ║
║     → auth.ts:42                 ║
║     → Fix: Added validation      ║
║  ...                             ║
║  Manual Review Required:         ║
║  → Payment callback idempotency  ║
║  → Distributed lock timeout       ║
╚══════════════════════════════════╝
```

### Report Interaction

- **Issue navigation:** Issue line numbers link to code location
- **Fix preview:** Fix plan shows diff preview
- **Batch operations:** Confirm/deny fixes by severity level; batch-skip 🔵 items
- **Per-item confirmation:** 🔴 and high-risk 🟡 fixes confirmed one at a time

---

## Language Adaptation

Detect project language/framework and load the corresponding checklist from `references/`:

| Language/Framework | Checklist File |
|-------------------|---------------|
| Java + Spring Boot | `references/java-spring.md` |
| Python + Django | `references/python-django.md` |
| Python + FastAPI | `references/python-fastapi.md` |
| Node.js + Express | `references/node-express.md` |
| Go + Gin | `references/go-gin.md` |
| No match | Use `references/review-checklist.md` (generic) |

---

## Constraints

- **No silent modifications:** Present fix plan before executing. Get user confirmation.
- **No fixes on FAIL:** When 🔴 blockers cause ❌ FAIL, report first and wait for user decision.
- **Context-aware:** With requirement docs → full review. Without → use "no-requirements baseline", reduce requirement/logic metric weights.
- **Historical learning:** High-frequency/high-risk findings auto-suggested for prompt accumulation. User confirms before activation.
- **Language-adaptive:** Auto-detect project language/framework, load matching checklist. Fall back to generic.
- **Config-driven:** `.code-review.yaml` controls review tier. No hardcoded rules.

---

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Rushing review without checking each layer | Complete all three layers in order. Layer 1 catches structural issues, Layer 2 catches metrics gaps, Layer 3 catches process gaps. |
| Skipping no-requirements baseline and guessing requirements | When no req docs exist, explicitly use the 4-part baseline (industry standards, business practices, accumulated prompts, architecture conventions). Mark the report accordingly. |
| Fixing 🔵 minor issues before 🔴 blockers | Fix order is strict: 🔴 → 🟡 → 🔵. A 🔴 blocker means ❌ FAIL — fix it first or don't fix at all. |
| Applying fixes without user confirmation | Always present the fix plan and wait for confirmation before executing. |
| Forgetting to mark high-risk modules for manual review | Payment, order, inventory, permissions, distributed locks, and data migration always require manual review. Load the corresponding checklist. |
| Loading the wrong language checklist | Auto-detect language/framework from project config (package.json, pom.xml, go.mod, etc.). Fall back to generic checklist if detection fails. |
| Omitting the "No requirements doc" annotation | Always state the review baseline in the report header so readers know what standards were applied. |
| Forgetting to export the HTML report after fixes | After all fixes are applied, always generate the HTML report (`code-review-report.html`) so the final output reflects the latest state. |