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:

Programming language(s) detected
Existing linter configs (.eslintrc, .prettierrc, pyproject.toml)
Package managers and installed linters
Project structure and conventions
Framework versions (package.json, go.mod, Cargo.toml)
Architecture patterns (Clean, Hexagonal, MVC)
State management (Zustand, Redux, Context)
Interface/types directories location

首先启动explore-codebase Agent:

> Use Task tool with subagent_type="explore-codebase"

需收集的信息:

检测到的编程语言
已有的代码检查器配置文件（.eslintrc、.prettierrc、pyproject.toml）
包管理器及已安装的代码检查器
项目结构与约定
框架版本（package.json、go.mod、Cargo.toml）
架构模式（Clean、Hexagonal、MVC）
状态管理方案（Zustand、Redux、Context）
接口/类型目录位置

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.

Risk	Criteria	Action
🟢 LOW	Internal, 0-1 usages	Proceed
🟡 MEDIUM	2-5 usages, compatible	Proceed with care
🔴 HIGH	5+ usages OR breaking	Flag 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

Level	Threshold	Action
🟢 Excellent	< 3%	No action needed
🟡 Good	3-5%	Document, fix if time
🟠 Acceptable	5-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

错误优先级矩阵

Priority	Type	Examples	Action
Critical	Security	SQL injection, XSS, CSRF, auth bypass	Fix IMMEDIATELY
High	Logic	SOLID violations, memory leaks, race conditions	Fix same session
High	DRY	Code duplication > 10%, copy-paste logic blocks	Mandatory refactoring
Medium	DRY	Code duplication 5-10%, repeated patterns	Extract shared logic
Medium	Performance	N+1 queries, deprecated APIs, inefficient algorithms	Fix if time
Low	Style	Formatting, naming, missing docs	Fix 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但未标记废弃说明