Back to Details

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：结构分析

  1. Project layout: Map the directory structure and identify the architecture pattern (flat, layered, hexagonal, etc.)
  2. 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)
  3. File size distribution: Flag unusually large files (likely candidates for splitting)
  1. 项目布局：梳理目录结构，识别架构模式（扁平式、分层式、六边形架构等）
  2. 依赖图谱：追踪包之间的导入关系，识别以下问题：
    • Circular dependencies
    • 意外的跨层依赖
    • 导入过多其他包的模块（高扇出）
    • 被过多其他包导入的模块（高扇入，潜在God package）
  3. 文件大小分布：标记异常大的文件（这类文件通常适合拆分）

Step 3: Duplication Detection

步骤3：重复代码检测

Search for code duplication across the codebase:
  1. Structural duplication: Similar function signatures, similar struct/type definitions
  2. Logic duplication: Repeated patterns (error handling, validation, formatting)
  3. 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)
在整个代码库中搜索重复代码：
  1. 结构重复：相似的函数签名、相似的结构体/类型定义
  2. 逻辑重复：重复的代码模式（错误处理、校验、格式化等）
  3. 跨包重复：同一工具函数在多个包中被重复实现
针对发现的每一处重复，需报告：
  • 位置（文件及行号范围）
  • 重复类型（完全复制、相似模式、同一概念的重复实现）
  • 建议重构方案（提取函数、创建共享包、使用interface）

Step 4: Redundancy Check

步骤4：冗余代码检查

  1. Dead code: Functions, types, or constants that are never referenced
  2. Unused imports/dependencies: Check go.mod, package.json for unused entries
  3. Overlapping abstractions: Multiple types or interfaces serving the same purpose
  4. Unnecessary complexity: Over-abstracted code, premature generalization
  1. 死代码：从未被引用的函数、类型或常量
  2. 未使用的导入/依赖：检查go.mod、package.json中的未使用条目
  3. 重叠抽象：多个类型或interface实现同一用途
  4. 不必要的复杂度：过度抽象的代码、过早的泛化

Step 5: Architecture Assessment

步骤5：架构评估

Evaluate the overall design:
  1. Separation of concerns: Are layers (CLI, domain, storage, etc.) cleanly separated?
  2. API surface: Are internal details leaking through public interfaces?
  3. Error handling: Is error handling consistent? Are errors wrapped with context?
  4. Naming consistency: Are naming conventions consistent across the codebase?
评估整体设计：
  1. 关注点分离：各层（CLI、领域层、存储层等）是否清晰分离？
  2. API暴露面：内部细节是否通过公共interface泄露？
  3. 错误处理：错误处理是否一致？错误是否附带上下文信息？
  4. 命名一致性：整个代码库的命名规范是否统一？

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