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

name, description

name	description
code-review	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.

# .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:

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

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 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:

<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

<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

<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)

╔══════════════════════════════════╗
║  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.