Back to Details

code-quality

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Code Quality Skill

代码质量Skill

🚨 MANDATORY 7-PHASE WORKFLOW

🚨 强制要求的7阶段工作流

PHASE 1: Exploration (explore-codebase) → BLOCKER
PHASE 2: Documentation (research-expert) → BLOCKER
PHASE 3: Impact Analysis (Grep usages) → BLOCKER
PHASE 3.5: DRY Detection (jscpd duplication) → NON-BLOCKING
PHASE 4: Error Detection (linters)
PHASE 5: Precision Correction (with docs + impact + DRY)
PHASE 6: Verification (re-run linters, tests, duplication)
CRITICAL: Phases 1-3 are BLOCKERS. Never skip them. DRY: Phase 3.5 is non-blocking but findings inform Phase 5 corrections.
PHASE 1: Exploration (explore-codebase) → BLOCKER
PHASE 2: Documentation (research-expert) → BLOCKER
PHASE 3: Impact Analysis (Grep usages) → BLOCKER
PHASE 3.5: DRY Detection (jscpd duplication) → NON-BLOCKING
PHASE 4: Error Detection (linters)
PHASE 5: Precision Correction (with docs + impact + DRY)
PHASE 6: Verification (re-run linters, tests, duplication)
重要提示：阶段1-3为阻塞项，绝对不能跳过。 DRY说明：阶段3.5为非阻塞项，但检测结果会为阶段5的修正提供参考。

PHASE 1: Architecture Exploration

阶段1：架构探索

Launch explore-codebase agent FIRST:
> Use Task tool with subagent_type="explore-codebase"
Gather:
  1. Programming language(s) detected
  2. Existing linter configs (.eslintrc, .prettierrc, pyproject.toml)
  3. Package managers and installed linters
  4. Project structure and conventions
  5. Framework versions (package.json, go.mod, Cargo.toml)
  6. Architecture patterns (Clean, Hexagonal, MVC)
  7. State management (Zustand, Redux, Context)
  8. Interface/types directories location
首先启动explore-codebase Agent:
> Use Task tool with subagent_type="explore-codebase"
需收集的信息:
  1. 检测到的编程语言
  2. 已有的代码检查器配置文件（.eslintrc、.prettierrc、pyproject.toml）
  3. 包管理器及已安装的代码检查器
  4. 项目结构与约定
  5. 框架版本（package.json、go.mod、Cargo.toml）
  6. 架构模式（Clean、Hexagonal、MVC）
  7. 状态管理方案（Zustand、Redux、Context）
  8. 接口/类型目录位置

PHASE 2: Documentation Research

阶段2：文档调研

Launch research-expert agent:
> Use Task tool with subagent_type="research-expert"
> Request: Verify [library/framework] documentation for [error type]
> Request: Find [language] best practices for [specific issue]
Request for each error:
  • Official API documentation
  • Current syntax and deprecations
  • Best practices for error patterns
  • Version-specific breaking changes
  • Security advisories
  • Language-specific SOLID patterns
启动research-expert Agent:
> Use Task tool with subagent_type="research-expert"
> Request: Verify [library/framework] documentation for [error type]
> Request: Find [language] best practices for [specific issue]
针对每个错误需调研的内容:
  • 官方API文档
  • 当前语法及废弃说明
  • 错误模式的最佳实践
  • 版本相关的破坏性变更
  • 安全公告
  • 语言特定的SOLID模式

PHASE 3: Impact Analysis

阶段3：影响分析

For EACH element to modify: Grep usages → assess risk → document impact.
RiskCriteriaAction
🟢 LOWInternal, 0-1 usagesProceed
🟡 MEDIUM2-5 usages, compatibleProceed with care
🔴 HIGH5+ usages OR breakingFlag to user FIRST
对于每一个待修改的元素：搜索使用场景 → 评估风险 → 记录影响范围。
风险等级判断标准操作建议
🟢 低风险内部使用，0-1处引用直接推进
🟡 中风险2-5处引用，兼容现有逻辑谨慎推进
🔴 高风险5处以上引用 或 会导致破坏性变更先向用户标记说明

PHASE 3.5: Code Duplication Detection (DRY)

阶段3.5：代码重复检测（DRY）

Tool: 
jscpd
— 150+ languages — 
npx jscpd ./src --threshold 5 --reporters console,json
LevelThresholdAction
🟢 Excellent< 3%No action needed
🟡 Good3-5%Document, fix if time
🟠 Acceptable5-10%Extract shared logic
🔴 Critical> 10%Mandatory refactoring
See references/duplication-thresholds.md for per-language thresholds, config, and extraction patterns. See references/linter-commands.md for language-specific jscpd commands.
工具：
jscpd
— 支持150+种语言 — 
npx jscpd ./src --threshold 5 --reporters console,json
等级阈值操作建议
🟢 优秀< 3%无需操作
🟡 良好3-5%记录情况，若有时间则修复
🟠 可接受5-10%提取共享逻辑
🔴 严重> 10%必须重构
查看 references/duplication-thresholds.md 获取各语言的阈值、配置及提取模式。 查看 references/linter-commands.md 获取各语言对应的jscpd命令。

