dev-code-quality

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Code Quality Scan

代码质量扫描

Systematic codebase scan that identifies duplication, redundancy, architectural issues, and improvement opportunities. Produces a prioritized action plan.

对代码库进行系统性扫描，识别代码重复、冗余、架构问题以及改进机会，并生成优先级明确的行动计划。

Workflow

工作流程

Step 1: Scope Definition

步骤1：范围定义

Determine the scan scope:

Full repo: Scan everything (default)
Directory: Scan a specific package/module
Post-change: Scan only files changed since last commit or compared to a branch

确定扫描范围：

完整代码仓库：扫描全部内容（默认选项）
指定目录：扫描特定的包/模块
变更后扫描：仅扫描自上次commit以来或与指定分支对比后变更的文件

Step 2: Structural Analysis

步骤2：结构分析

Project layout: Map the directory structure and identify the architecture pattern (flat, layered, hexagonal, etc.)
Dependency graph: Trace imports between packages to identify:
- Circular dependencies
- Unexpected cross-layer dependencies
- Packages that import too many others (high fan-out)
- Packages imported by too many others (high fan-in, potential God package)
File size distribution: Flag unusually large files (likely candidates for splitting)

项目布局：梳理目录结构，识别架构模式（扁平式、分层式、六边形架构等）
依赖图谱：追踪包之间的导入关系，识别以下问题：
- Circular dependencies
- 意外的跨层依赖
- 导入过多其他包的模块（高扇出）
- 被过多其他包导入的模块（高扇入，潜在God package）
文件大小分布：标记异常大的文件（这类文件通常适合拆分）

Step 3: Duplication Detection

步骤3：重复代码检测

Search for code duplication across the codebase:

Structural duplication: Similar function signatures, similar struct/type definitions
Logic duplication: Repeated patterns (error handling, validation, formatting)
Cross-package duplication: Same utility reimplemented in multiple packages

For each duplication found, report:

Location (files and line ranges)
Nature of duplication (exact copy, similar pattern, same concept)
Suggested refactoring (extract function, create shared package, use interface)

在整个代码库中搜索重复代码：

结构重复：相似的函数签名、相似的结构体/类型定义
逻辑重复：重复的代码模式（错误处理、校验、格式化等）
跨包重复：同一工具函数在多个包中被重复实现

针对发现的每一处重复，需报告：

位置（文件及行号范围）
重复类型（完全复制、相似模式、同一概念的重复实现）
建议重构方案（提取函数、创建共享包、使用interface）

Step 4: Redundancy Check

步骤4：冗余代码检查

Dead code: Functions, types, or constants that are never referenced
Unused imports/dependencies: Check go.mod, package.json for unused entries
Overlapping abstractions: Multiple types or interfaces serving the same purpose
Unnecessary complexity: Over-abstracted code, premature generalization

死代码：从未被引用的函数、类型或常量
未使用的导入/依赖：检查go.mod、package.json中的未使用条目
重叠抽象：多个类型或interface实现同一用途
不必要的复杂度：过度抽象的代码、过早的泛化

Step 5: Architecture Assessment

步骤5：架构评估

Evaluate the overall design:

Separation of concerns: Are layers (CLI, domain, storage, etc.) cleanly separated?
API surface: Are internal details leaking through public interfaces?
Error handling: Is error handling consistent? Are errors wrapped with context?
Naming consistency: Are naming conventions consistent across the codebase?

评估整体设计：

关注点分离：各层（CLI、领域层、存储层等）是否清晰分离？
API暴露面：内部细节是否通过公共interface泄露？
错误处理：错误处理是否一致？错误是否附带上下文信息？
命名一致性：整个代码库的命名规范是否统一？

Step 6: Report & Prioritize

步骤6：报告与优先级排序

Present findings as a prioritized list:

Code Quality Scan Results:

High Priority:
1. [Issue] — [Location] — [Impact] — [Suggested fix]
2. ...

Medium Priority:
3. [Issue] — [Location] — [Impact] — [Suggested fix]
4. ...

Low Priority (nice to have):
5. ...

Prioritization criteria:

High: Bugs, security issues, significant duplication, architectural violations
Medium: Code quality improvements, moderate duplication, naming inconsistencies
Low: Style preferences, minor optimizations, cosmetic improvements

Ask the user which items to address, then work through them.

将发现的问题整理为优先级明确的列表：

Code Quality Scan Results:

High Priority:
1. [Issue] — [Location] — [Impact] — [Suggested fix]
2. ...

Medium Priority:
3. [Issue] — [Location] — [Impact] — [Suggested fix]
4. ...

Low Priority (nice to have):
5. ...

优先级判定标准：

高优先级：Bug、安全问题、严重代码重复、架构违规
中优先级：代码质量提升、中度代码重复、命名不一致
低优先级：风格偏好、微小优化、外观改进

询问用户需要处理哪些问题，然后逐一解决。

What NOT to Flag

无需标记的内容

Minor style differences that don't affect readability
Test file duplication (test fixtures often intentionally repeat setup)
Generated code
Vendor/third-party code

不影响可读性的微小风格差异
测试文件中的重复内容（测试夹具通常会有意重复初始化代码）
生成的代码
第三方依赖代码（Vendor目录下的代码）

Common Findings

常见问题发现

Formatter/display code duplicated across CLI commands: Extract to shared
```
output
```
or
```
formatter
```
package
Similar validation logic in multiple handlers: Create a validation middleware or shared validator
Multiple config parsing approaches: Consolidate into a single config package
Type overlap between layers: Domain types leaked into CLI or storage layers
N+1 patterns: Loop with individual API/DB calls instead of batch operations

CLI命令间重复的格式化/展示代码：提取到共享的
```
output
```
或
```
formatter
```
包中
多个处理器中重复的校验逻辑：创建校验中间件或共享校验器
多种配置解析方式：合并为单一的config包
层间类型重叠：领域层类型泄露到CLI或存储层
N+1查询模式：通过循环发起单个API/DB调用，而非批量操作

Examples

示例

Example 1: Full repo scan

User: "scan the repo and suggest improvements"
Action:
1. Map project structure
2. Trace dependencies between packages
3. Search for duplicated patterns
4. Check for dead code
5. Assess architecture
6. Present prioritized report

Example 2: Post-refactor validation

User: "find code duplications and refactoring plan"
Action:
1. Focus on structural and logic duplication
2. Identify extraction candidates
3. Propose concrete refactoring steps with file references
4. Estimate scope of each refactoring

示例1：完整代码仓库扫描

User: "scan the repo and suggest improvements"
Action:
1. Map project structure
2. Trace dependencies between packages
3. Search for duplicated patterns
4. Check for dead code
5. Assess architecture
6. Present prioritized report

示例2：重构后验证

User: "find code duplications and refactoring plan"
Action:
1. Focus on structural and logic duplication
2. Identify extraction candidates
3. Propose concrete refactoring steps with file references
4. Estimate scope of each refactoring