catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-02-13 02:41:50 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat: Add orchestrator and state management for code review process

Browse Source 
- Implemented orchestrator logic to manage code review phases, including state reading, action selection, and execution loop.
- Defined state schema for review process, including metadata, context, findings, and execution tracking.
- Created action catalog detailing actions for context collection, quick scan, deep review, report generation, and completion.
- Established error recovery strategies and termination conditions for robust review handling.
- Developed issue classification and quality standards documentation to guide review severity and categorization.
- Introduced review dimensions with detailed checklists for correctness, security, performance, readability, testing, and architecture.
- Added templates for issue reporting and review reports to standardize output and improve clarity.
This commit is contained in:
catlog22
2026-01-13 14:39:16 +08:00
parent 76f5311e78
commit 29c8bb7a66
13 changed files with 2611 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

228
.claude/skills/review-code/specs/issue-classification.md Normal file
View File

@@ -0,0 +1,228 @@
# Issue Classification
问题分类和严重程度标准。
## When to Use
| Phase | Usage | Section |
|-------|-------|---------|
| action-deep-review | 确定问题严重程度 | Severity Levels |
| action-generate-report | 问题分类展示 | Category Mapping |
---
## Severity Levels
### Critical (严重) 🔴
**定义**: 必须在合并前修复的阻塞性问题
**标准**:
- 安全漏洞 (可被利用)
- 数据损坏或丢失风险
- 系统崩溃风险
- 生产环境重大故障
**示例**:
- SQL/XSS/命令注入
- 硬编码密钥泄露
- 未捕获的异常导致崩溃
- 数据库事务未正确处理
**响应**: 必须立即修复，阻塞合并
---
### High (高) 🟠
**定义**: 应在合并前修复的重要问题
**标准**:
- 功能缺陷
- 重要边界条件未处理
- 性能严重退化
- 资源泄漏
**示例**:
- 核心业务逻辑错误
- 内存泄漏
- N+1 查询问题
- 缺少必要的错误处理
**响应**: 强烈建议修复
---
### Medium (中) 🟡
**定义**: 建议修复的代码质量问题
**标准**:
- 代码可维护性问题
- 轻微性能问题
- 测试覆盖不足
- 不符合团队规范
**示例**:
- 函数过长
- 命名不清晰
- 缺少注释
- 代码重复
**响应**: 建议在后续迭代修复
---
### Low (低) 🔵
**定义**: 可选优化的问题
**标准**:
- 风格问题
- 微小优化
- 可读性改进
**示例**:
- 变量声明顺序
- 额外的空行
- 可以更简洁的写法
**响应**: 可根据团队偏好处理
---
### Info (信息) ⚪
**定义**: 信息性建议，非问题
**标准**:
- 学习机会
- 替代方案建议
- 文档完善建议
**示例**:
- "这里可以考虑使用新的 API"
- "建议添加 JSDoc 注释"
- "可以参考 xxx 模式"
**响应**: 仅供参考
---
## Category Mapping
### By Dimension
| Dimension | Common Categories |
|-----------|-------------------|
| Correctness | `null-check`, `boundary`, `error-handling`, `type-safety`, `logic-error` |
| Security | `injection`, `xss`, `hardcoded-secret`, `auth`, `sensitive-data` |
| Performance | `complexity`, `n+1-query`, `memory-leak`, `blocking-io`, `inefficient-algorithm` |
| Readability | `naming`, `function-length`, `complexity`, `comments`, `duplication` |
| Testing | `coverage`, `boundary-test`, `mock-abuse`, `test-isolation` |
| Architecture | `layer-violation`, `circular-dependency`, `coupling`, `srp-violation` |
### Category Details
#### Correctness Categories
| Category | Description | Default Severity |
|----------|-------------|------------------|
| `null-check` | 缺少空值检查 | High |
| `boundary` | 边界条件未处理 | High |
| `error-handling` | 错误处理不当 | High |
| `type-safety` | 类型安全问题 | Medium |
| `logic-error` | 逻辑错误 | Critical/High |
| `resource-leak` | 资源泄漏 | High |
#### Security Categories
| Category | Description | Default Severity |
|----------|-------------|------------------|
| `injection` | 注入风险 (SQL/Command) | Critical |
| `xss` | 跨站脚本风险 | Critical |
| `hardcoded-secret` | 硬编码密钥 | Critical |
| `auth` | 认证授权问题 | High |
| `sensitive-data` | 敏感数据暴露 | High |
| `insecure-dependency` | 不安全依赖 | Medium |
#### Performance Categories
| Category | Description | Default Severity |
|----------|-------------|------------------|
| `complexity` | 高算法复杂度 | Medium |
| `n+1-query` | N+1 查询问题 | High |
| `memory-leak` | 内存泄漏 | High |
| `blocking-io` | 阻塞 I/O | Medium |
| `inefficient-algorithm` | 低效算法 | Medium |
| `missing-cache` | 缺少缓存 | Low |
#### Readability Categories
| Category | Description | Default Severity |
|----------|-------------|------------------|
| `naming` | 命名问题 | Medium |
| `function-length` | 函数过长 | Medium |
| `nesting-depth` | 嵌套过深 | Medium |
| `comments` | 注释问题 | Low |
| `duplication` | 代码重复 | Medium |
| `magic-number` | 魔法数字 | Low |
#### Testing Categories
| Category | Description | Default Severity |
|----------|-------------|------------------|
| `coverage` | 测试覆盖不足 | Medium |
| `boundary-test` | 缺少边界测试 | Medium |
| `mock-abuse` | Mock 过度使用 | Low |
| `test-isolation` | 测试不独立 | Medium |
| `flaky-test` | 不稳定测试 | High |
#### Architecture Categories
| Category | Description | Default Severity |
|----------|-------------|------------------|
| `layer-violation` | 层次违规 | Medium |
| `circular-dependency` | 循环依赖 | High |
| `coupling` | 耦合过紧 | Medium |
| `srp-violation` | 单一职责违规 | Medium |
| `god-class` | 上帝类 | High |
---
## Finding ID Format
```
{PREFIX}-{NNN}
Prefixes by Dimension:
- CORR: Correctness
- SEC: Security
- PERF: Performance
- READ: Readability
- TEST: Testing
- ARCH: Architecture
Examples:
- SEC-001: First security finding
- CORR-015: 15th correctness finding
```
---
## Quality Gates
| Gate | Condition | Action |
|------|-----------|--------|
| **Block** | Critical > 0 | 禁止合并 |
| **Warn** | High > 0 | 需要审批 |
| **Pass** | Critical = 0, High = 0 | 允许合并 |
### Recommended Thresholds
| Metric | Ideal | Acceptable | Needs Work |
|--------|-------|------------|------------|
| Critical | 0 | 0 | Any > 0 |
| High | 0 | ≤ 2 | > 2 |
| Medium | ≤ 5 | ≤ 10 | > 10 |
| Total | ≤ 10 | ≤ 20 | > 20 |