Linter Commands

代码检查器命令

See references/linter-commands.md for language-specific commands.
查看 references/linter-commands.md 获取各语言对应的命令。

Error Priority Matrix

错误优先级矩阵

PriorityTypeExamplesAction
CriticalSecuritySQL injection, XSS, CSRF, auth bypassFix IMMEDIATELY
HighLogicSOLID violations, memory leaks, race conditionsFix same session
HighDRYCode duplication > 10%, copy-paste logic blocksMandatory refactoring
MediumDRYCode duplication 5-10%, repeated patternsExtract shared logic
MediumPerformanceN+1 queries, deprecated APIs, inefficient algorithmsFix if time
LowStyleFormatting, naming, missing docsFix if time
优先级类型示例操作建议
严重安全类SQL注入、XSS、CSRF、身份验证绕过立即修复
高逻辑类SOLID原则违反、内存泄漏、竞态条件本次会话内修复
高DRY类代码重复率>10%、复制粘贴的逻辑块必须重构
中DRY类代码重复率5-10%、重复出现的模式提取共享逻辑
中性能类N+1查询、废弃API、低效算法若有时间则修复
低风格类格式问题、命名规范、缺失文档若有时间则修复

SOLID Validation

SOLID原则验证

See references/solid-validation.md for S-O-L-I-D detection patterns and fix examples.
查看 references/solid-validation.md 获取SOLID原则的检测模式及修复示例。

File Size Rules

文件大小规则

See references/file-size-rules.md for LoC limits, calculation, and split strategies.
查看 references/file-size-rules.md 获取代码行数限制、计算方式及拆分策略。

Architecture Rules

架构规则

See references/architecture-patterns.md for project structures and patterns.
查看 references/architecture-patterns.md 获取项目结构及模式规范。

Validation Report Format

验证报告格式

See references/validation-report.md for the complete sniper report template.
查看 references/validation-report.md 获取完整的检测报告模板。

Complete Workflow Example

完整工作流示例

See references/examples.md for detailed walkthrough.
查看 references/examples.md 获取详细的流程演示。

Forbidden Behaviors

禁止行为

Workflow Violations

工作流违规

  • ❌ Skip PHASE 1 (explore-codebase)
  • ❌ Skip PHASE 2 (research-expert)
  • ❌ Skip PHASE 3 (impact analysis)
  • ❌ Skip PHASE 3.5 (DRY detection)
  • ❌ Jump to corrections without completing Phases 1-3
  • ❌ Proceed when BLOCKER is active
  • ❌ 跳过阶段1（explore-codebase）
  • ❌ 跳过阶段2（research-expert）
  • ❌ 跳过阶段3（影响分析）
  • ❌ 跳过阶段3.5（DRY检测）
  • ❌ 未完成阶段1-3就直接进入修正环节
  • ❌ 在阻塞项未处理时继续推进

Code Quality Violations

代码质量违规

  • ❌ Leave ANY linter errors unfixed
  • ❌ Apply fixes that introduce new errors
  • ❌ Ignore SOLID violations
  • ❌ Ignore DRY violations > 5% duplication
  • ❌ Copy-paste code instead of extracting shared logic
  • ❌ Create tests if project has none
  • ❌ 遗留任何代码检查器错误未修复
  • ❌ 修复后引入新的错误
  • ❌ 忽略SOLID原则违反
  • ❌ 忽略重复率>5%的DRY原则违反
  • ❌ 复制粘贴代码而非提取共享逻辑
  • ❌ 在无测试的项目中新增测试

Architecture Violations

架构违规

  • ❌ Interfaces in component files (ZERO TOLERANCE)
  • ❌ Business logic in components (must be in hooks)
  • ❌ Monolithic components (must section)
  • ❌ Files >100 LoC without split
  • ❌ Local state for global data (use stores)
  • ❌ 在组件文件中包含接口（零容忍）
  • ❌ 在组件中编写业务逻辑（必须放在hooks中）
  • ❌ 单体式组件（必须拆分）
  • ❌ 代码行数>100且未拆分的文件
  • ❌ 用本地状态存储全局数据（需使用状态管理库）

Safety Violations

安全违规

  • ❌ High-risk changes without user approval
  • ❌ Breaking backwards compatibility silently
  • ❌ Modifying public APIs without deprecation
  • ❌ 未获得用户批准就进行高风险变更
  • ❌ 静默破坏向后兼容性
  • ❌ 修改公共API但未标记废弃说明