claude-code-workflow 6.3.22 → 6.3.24

package/.claude/skills/review-code/specs/review-dimensions.md

@@ -0,0 +1,337 @@
+# Review Dimensions
+
+代码审查维度定义和检查点规范。
+
+## When to Use
+
+| Phase | Usage | Section |
+|-------|-------|---------|
+| action-deep-review | 获取维度检查规则 | All |
+| action-generate-report | 维度名称映射 | Dimension Names |
+
+---
+
+## Dimension Overview
+
+| Dimension | Weight | Focus | Key Indicators |
+|-----------|--------|-------|----------------|
+| **Correctness** | 25% | 功能正确性 | 边界条件、错误处理、类型安全 |
+| **Security** | 25% | 安全风险 | 注入攻击、敏感数据、权限 |
+| **Performance** | 15% | 执行效率 | 算法复杂度、资源使用 |
+| **Readability** | 15% | 可维护性 | 命名、结构、注释 |
+| **Testing** | 10% | 测试质量 | 覆盖率、边界测试 |
+| **Architecture** | 10% | 架构一致性 | 分层、依赖、模式 |
+
+---
+
+## 1. Correctness (正确性)
+
+### 检查清单
+
+- [ ] **边界条件处理**
+  - 空数组/空字符串
+  - Null/Undefined
+  - 数值边界 (0, 负数, MAX_INT)
+  - 集合边界 (首元素, 末元素)
+
+- [ ] **错误处理**
+  - Try-catch 覆盖
+  - 错误不被静默吞掉
+  - 错误信息有意义
+  - 资源正确释放
+
+- [ ] **类型安全**
+  - 类型转换正确
+  - 避免隐式转换
+  - TypeScript strict mode
+
+- [ ] **逻辑完整性**
+  - If-else 分支完整
+  - Switch 有 default
+  - 循环终止条件正确
+
+### 常见问题模式
+
+```javascript
+// ❌ 问题: 未检查 null
+function getName(user) {
+  return user.name.toUpperCase();  // user 可能为 null
+}
+
+// ✅ 修复
+function getName(user) {
+  return user?.name?.toUpperCase() ?? 'Unknown';
+}
+
+// ❌ 问题: 空 catch 块
+try {
+  await fetchData();
+} catch (e) {}  // 错误被静默吞掉
+
+// ✅ 修复
+try {
+  await fetchData();
+} catch (e) {
+  console.error('Failed to fetch data:', e);
+  throw e;
+}
+```
+
+---
+
+## 2. Security (安全性)
+
+### 检查清单
+
+- [ ] **注入防护**
+  - SQL 注入 (使用参数化查询)
+  - XSS (避免 innerHTML)
+  - 命令注入 (避免 exec)
+  - 路径遍历
+
+- [ ] **认证授权**
+  - 权限检查完整
+  - Token 验证
+  - Session 管理
+
+- [ ] **敏感数据**
+  - 无硬编码密钥
+  - 日志不含敏感信息
+  - 传输加密
+
+- [ ] **依赖安全**
+  - 无已知漏洞依赖
+  - 版本锁定
+
+### 常见问题模式
+
+```javascript
+// ❌ 问题: SQL 注入风险
+const query = `SELECT * FROM users WHERE id = ${userId}`;
+
+// ✅ 修复: 参数化查询
+const query = `SELECT * FROM users WHERE id = ?`;
+db.query(query, [userId]);
+
+// ❌ 问题: XSS 风险
+element.innerHTML = userInput;
+
+// ✅ 修复
+element.textContent = userInput;
+
+// ❌ 问题: 硬编码密钥
+const apiKey = 'sk-xxxxxxxxxxxx';
+
+// ✅ 修复
+const apiKey = process.env.API_KEY;
+```
+
+---
+
+## 3. Performance (性能)
+
+### 检查清单
+
+- [ ] **算法复杂度**
+  - 避免 O(n²) 在大数据集
+  - 使用合适的数据结构
+  - 避免不必要的循环
+
+- [ ] **I/O 效率**
+  - 批量操作 vs 循环单条
+  - 避免 N+1 查询
+  - 适当使用缓存
+
+- [ ] **资源使用**
+  - 内存泄漏
+  - 连接池使用
+  - 大文件流式处理
+
+- [ ] **异步处理**
+  - 并行 vs 串行
+  - Promise.all 使用
+  - 避免阻塞
+
+### 常见问题模式
+
+```javascript
+// ❌ 问题: N+1 查询
+for (const user of users) {
+  const posts = await db.query('SELECT * FROM posts WHERE user_id = ?', [user.id]);
+}
+
+// ✅ 修复: 批量查询
+const userIds = users.map(u => u.id);
+const posts = await db.query('SELECT * FROM posts WHERE user_id IN (?)', [userIds]);
+
+// ❌ 问题: 串行执行可并行操作
+const a = await fetchA();
+const b = await fetchB();
+const c = await fetchC();
+
+// ✅ 修复: 并行执行
+const [a, b, c] = await Promise.all([fetchA(), fetchB(), fetchC()]);
+```
+
+---
+
+## 4. Readability (可读性)
+
+### 检查清单
+
+- [ ] **命名规范**
+  - 变量名见名知意
+  - 函数名表达动作
+  - 常量使用 UPPER_CASE
+  - 避免缩写和单字母
+
+- [ ] **函数设计**
+  - 单一职责
+  - 长度 < 50 行
+  - 参数 < 5 个
+  - 嵌套 < 4 层
+
+- [ ] **代码组织**
+  - 逻辑分组
+  - 空行分隔
+  - Import 顺序
+
+- [ ] **注释质量**
+  - 解释 WHY 而非 WHAT
+  - 及时更新
+  - 无冗余注释
+
+### 常见问题模式
+
+```javascript
+// ❌ 问题: 命名不清晰
+const d = new Date();
+const a = users.filter(x => x.s === 'active');
+
+// ✅ 修复
+const currentDate = new Date();
+const activeUsers = users.filter(user => user.status === 'active');
+
+// ❌ 问题: 函数过长、职责过多
+function processOrder(order) {
+  // ... 200 行代码，包含验证、计算、保存、通知
+}
+
+// ✅ 修复: 拆分职责
+function validateOrder(order) { /* ... */ }
+function calculateTotal(order) { /* ... */ }
+function saveOrder(order) { /* ... */ }
+function notifyCustomer(order) { /* ... */ }
+```
+
+---
+
+## 5. Testing (测试)
+
+### 检查清单
+
+- [ ] **测试覆盖**
+  - 核心逻辑有测试
+  - 边界条件有测试
+  - 错误路径有测试
+
+- [ ] **测试质量**
+  - 测试独立
+  - 断言明确
+  - Mock 适度
+
+- [ ] **测试可维护性**
+  - 命名清晰
+  - 结构统一
+  - 避免重复
+
+### 常见问题模式
+
+```javascript
+// ❌ 问题: 测试不独立
+let counter = 0;
+test('increment', () => {
+  counter++;  // 依赖外部状态
+  expect(counter).toBe(1);
+});
+
+// ✅ 修复: 每个测试独立
+test('increment', () => {
+  const counter = new Counter();
+  counter.increment();
+  expect(counter.value).toBe(1);
+});
+
+// ❌ 问题: 缺少边界测试
+test('divide', () => {
+  expect(divide(10, 2)).toBe(5);
+});
+
+// ✅ 修复: 包含边界情况
+test('divide by zero throws', () => {
+  expect(() => divide(10, 0)).toThrow();
+});
+```
+
+---
+
+## 6. Architecture (架构)
+
+### 检查清单
+
+- [ ] **分层结构**
+  - 层次清晰
+  - 依赖方向正确
+  - 无循环依赖
+
+- [ ] **模块化**
+  - 高内聚低耦合
+  - 接口定义清晰
+  - 职责单一
+
+- [ ] **设计模式**
+  - 使用合适的模式
+  - 避免过度设计
+  - 遵循项目既有模式
+
+### 常见问题模式
+
+```javascript
+// ❌ 问题: 层次混乱 (Controller 直接操作数据库)
+class UserController {
+  async getUser(req, res) {
+    const user = await db.query('SELECT * FROM users WHERE id = ?', [req.params.id]);
+    res.json(user);
+  }
+}
+
+// ✅ 修复: 分层清晰
+class UserController {
+  constructor(private userService: UserService) {}
+  
+  async getUser(req, res) {
+    const user = await this.userService.findById(req.params.id);
+    res.json(user);
+  }
+}
+
+// ❌ 问题: 循环依赖
+// moduleA.ts
+import { funcB } from './moduleB';
+// moduleB.ts
+import { funcA } from './moduleA';
+
+// ✅ 修复: 提取共享模块或使用依赖注入
+```
+
+---
+
+## Severity Mapping
+
+| Severity | Criteria |
+|----------|----------|
+| **Critical** | 安全漏洞、数据损坏风险、崩溃风险 |
+| **High** | 功能缺陷、性能严重问题、重要边界未处理 |
+| **Medium** | 代码质量问题、可维护性问题 |
+| **Low** | 风格问题、优化建议 |
+| **Info** | 信息性建议、学习机会 |

