code-quality-scoring

代码质量评分

一个与供应商无关的框架，用于在应用和产品组合层面量化并传达软件质量。大多数质量技能会告诉你如何修复某个问题；而这项技能会告诉你如何为整个代码库评分、如何估算其技术债务的成本，以及如何向不阅读代码的人解释这两者。

来源说明： 以下评分框架源自 CAST Highlight 的代码质量指标和方法论（https://doc.casthighlight.com/）。内容经过改述，重新表达为与供应商无关的模型。阈值区间和债务密度数据来自 CAST 对其 AppMarq 基准数据集的专有校准；此处将其作为注明来源的参考区间，而非普适标准。对于 CAST 参考开放标准的部分（工作量采用 COCOMO II，许可证采用 SPDX/choosealicense，安全采用 CWE/CVE），请引用这些一手来源。

何时使用此技能

当问题是**“这个代码库的健康状况如何，我们应该先做什么？”**时使用，例如：

• 初次接触不熟悉的代码库，需要建立健康基线。
• 决定是重构、重写还是停用某个应用。
• 确定多个应用（一个产品组合）的修复优先级。
• 估算待处理的质量缺陷会带来多少工作量／成本。
• 向经理、产品负责人或高管汇报质量／技术债务状况。

不要用它来修复单个缺陷；此类问题应使用特定语言的质量技能（Python/Java/PHP/TS 质量反模式）和 code-review-standards。

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

将整体代码健康度视为三个独立维度的简单平均值，每个维度的评分范围为 0–100。这种拆分方式（源自 CAST Highlight）很有用，因为每个维度都对应不同类型的修复工作，以及不同相关方的关注点：

维度	亦称	衡量内容	对应检查清单类别
弹性／健壮性	软件弹性	是否会在生产环境中出错？错误处理、防御性编码、可靠性	健壮性、安全性
敏捷性／可变更性	软件敏捷性	团队能否快速理解和修改？文档、可读性、命名	可变更性、可移交性
简洁性／效率	软件简洁性	是否精简？复杂度、死代码、算法／数据访问效率	效率

Software Health = avg(Resiliency, Agility, Elegance)

阈值区间（注明源自 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 数量）、许可证合规性（低风险、中风险和高风险许可证的占比）和过时程度（与最新版本的差距）的平均值。这与第 1 阶段的 OSS 安全性工作交叉引用——不要重复。参见 open-source-safety.md；修复方法请使用 universal/security/security-scanning 和 toolchains/universal/dependency/dependency-audit，其中已包含许可证风险等级和 CVE 加权框架。

核心概念 5 — 根据业务影响确定优先级

一款缺陷密集、无人依赖的应用，优先级低于一款存在中等缺陷、但对收入至关重要的应用。将技术风险分数与业务影响分数（故障后果、受众规模、发布/维护工作量）结合起来，使修复工作按对业务的风险排序，而不是按原始缺陷数量排序。CAST 将此规范为 ROAR 式指数（按业务影响加权的风险）。参见 quality-communication-guide.md。

如何应用（快速工作流）

1. 评估三个健康维度：使用现有的代码检查器/扫描器——将每种工具的发现映射到韧性 / 敏捷性 / 优雅性，取平均值作为健康度分数，并标注红色/橙色/绿色区间。
2. 估算技术债——将违规密度乘以该语言的技术债系数（注明来源的范围），并在说明假设的基础上换算为工作量（小时/FTE）。
3. 如果与决策相关，评估 OSS 安全性和云就绪度。
4. 根据业务影响加权，为应用/模块排序。
5. 沟通时采用面向利益相关者的表述方式——先谈风险和成本，不要先谈规则名称。

反模式

• 只报告一个综合等级，隐藏实际处于红色区间的维度。
• 以精确金额引用技术债，却不说明 LOC、小时费率和密度假设——应提供范围并说明假设。
• 将 CAST 的阈值数字视为普遍准则——它们只是某个供应商的校准结果；引用时应将其作为参考背景。
• 按缺陷数量而非按业务加权风险为修复工作排序。
• 在此处重复 OSS 许可证等级——交叉引用第 1 阶段的参考资料。

导航

• Software Health Framework — 韧性/敏捷性/优雅性的分解、区间，以及如何将代码检查器输出映射到该框架。
• Technical Debt Estimation — 修复工作量模型、按语言划分的技术债密度范围（注明来源）、与 COCOMO II 的关联，以及示例。
• Cloud Maturity — 扫描与调查、代码中的阻碍因素和促进因素，以及如何解读云就绪度分数。
• Open Source Safety — 安全性/许可证/过时程度指数；与 dependency-audit 和 security-scanning 技能的交叉引用。
• Quality Communication Guide — 业务影响表述方式、ROAR 式优先级排序，以及如何向非技术利益相关者展示分数。

相关技能

• code-review-standards — 针对每项发现的检查清单，包含效率 + 可迁移性维度（第 1 阶段）；此技能将这些类别汇总为分数。
• security-scanning / dependency-audit — OSS 安全性的修复方法。
• software-patterns — 指出优雅性/敏捷性得分偏低的架构信号。