Add comprehensive code review specifications and templates

- Introduced best practices requirements specification covering code quality, performance, maintainability, error handling, and documentation standards. - Established quality standards with overall quality metrics and mandatory checks for security, code quality, performance, and maintainability. - Created security requirements specification aligned with OWASP Top 10 and CWE Top 25, detailing checks and patterns for common vulnerabilities. - Developed templates for documenting best practice findings, security findings, and generating reports, including structured markdown and JSON formats. - Updated dependencies in the project, ensuring compatibility and stability. - Added test files and README documentation for vector indexing tests.
2026-02-14 02:42:04 +08:00 · 2026-01-06 23:11:15 +08:00
parent 02d66325a0
commit ef770ff29b
32 changed files with 4530 additions and 164 deletions
--- a/.claude/skills/code-reviewer/specs/quality-standards.md
+++ b/.claude/skills/code-reviewer/specs/quality-standards.md
@@ -0,0 +1,252 @@
+# Quality Standards
+
+## Overall Quality Metrics
+
+### Quality Score Formula
+
+```
+Overall Quality = (
+  Correctness × 0.30 +
+  Security × 0.25 +
+  Maintainability × 0.20 +
+  Performance × 0.15 +
+  Documentation × 0.10
+)
+```
+
+### Score Ranges
+
+| Range | Grade | Description |
+|-------|-------|-------------|
+| 90-100 | A | Excellent - Production ready |
+| 80-89 | B | Good - Minor improvements needed |
+| 70-79 | C | Acceptable - Some issues to address |
+| 60-69 | D | Poor - Significant improvements required |
+| 0-59 | F | Failing - Major issues, not production ready |
+
+## Review Completeness
+
+### Mandatory Checks
+
+**Security**:
+- ✅ OWASP Top 10 coverage
+- ✅ CWE Top 25 coverage
+- ✅ Language-specific security patterns
+- ✅ Dependency vulnerability scan
+
+**Code Quality**:
+- ✅ Naming convention compliance
+- ✅ Complexity analysis
+- ✅ Code duplication detection
+- ✅ Dead code identification
+
+**Performance**:
+- ✅ N+1 query detection
+- ✅ Algorithm efficiency check
+- ✅ Memory leak detection
+- ✅ Resource cleanup verification
+
+**Maintainability**:
+- ✅ Documentation coverage
+- ✅ Test coverage analysis
+- ✅ Dependency health check
+- ✅ Error handling review
+
+## Reporting Standards
+
+### Finding Requirements
+
+Each finding must include:
+- **Unique ID**: SEC-001, BP-001, etc.
+- **Type**: Specific issue type (sql-injection, high-complexity, etc.)
+- **Severity**: Critical, High, Medium, Low
+- **Location**: File path and line number
+- **Code Snippet**: Vulnerable/problematic code
+- **Message**: Clear description of the issue
+- **Recommendation**: Specific fix guidance
+- **Example**: Before/after code example
+
+### Report Structure
+
+**Executive Summary**:
+- High-level overview
+- Risk assessment
+- Key statistics
+- Compliance status
+
+**Detailed Findings**:
+- Organized by severity
+- Grouped by category
+- Full details for each finding
+
+**Action Plan**:
+- Prioritized fix list
+- Effort estimates
+- Timeline recommendations
+
+**Metrics Dashboard**:
+- Quality scores
+- Trend analysis (if historical data)
+- Compliance status
+
+**Appendix**:
+- Full findings list
+- Configuration details
+- Tool versions
+- References
+
+## Output File Standards
+
+### File Naming
+
+```
+.code-review/
+├── inventory.json              # File inventory
+├── security-findings.json      # Security findings
+├── best-practices-findings.json # Best practices findings
+├── summary.json                # Summary statistics
+├── REPORT.md                   # Main report
+├── FIX-CHECKLIST.md           # Action checklist
+└── state.json                  # Session state
+```
+
+### JSON Schema
+
+**Finding Schema**:
+```json
+{
+  "id": "string",
+  "type": "string",
+  "category": "security|code_quality|performance|maintainability",
+  "severity": "critical|high|medium|low",
+  "file": "string",
+  "line": "number",
+  "column": "number",
+  "code": "string",
+  "message": "string",
+  "recommendation": {
+    "description": "string",
+    "fix_example": "string"
+  },
+  "references": ["string"],
+  "cwe": "string (optional)",
+  "owasp": "string (optional)"
+}
+```
+
+## Validation Requirements
+
+### Phase Completion Criteria
+
+**Phase 1 (Code Discovery)**:
+- ✅ At least 1 file discovered
+- ✅ Files categorized by priority
+- ✅ Metadata extracted
+- ✅ Inventory JSON created
+
+**Phase 2 (Security Analysis)**:
+- ✅ All critical/high priority files analyzed
+- ✅ Findings have severity classification
+- ✅ CWE/OWASP mappings included
+- ✅ Fix recommendations provided
+
+**Phase 3 (Best Practices)**:
+- ✅ Code quality checks completed
+- ✅ Performance analysis done
+- ✅ Maintainability assessed
+- ✅ Recommendations provided
+
+**Phase 4 (Report Generation)**:
+- ✅ All findings consolidated
+- ✅ Scores calculated
+- ✅ Reports generated
+- ✅ Checklist created
+
+## Skill Execution Standards
+
+### Performance Targets
+
+- **Phase 1**: < 30 seconds per 1000 files
+- **Phase 2**: < 60 seconds per 100 files (security)
+- **Phase 3**: < 60 seconds per 100 files (best practices)
+- **Phase 4**: < 10 seconds (report generation)
+
+### Resource Limits
+
+- **Memory**: < 2GB for projects with 1000+ files
+- **CPU**: Efficient pattern matching (minimize regex complexity)
+- **Disk**: Use streaming for large files (> 10MB)
+
+### Error Handling
+
+**Graceful Degradation**:
+- If tool unavailable: Skip check, note in report
+- If file unreadable: Log warning, continue with others
+- If analysis fails: Report error, continue with next file
+
+**User Notification**:
+- Progress updates every 10% completion
+- Clear error messages with troubleshooting steps
+- Final summary with metrics and file locations
+
+## Integration Standards
+
+### Git Integration
+
+**Pre-commit Hook**:
+```bash
+#!/bin/bash
+ccw run code-reviewer --scope staged --severity critical,high
+exit $?  # Block commit if critical/high issues found
+```
+
+**PR Comments**:
+- Automatic review comments on changed lines
+- Summary comment with overall findings
+- Status check (pass/fail based on threshold)
+
+### CI/CD Integration
+
+**Requirements**:
+- Exit code 0 if no critical/high issues
+- Exit code 1 if blocking issues found
+- JSON output for parsing
+- Configurable severity threshold
+
+### IDE Integration
+
+**LSP Support** (future):
+- Real-time security/quality feedback
+- Inline fix suggestions
+- Quick actions for common fixes
+
+## Compliance Mapping
+
+### Supported Standards
+
+**PCI DSS**:
+- Requirement 6.5: Common coding vulnerabilities
+- Map findings to specific requirements
+
+**HIPAA**:
+- Technical safeguards
+- Map data exposure findings
+
+**GDPR**:
+- Data protection by design
+- Map sensitive data handling
+
+**SOC 2**:
+- Security controls
+- Map access control findings
+
+### Compliance Reports
+
+Generate compliance-specific reports:
+```
+.code-review/compliance/
+├── pci-dss-report.md
+├── hipaa-report.md
+├── gdpr-report.md
+└── soc2-report.md
+```