package/.claude/skills/review-code/specs/rules/architecture-rules.json

@@ -0,0 +1,63 @@
+{
+  "dimension": "architecture",
+  "prefix": "ARCH",
+  "description": "Rules for detecting architecture issues including coupling, layering, and design patterns",
+  "rules": [
+    {
+      "id": "circular-dependency",
+      "category": "dependency",
+      "severity": "high",
+      "pattern": "import\\s+.*from\\s+['\"]\\.\\..*['\"]",
+      "patternType": "regex",
+      "contextPattern": "export.*import.*from.*same-module",
+      "description": "Potential circular dependency detected. Circular imports cause initialization issues and tight coupling",
+      "recommendation": "Extract shared code to a separate module, use dependency injection, or restructure the dependency graph",
+      "fixExample": "// Before - A imports B, B imports A\n// moduleA.ts\nimport { funcB } from './moduleB';\nexport const funcA = () => funcB();\n\n// moduleB.ts\nimport { funcA } from './moduleA'; // circular!\n\n// After - extract shared logic\n// shared.ts\nexport const sharedLogic = () => { ... };\n\n// moduleA.ts\nimport { sharedLogic } from './shared';"
+    },
+    {
+      "id": "god-class",
+      "category": "single-responsibility",
+      "severity": "high",
+      "pattern": "class\\s+\\w+\\s*\\{",
+      "patternType": "regex",
+      "methodThreshold": 15,
+      "lineThreshold": 300,
+      "description": "Class with too many methods or lines violates single responsibility principle",
+      "recommendation": "Split into smaller, focused classes. Each class should have one reason to change",
+      "fixExample": "// Before - UserManager handles everything\nclass UserManager {\n  createUser() { ... }\n  updateUser() { ... }\n  sendEmail() { ... }\n  generateReport() { ... }\n  validatePassword() { ... }\n}\n\n// After - separated concerns\nclass UserRepository { create, update, delete }\nclass EmailService { sendEmail }\nclass ReportGenerator { generate }\nclass PasswordValidator { validate }"
+    },
+    {
+      "id": "layer-violation",
+      "category": "layering",
+      "severity": "high",
+      "pattern": "import.*(?:repository|database|sql|prisma|mongoose).*from",
+      "patternType": "regex",
+      "contextPath": ["controller", "handler", "route", "component"],
+      "description": "Direct database access from presentation layer violates layered architecture",
+      "recommendation": "Access data through service/use-case layer. Keep controllers thin and delegate to services",
+      "fixExample": "// Before - controller accesses DB directly\nimport { prisma } from './database';\nconst getUsers = async () => prisma.user.findMany();\n\n// After - use service layer\nimport { userService } from './services';\nconst getUsers = async () => userService.getAll();"
+    },
+    {
+      "id": "missing-interface",
+      "category": "abstraction",
+      "severity": "medium",
+      "pattern": "new\\s+\\w+Service\\(|new\\s+\\w+Repository\\(",
+      "patternType": "regex",
+      "negativePatterns": ["interface", "implements", "inject"],
+      "description": "Direct instantiation of services/repositories creates tight coupling",
+      "recommendation": "Define interfaces and use dependency injection for loose coupling and testability",
+      "fixExample": "// Before - tight coupling\nclass OrderService {\n  private repo = new OrderRepository();\n}\n\n// After - loose coupling\ninterface IOrderRepository {\n  findById(id: string): Promise<Order>;\n}\n\nclass OrderService {\n  constructor(private repo: IOrderRepository) {}\n}"
+    },
+    {
+      "id": "mixed-concerns",
+      "category": "separation-of-concerns",
+      "severity": "medium",
+      "pattern": "fetch\\s*\\(|axios\\.|http\\.",
+      "patternType": "regex",
+      "contextPath": ["component", "view", "page"],
+      "description": "Network calls in UI components mix data fetching with presentation",
+      "recommendation": "Extract data fetching to hooks, services, or state management layer",
+      "fixExample": "// Before - fetch in component\nfunction UserList() {\n  const [users, setUsers] = useState([]);\n  useEffect(() => {\n    fetch('/api/users').then(r => r.json()).then(setUsers);\n  }, []);\n}\n\n// After - custom hook\nfunction useUsers() {\n  return useQuery('users', () => userService.getAll());\n}\n\nfunction UserList() {\n  const { data: users } = useUsers();\n}"
+    }
+  ]
+}

