code-quality-scoring

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Code Quality Scoring

代码质量评分

A vendor-neutral framework for quantifying and communicating software quality at the application and portfolio level. Most quality skills tell you how to fix one finding; this skill tells you how to score an entire codebase, estimate the cost of its debt, and explain both to people who do not read code.

Source note: The scoring frameworks below are derived from CAST Highlight's code quality indicators and methodology (https://doc.casthighlight.com/). They are paraphrased and re-expressed as a vendor-neutral model. Threshold bands and debt-density figures are CAST's proprietary calibration from their AppMarq benchmark dataset; they are presented here as attributed reference ranges, not as universal standards. Where CAST defers to open standards (COCOMO II for effort, SPDX/choosealicense for licenses, CWE/CVE for security), cite those primary sources.

一款厂商中立的框架，用于在应用与组合层面量化并传达软件质量。大多数质量相关技能会告诉你如何修复单个问题；而本技能则会教你如何为整个代码库评分、估算其债务成本，并向不懂代码的人解释这两者。

来源说明： 以下评分框架源自CAST Highlight的代码质量指标与方法论（https://doc.casthighlight.com/）。我们对其进行了转述，将其重构为厂商中立模型。阈值区间与债务密度数据来自CAST基于其AppMarq基准数据集的专有校准；此处仅作为**标注来源的参考范围**呈现，而非通用标准。当CAST遵循开源标准时（如用于工作量估算的COCOMO II、用于许可证的SPDX/choosealicense、用于安全的CWE/CVE），请引用这些原始来源。

When to Use This Skill

何时使用本技能

Use it when the question is "how healthy is this codebase, and what should we do first?" — for example:

Onboarding to an unfamiliar codebase and needing a health baseline.
Deciding whether to refactor, rewrite, or retire an application.
Prioritizing remediation across many applications (a portfolio).
Estimating the effort/cost a backlog of quality defects represents.
Presenting a quality/debt position to a manager, product owner, or executive.

Do not reach for it to fix a single defect — for that, use the language-specific quality skills (Python/Java/PHP/TS quality anti-patterns) and

code-review-standards

当你面临的问题是**“这个代码库的健康状况如何？我们首先应该做什么？”**时，可以使用本技能，例如：

接手陌生代码库，需要建立健康基线。
决定是重构、重写还是淘汰某一应用。
在多个应用（组合）中优先安排整改工作。
估算质量缺陷积压所需的工作量/成本。
向经理、产品负责人或高管汇报质量/债务状况。

不要用它来修复单个缺陷——针对这种场景，请使用特定语言的质量技能（Python/Java/PHP/TS质量反模式）以及

code-review-standards

。

Core Concept 1 — Software Health is a composite

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

Treat overall code health as the straight average of three independent dimensions, each scored 0–100. This decomposition (derived from CAST Highlight) is useful because each dimension maps to a different class of fix and a different stakeholder concern:

Dimension	A.k.a.	Measures	Maps to checklist family
Resiliency / Robustness	Software Resiliency	Will it break in production? Error handling, defensive coding, reliability	Robustness, Security
Agility / Changeability	Software Agility	Can a team understand and change it quickly? Documentation, readability, naming	Changeability, Transferability
Elegance / Efficiency	Software Elegance	Is it lean? Complexity, dead code, algorithmic/data-access efficiency	Efficiency

Software Health = avg(Resiliency, Agility, Elegance)