214
.claude/skills/review-code/specs/quality-standards.md Normal file
View File

@@ -0,0 +1,214 @@
# Quality Standards
代码审查质量标准。
## When to Use
| Phase | Usage | Section |
|-------|-------|---------|
| action-generate-report | 质量评估 | Quality Dimensions |
| action-complete | 最终评分 | Quality Gates |
---
## Quality Dimensions
### 1. Completeness (完整性) - 25%
**评估审查覆盖的完整程度**
| Score | Criteria |
|-------|----------|
| 100% | 所有维度审查完成，所有高风险文件检查 |
| 80% | 核心维度完成，主要文件检查 |
| 60% | 部分维度完成 |
| < 60% | 审查不完整 |
**检查点**:
- [ ] 6 个维度全部审查
- [ ] 高风险区域重点检查
- [ ] 关键文件覆盖
---
### 2. Accuracy (准确性) - 25%
**评估发现问题的准确程度**
| Score | Criteria |
|-------|----------|
| 100% | 问题定位准确，分类正确，无误报 |
| 80% | 偶有分类偏差，定位准确 |
| 60% | 存在误报或漏报 |
| < 60% | 准确性差 |
**检查点**:
- [ ] 问题行号准确
- [ ] 严重程度合理
- [ ] 分类正确
---
### 3. Actionability (可操作性) - 25%
**评估建议的实用程度**
| Score | Criteria |
|-------|----------|
| 100% | 每个问题都有具体可执行的修复建议 |
| 80% | 大部分问题有清晰建议 |
| 60% | 建议较笼统 |
| < 60% | 缺乏可操作建议 |
**检查点**:
- [ ] 提供具体修复建议
- [ ] 包含代码示例
- [ ] 说明修复优先级
---
### 4. Consistency (一致性) - 25%
**评估审查标准的一致程度**
| Score | Criteria |
|-------|----------|
| 100% | 相同问题相同处理，标准统一 |
| 80% | 基本一致，偶有差异 |
| 60% | 标准不太统一 |
| < 60% | 标准混乱 |
**检查点**:
- [ ] ID 格式统一
- [ ] 严重程度标准一致
- [ ] 描述风格统一
---
## Quality Gates
### Review Quality Gate
| Gate | Overall Score | Action |
|------|---------------|--------|
| **Excellent** | ≥ 90% | 高质量审查 |
| **Good** | ≥ 80% | 合格审查 |
| **Acceptable** | ≥ 70% | 基本可接受 |
| **Needs Improvement** | < 70% | 需要改进 |
### Code Quality Gate (Based on Findings)
| Gate | Condition | Recommendation |
|------|-----------|----------------|
| **Block** | Critical > 0 | 禁止合并，必须修复 |
| **Warn** | High > 3 | 需要团队讨论 |
| **Caution** | Medium > 10 | 建议改进 |
| **Pass** | 其他 | 可以合并 |
---
## Report Quality Checklist
### Structure
- [ ] 包含审查概览
- [ ] 包含问题统计
- [ ] 包含高风险区域
- [ ] 包含问题详情
- [ ] 包含修复建议
### Content
- [ ] 问题描述清晰
- [ ] 文件位置准确
- [ ] 代码片段有效
- [ ] 修复建议具体
- [ ] 优先级明确
### Format
- [ ] Markdown 格式正确
- [ ] 表格对齐
- [ ] 代码块语法正确
- [ ] 链接有效
- [ ] 无拼写错误
---
## Validation Function
```javascript
function validateReviewQuality(state) {
const scores = {
completeness: 0,
accuracy: 0,
actionability: 0,
consistency: 0
};
// 1. Completeness
const dimensionsReviewed = state.reviewed_dimensions?.length || 0;
scores.completeness = (dimensionsReviewed / 6) * 100;
// 2. Accuracy (需要人工验证或后续反馈)
// 暂时基于有无错误来估算
scores.accuracy = state.error_count === 0 ? 100 : Math.max(0, 100 - state.error_count * 20);
// 3. Actionability
const findings = Object.values(state.findings).flat();
const withRecommendations = findings.filter(f => f.recommendation).length;
scores.actionability = findings.length > 0
? (withRecommendations / findings.length) * 100
: 100;
// 4. Consistency (检查 ID 格式等)
const validIds = findings.filter(f => /^(CORR|SEC|PERF|READ|TEST|ARCH)-\d{3}$/.test(f.id)).length;
scores.consistency = findings.length > 0
? (validIds / findings.length) * 100
: 100;
// Overall
const overall = (
scores.completeness * 0.25 +
scores.accuracy * 0.25 +
scores.actionability * 0.25 +
scores.consistency * 0.25
);
return {
scores,
overall,
gate: overall >= 90 ? 'excellent' :
overall >= 80 ? 'good' :
overall >= 70 ? 'acceptable' : 'needs_improvement'
};
}
```
---
## Improvement Recommendations
### If Completeness is Low
- 增加扫描的文件范围
- 确保所有维度都被审查
- 重点关注高风险区域
### If Accuracy is Low
- 提高规则精度
- 减少误报
- 验证行号准确性
### If Actionability is Low
- 为每个问题添加修复建议
- 提供代码示例
- 说明修复步骤
### If Consistency is Low
- 统一 ID 格式
- 标准化严重程度判定
- 使用模板化描述

337
.claude/skills/review-code/specs/review-dimensions.md Normal file
View File

@@ -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** | 信息性建议、学习机会 |