package/.claude/skills/review-code/specs/rules/correctness-rules.json

@@ -0,0 +1,60 @@
+{
+  "dimension": "correctness",
+  "prefix": "CORR",
+  "description": "Rules for detecting logical errors, null handling, and error handling issues",
+  "rules": [
+    {
+      "id": "null-check",
+      "category": "null-check",
+      "severity": "high",
+      "pattern": "\\w+\\.\\w+(?!\\.?\\?)",
+      "patternType": "regex",
+      "negativePatterns": ["\\?\\.", "if\\s*\\(", "!==?\\s*null", "!==?\\s*undefined", "&&\\s*\\w+\\."],
+      "description": "Property access without null/undefined check may cause runtime errors",
+      "recommendation": "Add null/undefined check before accessing properties using optional chaining or conditional checks",
+      "fixExample": "// Before\nobj.property.value\n\n// After\nobj?.property?.value\n// or\nif (obj && obj.property) { obj.property.value }"
+    },
+    {
+      "id": "empty-catch",
+      "category": "empty-catch",
+      "severity": "high",
+      "pattern": "catch\\s*\\([^)]*\\)\\s*\\{\\s*\\}",
+      "patternType": "regex",
+      "description": "Empty catch block silently swallows errors, hiding bugs and making debugging difficult",
+      "recommendation": "Log the error, rethrow it, or handle it appropriately. Never silently ignore exceptions",
+      "fixExample": "// Before\ncatch (e) { }\n\n// After\ncatch (e) {\n  console.error('Operation failed:', e);\n  throw e; // or handle appropriately\n}"
+    },
+    {
+      "id": "unreachable-code",
+      "category": "unreachable-code",
+      "severity": "medium",
+      "pattern": "return\\s+[^;]+;\\s*\\n\\s*[^}\\s]",
+      "patternType": "regex",
+      "description": "Code after return statement is unreachable and will never execute",
+      "recommendation": "Remove unreachable code or restructure the logic to ensure all code paths are accessible",
+      "fixExample": "// Before\nfunction example() {\n  return value;\n  doSomething(); // unreachable\n}\n\n// After\nfunction example() {\n  doSomething();\n  return value;\n}"
+    },
+    {
+      "id": "array-index-unchecked",
+      "category": "boundary-check",
+      "severity": "high",
+      "pattern": "\\[\\d+\\]|\\[\\w+\\](?!\\s*[!=<>])",
+      "patternType": "regex",
+      "negativePatterns": ["\\.length", "Array\\.isArray", "\\?.\\["],
+      "description": "Array index access without boundary check may cause undefined access or out-of-bounds errors",
+      "recommendation": "Check array length or use optional chaining before accessing array elements",
+      "fixExample": "// Before\nconst item = arr[index];\n\n// After\nconst item = arr?.[index];\n// or\nconst item = index < arr.length ? arr[index] : defaultValue;"
+    },
+    {
+      "id": "comparison-type-coercion",
+      "category": "type-safety",
+      "severity": "medium",
+      "pattern": "[^!=]==[^=]|[^!]==[^=]",
+      "patternType": "regex",
+      "negativePatterns": ["===", "!=="],
+      "description": "Using == instead of === can lead to unexpected type coercion",
+      "recommendation": "Use strict equality (===) to avoid implicit type conversion",
+      "fixExample": "// Before\nif (value == null)\nif (a == b)\n\n// After\nif (value === null || value === undefined)\nif (a === b)"
+    }
+  ]
+}