Threshold bands (attributed to CAST's calibration — use as guidance, not gospel):

Band	Health	Agility (note the different cutoffs per dimension)
🔴 Low / Red	below ~53	below ~54
🟠 Medium / Orange	~53–75	~54–69
🟢 High / Green	above ~75	above ~69

The key insight is not the exact numbers — it is that each dimension has its own distribution and its own remediation strategy, so a single blended grade hides the story. A codebase can be green on Resiliency (rarely crashes) yet red on Agility (nobody can change it safely). See software-health-framework.md.

将整体代码健康度视为三个独立维度的算术平均值，每个维度的评分范围为0–100。这种分解方式（源自CAST Highlight）十分实用，因为每个维度对应不同的修复类别和不同的利益相关者关注点：

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

Software Health = avg(Resiliency, Agility, Elegance)

阈值区间（源自CAST的校准——仅作指导，而非绝对标准）：

区间	健康度	敏捷性（注意各维度的阈值不同）
🔴 低/红色	~53以下	~54以下
🟠 中/橙色	~53–75	~54–69
🟢 高/绿色	~75以上	~69以上

关键洞见不是精确的数值——而是每个维度有其自身的分布和整改策略，单一的综合评分会掩盖真实情况。某个代码库可能在弹性维度为绿色（极少崩溃），但在敏捷性维度为红色（无人能安全修改）。详见**software-health-framework.md**。

Core Concept 2 — Technical debt is an effort-to-fix estimate

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

Express debt as estimated remediation effort, derived from violation density scaled by a per-line-of-code debt factor that varies by language. Higher-level / verbose languages (Java, JavaScript, PHP) tend to carry more debt per LOC than concise scripting languages (Python, shell). Always present these as attributed ranges ("Java's median debt density is roughly 3–4× Python's per industry benchmarks") rather than copied exact figures, and convert to money/time only with explicit assumptions stated. CAST's maintenance-effort model itself builds on COCOMO II. See technical-debt-estimation.md.

将债务表示为估算的整改工作量，由违规密度乘以随语言变化的每行代码债务系数得出。高级/冗长语言（Java、JavaScript、PHP）通常比简洁脚本语言（Python、shell）的每行代码债务更高。请始终将这些数据作为标注来源的范围呈现（例如“根据行业基准，Java的中位债务密度约为Python的3–4倍”），而非直接复制精确数值；只有在明确说明假设条件的情况下，才能将其转换为资金/时间成本。CAST的维护工作量模型本身基于COCOMO II构建。详见**technical-debt-estimation.md**。

Core Concept 3 — Cloud readiness is scan + survey

核心概念3 —— 云就绪性是扫描+调查的结合

Cloud maturity is the average of a code-scan score (blockers and boosters detected in source — e.g. hard-coded file paths and host names are blockers; statelessness and externalized config are boosters) and a survey score (team/operational factors the code cannot reveal). See cloud-maturity.md.

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

Core Concept 4 — Open-source safety is a three-part index

核心概念4 —— 开源安全性是三部分指标的综合

Third-party risk is the average of Security (CVE count weighted by criticality), License Compliance (share of low- vs medium- vs high-risk licenses), and Obsolescence (version gap to latest). This cross-references the Phase 1 OSS Safety work — do not duplicate it. See open-source-safety.md, and for remediation mechanics use

universal/security/security-scanning

and

toolchains/universal/dependency/dependency-audit

, which already carry the license-risk tiers and CVE-weighting framing.

第三方风险是安全性（按严重性加权的CVE数量）、许可证合规性（低/中/高风险许可证的占比）和过时性（与最新版本的差距）的平均值。这与第一阶段的OSS安全工作相互关联，请勿重复工作。详见**open-source-safety.md**；如需了解整改机制，请使用

universal/security/security-scanning

和

toolchains/universal/dependency/dependency-audit

，这两个技能已包含许可证风险等级和CVE加权框架。

Core Concept 5 — Prioritize by business impact

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

A defect-dense application nobody depends on is lower priority than a moderately-flawed revenue-critical one. Blend a technical risk score with a business impact score (failure consequences, audience size, release/maintenance effort) so remediation is ranked by risk to the business, not by raw defect count. CAST formalizes this as a ROAR-style index (risk weighted by business impact). See quality-communication-guide.md.

一个缺陷密集但无人依赖的应用，优先级低于存在中等缺陷但对收入至关重要的应用。将技术风险评分与业务影响评分（故障后果、受众规模、发布/维护工作量）相结合，使整改工作按业务风险排序，而非单纯按缺陷数量排序。CAST将其正式化为ROAR风格的指数（按业务影响加权的风险）。详见**quality-communication-guide.md**。

How to Apply (quick workflow)

应用方法（快速工作流）

Score the three health dimensions from your existing linters/scanners — map each tool's findings into Resiliency / Agility / Elegance, average to a Health score, place on the red/orange/green band.
Estimate debt — multiply violation density by the language's debt factor (as an attributed range), express as effort (hours/FTE) with assumptions stated.
Score OSS safety and cloud readiness if relevant to the decision.
Weight by business impact to rank applications/modules.
Communicate using the stakeholder framing — lead with risk and money, not rule names.

为三个健康维度评分——利用现有代码检查工具/扫描工具的结果，将每个工具的发现映射到弹性/敏捷性/简洁性维度，取平均值得到健康度评分，并归入红/橙/绿区间。
估算债务——将违规密度乘以对应语言的债务系数（作为标注来源的范围），在说明假设条件的前提下，以工作量（小时/全职员工）表示。
如有决策需求，对OSS安全性和云就绪性评分。
按业务影响加权，对应用/模块进行排序。
传达结果——采用面向利益相关者的框架，重点强调风险和成本，而非规则名称。

Anti-Patterns

反模式

Reporting a single blended grade and hiding the dimension that is actually red.
Quoting debt in exact dollars without stating the LOC, hourly rate, and density assumptions — present ranges and assumptions.
Treating CAST's threshold numbers as universal law — they are one vendor's calibration; cite them as reference context.
Ranking remediation by defect count instead of by business-weighted risk.
Duplicating the OSS license tiers here — cross-reference the Phase 1 references.

仅报告单一综合评分，掩盖实际为红色的维度。
未说明代码行数、小时费率和密度假设就精确引用债务金额——应呈现范围和假设条件。
将CAST的阈值视为通用准则——它们只是某厂商的校准值，请作为参考背景引用。
按缺陷数量排序整改优先级，而非按业务加权风险排序。
在此处重复OSS许可证等级——请关联第一阶段的参考资料。

Navigation

Software Health Framework — the Resiliency/Agility/Elegance decomposition, bands, and how to map linter output onto it.
Technical Debt Estimation — effort-to-fix model, per-language debt-density ranges (attributed), COCOMO II linkage, worked example.
Cloud Maturity — scan vs survey, code blockers and boosters, how to read a cloud-readiness score.
Open Source Safety — the Security/License/ Obsolescence index; cross-references to the dependency-audit and security-scanning skills.
Quality Communication Guide — business- impact framing, ROAR-style prioritization, presenting scores to non-technical stakeholders.

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