code-quality-scoring

用途

Code Quality Scoring 是一个厂商中立的框架，用于在应用和组合（portfolio）层面量化并沟通软件质量。多数质量类技能告诉你如何修复单个问题，而这个技能告诉你如何给整个代码库打分、估算其债务成本，并向不读代码的人解释这两者。

适用场景包括：

接手不熟悉的代码库，需要一份健康基线。
决定是重构、重写还是淘汰某个应用。
在多个应用（组合）之间排定修复优先级。
估算一批质量缺陷积压所代表的工作量/成本。
向经理、产品负责人或高管汇报质量/债务状况。

不适用于修复单个缺陷——那应使用语言特定的质量技能（Python/Java/PHP/TS 质量反模式）和 code-review-standards。

来源说明：以下评分框架源自 CAST Highlight 的代码质量指标与方法论（https://doc.casthighlight.com/），经改写为厂商中立模型。阈值区间与债务密度数字是 CAST 基于其 AppMarq 基准数据集的专有校准，此处作为带署名的参考区间呈现，而非通用标准。凡 CAST 引用开放标准之处（工作量用 COCOMO II、许可证用 SPDX/choosealicense、安全用 CWE/CVE），应引用那些一手来源。

核心概念 1 — 软件健康度是复合指标

将整体代码健康度视为三个独立维度的算术平均，每个维度 0–100 分。这一分解（源自 CAST Highlight）之所以有用，是因为每个维度对应不同类别的修复和不同利益相关者的关切：

维度	别名	衡量内容	对应检查清单族
韧性/健壮性	Software Resiliency	会在生产环境崩溃吗？错误处理、防御性编码、可靠性	健壮性、安全
敏捷性/可变更性	Software Agility	团队能否快速理解并修改它？文档、可读性、命名	可变更性、可迁移性
优雅性/效率	Software Elegance	是否精简？复杂度、死代码、算法/数据访问效率	效率

软件健康度 = avg(韧性, 敏捷性, 优雅性)

阈值区间（署名 CAST 校准——作为指导而非铁律）：

区间	健康度	敏捷性（各维度切点不同）
🔴 低/红	低于约 53	低于约 54
🟠 中/橙	约 53–75	约 54–69
🟢 高/绿	高于约 75	高于约 69

关键洞见不在于具体数字，而在于每个维度有自己的分布和修复策略，因此单一混合评分会掩盖真相。一个代码库可能在韧性上是绿色（很少崩溃），但在敏捷性上是红色（没人能安全地修改它）。详见 software-health-framework.md。

核心概念 2 — 技术债务是修复工作量估算

将债务表达为估算的修复工作量，由违规密度乘以按语言区分的每行代码债务因子推导。更高级/冗长的语言（Java、JavaScript、PHP）每行代码往往比简洁的脚本语言（Python、shell）承载更多债务。始终以带署名的区间呈现（“按行业基准，Java 的债务密度中位数约为 Python 的 3–4 倍”），而非照抄精确数字，并且只有在明确陈述假设时才换算成金钱/时间。CAST 的维护工作量模型本身建立在 COCOMO II 之上。详见 technical-debt-estimation.md。

核心概念 3 — 云就绪度是扫描 + 调研

云成熟度是代码扫描分（源码中检测到的阻碍项和促进项——例如硬编码文件路径和主机名是阻碍项；无状态性和外置配置是促进项）与调研分（代码无法揭示的团队/运营因素）的平均。详见 cloud-maturity.md。

核心概念 4 — 开源安全是三部分指数

第三方风险是安全（按严重性加权的 CVE 数量）、许可证合规（低/中/高风险许可证的占比）和过时程度（与最新版本的版本差距）三者的平均。这与 Phase 1 的 OSS Safety 工作交叉引用——不要重复。详见 open-source-safety.md；修复机制请使用 universal/security/security-scanning 和 toolchains/universal/dependency/dependency-audit，它们已包含许可证风险层级和 CVE 加权框架。

核心概念 5 — 按业务影响排优先级

一个没人依赖但缺陷密集的应用，优先级低于一个中等缺陷但关乎收入的应用。将技术风险分与业务影响分（故障后果、受众规模、发布/维护工作量）混合，使修复按对业务的风险排序，而非按原始缺陷数。CAST 将此形式化为 ROAR 式指数（按业务影响加权的风险）。详见 quality-communication-guide.md。

如何应用（快速工作流）

从现有 linter/扫描器为三个健康维度打分——将每个工具的发现映射到韧性/敏捷性/优雅性，取平均得出健康分，定位到红/橙/绿区间。
估算债务——将违规密度乘以该语言的债务因子（作为带署名的区间），以工作量（小时/FTE）表达并陈述假设。
若与决策相关，评估 OSS 安全性和云就绪度。
按业务影响加权，对应用/模块排序。
使用利益相关者框架沟通——以风险和金钱开头，而非规则名称。

反模式

只报告单一混合评分，隐藏实际为红色的维度。
引用精确美元债务数字却不说明 LOC、时薪和密度假设——应呈现区间和假设。
把 CAST 的阈值数字当作通用法则——它们只是一家厂商的校准；应作为参考背景引用。
按缺陷数而非业务加权风险排序修复。
在此重复 OSS 许可证层级——应交叉引用 Phase 1 参考。

Software Health Framework — 韧性/敏捷性/优雅性分解、区间，以及如何将 linter 输出映射到其上。
Technical Debt Estimation — 修复工作量模型、按语言的债务密度区间（带署名）、COCOMO II 关联、示例。
Cloud Maturity — 扫描 vs 调研、代码阻碍项和促进项、如何解读云就绪分。
Open Source Safety — 安全/许可证/过时指数；交叉引用 dependency-audit 和 security-scanning 技能。
Quality Communication Guide — 业务影响框架、ROAR 式优先级、向非技术利益相关者呈现评分。

技能介绍

用途