package/.claude/skills/review-code/specs/rules/index.md

@@ -0,0 +1,140 @@
+# Code Review Rules Index
+
+This directory contains externalized review rules for the multi-dimensional code review skill.
+
+## Directory Structure
+
+```
+rules/
+├── index.md                    # This file
+├── correctness-rules.json      # CORR - Logic and error handling
+├── security-rules.json         # SEC  - Security vulnerabilities
+├── performance-rules.json      # PERF - Performance issues
+├── readability-rules.json      # READ - Code clarity
+├── testing-rules.json          # TEST - Test quality
+└── architecture-rules.json     # ARCH - Design patterns
+```
+
+## Rule File Schema
+
+Each rule file follows this JSON schema:
+
+```json
+{
+  "dimension": "string",        // Dimension identifier
+  "prefix": "string",           // Finding ID prefix (4 chars)
+  "description": "string",      // Dimension description
+  "rules": [
+    {
+      "id": "string",           // Unique rule identifier
+      "category": "string",     // Rule category within dimension
+      "severity": "critical|high|medium|low",
+      "pattern": "string",      // Detection pattern
+      "patternType": "regex|includes|ast",
+      "negativePatterns": [],   // Patterns that exclude matches
+      "caseInsensitive": false, // For regex patterns
+      "contextPattern": "",     // Additional context requirement
+      "contextPath": [],        // Path patterns for context
+      "lineThreshold": 0,       // For size-based rules
+      "methodThreshold": 0,     // For complexity rules
+      "description": "string",  // Issue description
+      "recommendation": "string", // How to fix
+      "fixExample": "string"    // Code example
+    }
+  ]
+}
+```
+
+## Dimension Summary
+
+| Dimension | Prefix | Rules | Focus Areas |
+|-----------|--------|-------|-------------|
+| Correctness | CORR | 5 | Null checks, error handling, type safety |
+| Security | SEC | 5 | XSS, injection, secrets, crypto |
+| Performance | PERF | 5 | Complexity, I/O, memory leaks |
+| Readability | READ | 5 | Naming, length, nesting, magic values |
+| Testing | TEST | 5 | Assertions, coverage, mock quality |
+| Architecture | ARCH | 5 | Dependencies, layering, coupling |
+
+## Severity Levels
+
+| Severity | Description | Action |
+|----------|-------------|--------|
+| **critical** | Security vulnerability or data loss risk | Must fix before release |
+| **high** | Bug or significant quality issue | Fix in current sprint |
+| **medium** | Code smell or maintainability concern | Plan to address |
+| **low** | Style or minor improvement | Address when convenient |
+
+## Pattern Types
+
+### regex
+Standard regular expression pattern. Supports flags via `caseInsensitive`.
+
+```json
+{
+  "pattern": "catch\\s*\\([^)]*\\)\\s*\\{\\s*\\}",
+  "patternType": "regex"
+}
+```
+
+### includes
+Simple substring match. Faster than regex for literal strings.
+
+```json
+{
+  "pattern": "innerHTML",
+  "patternType": "includes"
+}
+```
+
+### ast (Future)
+AST-based detection for complex structural patterns.
+
+```json
+{
+  "pattern": "function[params>5]",
+  "patternType": "ast"
+}
+```
+
+## Usage in Code
+
+```javascript
+// Load rules
+const rules = JSON.parse(fs.readFileSync('correctness-rules.json'));
+
+// Apply rules
+for (const rule of rules.rules) {
+  const matches = detectByPattern(content, rule.pattern, rule.patternType);
+  for (const match of matches) {
+    // Check negative patterns
+    if (rule.negativePatterns?.some(np => match.context.includes(np))) {
+      continue;
+    }
+    findings.push({
+      id: `${rules.prefix}-${counter++}`,
+      severity: rule.severity,
+      category: rule.category,
+      description: rule.description,
+      recommendation: rule.recommendation,
+      fixExample: rule.fixExample
+    });
+  }
+}
+```
+
+## Adding New Rules
+
+1. Identify the appropriate dimension
+2. Create rule with unique `id` within dimension
+3. Choose appropriate `patternType`
+4. Provide clear `description` and `recommendation`
+5. Include practical `fixExample`
+6. Test against sample code
+
+## Rule Maintenance
+
+- Review rules quarterly for relevance
+- Update patterns as language/framework evolves
+- Track false positive rates
+- Collect feedback from users

