Checking Code Quality

代码质量校验关卡

> 阈值是 heuristic，不是判决。主动判断哪些超标值得拆，哪些是合理复杂度。

何时使用

| 场景 | 跑 | 判据 | |------|------|------| | 重构完成 | ✅ | 验证拆分有效，未引入新异味 | | 复杂模块新增 | ✅ | 早期发现可读性问题 | | 提交前（>30 行变更） | ✅ | 防腐烂 | | PR review | ✅ | 客观度量替代主观争论 | | 紧急修复 | ❌ | 优先稳定，质量在收口阶段补 | | 算法/性能关键路径 | ⚠ | 工具阈值不适用，按性能基准判断 |

abyss 集成

如果 abyss 可用，质量检查时额外使用 hotspot 数据：

abyss map --json  # 获取热点文件列表

• hotspot_score > 10000 的文件：标记为「高风险热点」，优先拆分
• change_count > 20 且 complexity > 100：建议拆分为更小的文件/函数
• coupling_score > 80%：提醒耦合文件需要同步审查

阈值与处置

| 指标 | 阈值 | 超标处置 | 何时容忍 | |------|------|----------|----------| | 圈复杂度 | ≤10 | 拆分函数、引入策略模式 | 有限状态机/解析器（结构性复杂） | | 函数长度 | ≤50 行 | 提取子函数 | 配置/常量声明、大型 switch | | 文件长度 | ≤500 行 | 拆分模块 | 自动生成代码、protobuf | | 参数数量 | ≤5 | 封装参数对象 | 构造函数（builder 模式更佳） | | 嵌套深度 | ≤4 | 早返回、提取函数、查表 | 罕见情况下的状态机 | | 行长度 | ≤120 | 换行 | 长字符串字面量、SQL |

例外说明：bin/ 下带 Node shebang 的 CLI 入口按命令编排层处理，不参与文件长度阈值；其业务逻辑仍应优先下沉到 bin/lib/。

代码异味

| 异味 | 严重度 | 处置 | |------|--------|------| | 重复代码 >10 行 | High | 提取公共函数；判断是否真重复（结构相似但语义不同时不要强抽） | | 参数 >5 个 | Medium | 封装参数对象 | | 魔法数字 | Medium | 提取常量；常见数（0, 1, 2）可豁免 | | 死代码/注释代码块 | Low | 删除；用 git history 追溯，不要靠注释保留 |

命名规范

| 实体 | 规则 | |------|------| | 类 | PascalCase | | 函数 | snakecase (Python/Rust) / camelCase (JS/TS/Go) | | 常量 | UPPERSNAKE | | 变量 | snake_case / camelCase（按语言） |

跨语言项目按主语言定，不混搭。

判断式重构

# 深嵌套 → 早返回
def process(data):
    if not c1: return
    if not c2: return
    # 主逻辑

# 重复 → 提取
def common(): ...
def f1(): common()
def f2(): common()

> 重构红线：测试不绿不重构。先把测试补齐，才有改动的安全网。

与其他 skill 联动

• 重构后 → 同步跑 [analyzing-changes](../analyzing-changes/SKILL.md)（看影响面）+ [analyzing-security](../analyzing-security/SKILL.md)（防退化）
• 复杂度爆炸时 → 看是否需要 [designing-architectures](../designing-architectures/SKILL.md) 的拆分模式

使用

node scripts/quality_checker.js 
node scripts/quality_checker.js  -v       # 详细
node scripts/quality_checker.js  --json   # CI 用

收口

报告以 quality_checker.js 实际输出为准。超标项要么修复，要么在 DESIGN.md 留「为何接受」的说明。不允许悄悄忽略。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: telagod
• Source: telagod/code-abyss
• License: MIT
• Homepage: https://www.npmjs.com/package/code-abyss

Install and usage instructions live in the source repository linked above.