feat: 集成code-review skill到项目

- 项目级 skill: .claude/skills/code-review/ (398行SKILL.md + 参考文件) - 自动触发: AI修改.py/.cbl/.cpy/.lark后自动review - CLAUDE.md: 定义触发规则、review流程、严重级别 - .code-review.yaml: tier=standard, 高风险模块配置效果: clone即用, 每次代码变更后自动审查, 防止低质量代码入库 Co-Authored-By: Claude <noreply@anthropic.com>
2026-06-25 10:24:15 +08:00
parent 874b16f48c
commit 2f61ad7f1a
16 changed files with 1146 additions and 0 deletions
@@ -0,0 +1,398 @@
+---
+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. |