package/.claude/skills/review-code/specs/rules/performance-rules.json

@@ -0,0 +1,59 @@
+{
+  "dimension": "performance",
+  "prefix": "PERF",
+  "description": "Rules for detecting performance issues including inefficient algorithms, memory leaks, and resource waste",
+  "rules": [
+    {
+      "id": "nested-loops",
+      "category": "algorithm-complexity",
+      "severity": "medium",
+      "pattern": "for\\s*\\([^)]+\\)\\s*\\{[^}]*for\\s*\\([^)]+\\)|forEach\\s*\\([^)]+\\)\\s*\\{[^}]*forEach",
+      "patternType": "regex",
+      "description": "Nested loops may indicate O(n^2) or worse complexity. Consider if this can be optimized",
+      "recommendation": "Use Map/Set for O(1) lookups, break early when possible, or restructure the algorithm",
+      "fixExample": "// Before - O(n^2)\nfor (const a of listA) {\n  for (const b of listB) {\n    if (a.id === b.id) { ... }\n  }\n}\n\n// After - O(n)\nconst bMap = new Map(listB.map(b => [b.id, b]));\nfor (const a of listA) {\n  const b = bMap.get(a.id);\n  if (b) { ... }\n}"
+    },
+    {
+      "id": "array-in-loop",
+      "category": "inefficient-operation",
+      "severity": "high",
+      "pattern": "\\.includes\\s*\\(|indexOf\\s*\\(|find\\s*\\(",
+      "patternType": "includes",
+      "contextPattern": "for|while|forEach|map|filter|reduce",
+      "description": "Array search methods inside loops cause O(n*m) complexity. Consider using Set or Map",
+      "recommendation": "Convert array to Set before the loop for O(1) lookups",
+      "fixExample": "// Before - O(n*m)\nfor (const item of items) {\n  if (existingIds.includes(item.id)) { ... }\n}\n\n// After - O(n)\nconst idSet = new Set(existingIds);\nfor (const item of items) {\n  if (idSet.has(item.id)) { ... }\n}"
+    },
+    {
+      "id": "synchronous-io",
+      "category": "io-efficiency",
+      "severity": "high",
+      "pattern": "readFileSync|writeFileSync|execSync|spawnSync",
+      "patternType": "includes",
+      "description": "Synchronous I/O blocks the event loop and degrades application responsiveness",
+      "recommendation": "Use async versions (readFile, writeFile) or Promise-based APIs",
+      "fixExample": "// Before\nconst data = fs.readFileSync(path);\n\n// After\nconst data = await fs.promises.readFile(path);\n// or\nfs.readFile(path, (err, data) => { ... });"
+    },
+    {
+      "id": "memory-leak-closure",
+      "category": "memory-leak",
+      "severity": "high",
+      "pattern": "addEventListener\\s*\\(|setInterval\\s*\\(|setTimeout\\s*\\(",
+      "patternType": "regex",
+      "negativePatterns": ["removeEventListener", "clearInterval", "clearTimeout"],
+      "description": "Event listeners and timers without cleanup can cause memory leaks",
+      "recommendation": "Always remove event listeners and clear timers in cleanup functions (componentWillUnmount, useEffect cleanup)",
+      "fixExample": "// Before\nuseEffect(() => {\n  window.addEventListener('resize', handler);\n}, []);\n\n// After\nuseEffect(() => {\n  window.addEventListener('resize', handler);\n  return () => window.removeEventListener('resize', handler);\n}, []);"
+    },
+    {
+      "id": "unnecessary-rerender",
+      "category": "react-performance",
+      "severity": "medium",
+      "pattern": "useState\\s*\\(\\s*\\{|useState\\s*\\(\\s*\\[",
+      "patternType": "regex",
+      "description": "Creating new object/array references in useState can cause unnecessary re-renders",
+      "recommendation": "Use useMemo for computed values, useCallback for functions, or consider state management libraries",
+      "fixExample": "// Before - new object every render\nconst [config] = useState({ theme: 'dark' });\n\n// After - stable reference\nconst defaultConfig = useMemo(() => ({ theme: 'dark' }), []);\nconst [config] = useState(defaultConfig);"
+    }
+  ]
+}