review-maintainability

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Maintainability & Understandability Fitness Review

可维护性与可理解性适配度审查

Analyze the codebase for maintainability and understandability fitness. Maintainability is a core quality attribute (ISO 25010); simplicity and understandability are means to achieve it. This skill evaluates structural complexity, comprehensibility, technical debt, and code smells with concrete metrics where observable.

Reference: Fundamentals of Maintainability — see also Fundamentals

分析代码库的可维护性与可理解性适配度。可维护性是一项核心质量属性（ISO 25010）；简洁性与可理解性是实现它的手段。本 skill 会在可观测的情况下，使用具体指标评估结构复杂度、可理解性、技术债和代码坏味道。

参考：可维护性基础——另见 Fundamentals。

Domain Knowledge

领域知识

```
references/rubric.md
```
is the scoring source: the single threshold table, severity definitions, 1-10 anchors per dimension, the N/A rule, and the overall-score formula. Read it first; it is short.
```
references/checklist.md
```
is what to inspect during the workflow steps. Its numbers match the rubric's threshold table.
```
references/wisdom.md
```
is optional background, auto-generated from Fundamentals of Maintainability. It holds no rubric. Grep it by heading for a specific question (e.g.
```
Mistake 3: Copy-Paste
```
); never read it whole.
```
scripts/metrics.py
```
measures what the rubric thresholds need, so the Metrics Summary is measured rather than estimated.

```
references/rubric.md
```
是评分依据：其中包含唯一的阈值表、严重性定义、每个维度的 1–10 分锚点、N/A 规则以及总分公式。先阅读它；篇幅很短。
```
references/checklist.md
```
是工作流步骤中需要检查的内容。其编号与 rubric 的阈值表一致。
```
references/wisdom.md
```
是可选的背景资料，根据 Fundamentals of Maintainability 自动生成。它不包含 rubric。按标题 grep 以查找特定问题（例如
```
Mistake 3: Copy-Paste
```
）；不要完整阅读。
```
scripts/metrics.py
```
负责测量 rubric 阈值所需的指标，因此指标摘要（Metrics Summary）是实测结果，而非估算结果。

Configuration

配置

Invoke the resolver CLI to obtain effective weights and thresholds for the review target. Never load

fitness-config.json

directly.

bash

python3 "${CLAUDE_SKILL_DIR}/../../scripts/fitness-config.py" show --path <target>

${CLAUDE_SKILL_DIR}

is this skill's directory; the resolver ships two levels up in the plugin's

scripts/

. If your agent does not expand the variable, substitute the directory containing this

SKILL.md

Where

<target>

is the file or directory under review. The CLI walks up to discover any module override and merges it with the root config. Include the

Config:

and

Effective weights:

lines from the resolver output within the first 10 lines of the final report as the provenance trail (AC-03.1, AC-08.2). The

effective

object inside the JSON block delimited by

<!-- BEGIN_EFFECTIVE_CONFIG_JSON -->

<!-- END_EFFECTIVE_CONFIG_JSON -->

carries weights, status thresholds, security, and scoring for any programmatic needs.

调用 resolver CLI，以获取审查目标的有效权重和阈值。绝不直接加载

fitness-config.json

。

bash

python3 "${CLAUDE_SKILL_DIR}/../../scripts/fitness-config.py" show --path <target>

${CLAUDE_SKILL_DIR}

是本 skill 的目录；resolver 位于 plugin 的

scripts/

目录下两级目录处。如果你的 Agent 无法展开该变量，请替换为包含本

SKILL.md

的目录。

其中，

<target>

是待审查的文件或目录。CLI 会向上遍历目录，查找模块级覆盖配置，并将其与根配置合并。在最终报告的前 10 行内包含 resolver 输出中的

Config:

和

Effective weights:

行，作为来源追溯记录（AC-03.1、AC-08.2）。由

<!-- BEGIN_EFFECTIVE_CONFIG_JSON -->

<!-- END_EFFECTIVE_CONFIG_JSON -->

界定的 JSON 块中的

effective

对象包含权重、状态阈值、安全性和评分信息，可供程序化使用。

Workflow

工作流

Read the rubric — Read

references/rubric.md

, then skim

references/checklist.md

Identify scope — List source files and the primary language(s). Exclude generated code (
```
*.min.js
```
,
```
*_pb2.py
```
, build output) and vendored dependencies (
```
vendor/
```
,
```
third_party/
```
, copied-in libraries), and name what you excluded in the report's Target line.
- Vendored code: decide by ownership, not size. The question is whether the team maintains this copy. Review it as owned code when it has local edits or local commits (
```
git log -- <path>
```
  ), or when it is what actually runs (the project imports the copy, not an installed package). Say so in the Target line ("includes vendored fork of X"). Exclude it when it is an unmodified copy of a published version (compare against the version named in the manifest or lockfile when you can fetch it read-only) or when nothing in scope loads it; then name it under excluded, and report the dead copy itself under Technical Debt. If you cannot tell, treat it as owned and say why.
- To measure without an excluded copy that is not under
```
vendor/
```
  or
```
third_party/
```
  , pass
```
--exclude <glob>
```
  to the metrics helper (step 4).
Decide applicability — For each of the five dimensions, decide whether anything in scope can be evaluated. Mark the rest
```
N/A — <reason>
```
per the rubric's N/A rule. A dimension with clean code is scored, not N/A.
Measure — Run the metrics helper on the target (add
```
--include-vendored
```
if step 2 decided vendored code is the project):
bash
```
python3 "${CLAUDE_SKILL_DIR}/scripts/metrics.py" <target> --top 15
```
It reports max function LOC, cyclomatic complexity, nesting, parameter count, class and file size, and every TODO/FIXME/HACK/XXX and lint suppression, each with file:line, and marks rows over the finding thresholds.
```
--include-vendored
```
scans
```
vendor/
```
-style directories it skips by default;
```
--exclude <glob>
```
(repeatable) drops other paths. Python is AST-exact; brace languages are approximate, so read the code before basing a HIGH finding on a brace-language number. For unsupported languages, or functions the helper misses, measure by reading and mark the value
```
(read)
```
.
Assess structural complexity — Start from the metrics output; read the worst functions to confirm and to judge cognitive complexity.
Evaluate understandability — Naming, control-flow readability, "why" comments on non-obvious logic, consistency between modules.
Count technical debt indicators — Use the markers and suppressions from step 4; check whether each TODO has an issue reference. Look for duplicated blocks (
```
diff
```
near-identical files; grep for a distinctive line from a suspected copy), magic values, and hardcoded configuration.
Assess coupling and dependency depth — Trace imports: fan-in per module, cycles, skip-layer imports, inheritance depth.
Tally code smells — God classes (or closure factories / stateful modules in class-less code), long methods, feature envy, shotgun surgery, dead or commented-out code. Normalize per 1,000 non-blank LOC as the rubric asks.
Score each applicable dimension against the rubric anchors, with file:line evidence.
Self-check, then write the report (see Output Format). Before writing, confirm:
- every cited file:line exists and shows what the finding claims;
- every finding has confidence >= 7 and all eight template fields (Severity through Remediation);
- the overall score equals the stated computation (mean of scored dimensions, CRITICAL cap applied);
- Metrics Summary values match the metrics output;
- no secret value appears anywhere in the report (see Secrets below).

阅读 rubric——阅读

references/rubric.md

，然后浏览

references/checklist.md

。

确定范围——列出源文件及主要语言。排除生成的代码（
```
*.min.js
```
、
```
*_pb2.py
```
、构建输出）和 vendored dependencies（
```
vendor/
```
、
```
third_party/
```
、复制进来的库），并在报告的 Target 行中注明排除项。
- **Vendored code：按所有权而非体积判断。**关键是团队是否维护这个副本。如果副本存在本地修改或本地 commit（
```
git log -- <path>
```
  ），或者实际运行的就是该副本（项目导入该副本，而不是已安装的 package），则将其作为自有代码审查。在 Target 行中说明这一点（“includes vendored fork of X”）。如果它是已发布版本的未经修改副本（在可以只读获取时，与 manifest 或 lockfile 中指定的版本进行比较），或者范围内没有任何内容加载它，则将其排除；在 excluded 下注明该路径，并将其无效副本本身作为 Technical Debt 报告。如果无法判断，则将其视为自有代码并说明原因。
- 如果需要测量某个不在
```
vendor/
```
  或
```
third_party/
```
  下的排除副本，请向 metrics helper 传递
```
--exclude <glob>
```
  （步骤 4）。
确定适用性——针对五个维度中的每一个，判断范围内是否有可评估的内容。按照 rubric 的 N/A 规则，将其余维度标记为
```
N/A — <reason>
```
。代码干净的维度应当评分，而不是标为 N/A。
测量——对目标运行 metrics helper；如果步骤 2 判定 vendored code 属于项目，则添加
```
--include-vendored
```
：
bash
```
python3 "${CLAUDE_SKILL_DIR}/scripts/metrics.py" <target> --top 15
```
它会报告最大函数 LOC、圈复杂度、嵌套深度、参数数量、类大小和文件大小，以及每个 TODO/FIXME/HACK/XXX 和 lint suppression；每项均附带 file:line，并标记超过发现阈值的行。
```
--include-vendored
```
会扫描默认跳过的
```
vendor/
```
类目录；
```
--exclude <glob>
```
可重复使用，以移除其他路径。Python 的 AST 结果是精确的；花括号语言的结果是近似值，因此在对花括号语言的数值作出 HIGH 级发现前，必须阅读代码。对于不支持的语言或 helper 遗漏的函数，应通过阅读代码进行测量，并将数值标记为
```
(read)
```
。
评估结构复杂度——从指标输出开始；阅读表现最差的函数，以确认指标并判断认知复杂度。
评估可理解性——检查命名、控制流可读性、对非显而易见逻辑的 why 注释，以及模块之间的一致性。
统计技术债指标——使用步骤 4 中的标记和 suppression；检查每个 TODO 是否关联 issue。查找重复代码块（使用
```
diff
```
比较近乎相同的文件；grep 疑似副本中的特征行）、magic values 和硬编码配置。
评估耦合与依赖深度——追踪 imports：每个模块的 fan-in、循环依赖、跨层 imports 和继承深度。
统计 code smells——God Class（对于无类代码，则检查 closure factory 或有状态模块）、long method、feature envy、shotgun surgery、dead code 或 commented-out code。按照 rubric 的要求，以每 1,000 个非空 LOC 进行归一化。
评分——根据 rubric 锚点对每个适用维度评分，并提供 file:line 证据。
自检，然后撰写报告（参见“输出格式”）。撰写前确认：
- 每个引用的 file:line 都存在，并且确实显示发现所描述的内容；
- 每项发现的置信度均 >= 7，并且包含模板中的全部八个字段（从 Severity 到 Remediation）；
- 总分等于所述计算方式（已评分维度的平均值，并应用 CRITICAL 上限）；
- Metrics Summary 中的数值与 metrics 输出一致；
- 报告中的任何位置都不包含 secret value（参见“Secrets”）。

Confidence and Severity

置信度与严重性

Only report findings with confidence >= 7/10. For each finding, assess:

Is this a real pattern in the code, not a guess about runtime behavior?
Can you point to a specific file and line?
Is the problematic pattern actually reachable in normal execution?

If any answer is no, do not report it. It is better to miss a theoretical issue than to flood the report with noise.

Severity levels (CRITICAL, HIGH, MEDIUM, LOW) are defined with maintainability examples in

references/rubric.md

. Tie severity to the threshold table: over Severe is HIGH, over Finding is MEDIUM, between Target and Finding is LOW.

仅报告置信度 >= 7/10 的发现。针对每项发现，评估：

这是代码中真实存在的模式，而不是对运行时行为的猜测吗？
能否指出具体文件和行号？
问题模式在正常执行过程中确实可达吗？

如果任一答案为否，则不要报告。漏掉一个理论问题，好过用噪声淹没报告。

严重性级别（CRITICAL、HIGH、MEDIUM、LOW）及可维护性示例定义在

references/rubric.md

中。将严重性与阈值表关联：超过 Severe 为 HIGH，超过 Finding 为 MEDIUM，介于 Target 与 Finding 之间为 LOW。

Secrets

Maintainability targets often contain hardcoded credentials, tokens, or session cookies. Never reproduce a secret value in Evidence, code excerpts, or remediation examples: cite the file:line and write

<redacted>

in place of the value. Here, hardcoded credentials count only as configuration-in-code debt (Technical Debt). Leave exposure, rotation, and severity to

review-security

, and add one line to the report recommending it ("Hardcoded credentials at file:line; run review-security").

可维护性审查目标中通常包含硬编码凭据、token 或 session cookie。绝不能在 Evidence、代码摘录或修复示例中复现 secret value：应引用 file:line，并以

<redacted>

替代具体值。在此，硬编码凭据仅计为代码内配置债务（Technical Debt）。暴露情况、轮换和严重性留给

review-security

处理，并在报告中添加一行建议（“file:line 处存在硬编码凭据；请运行 review-security”）。

Scoring Dimensions (1-10 each)

评分维度（每项 1–10 分）

Anchors for each band are in

references/rubric.md

Structural Complexity — Cyclomatic complexity, nesting depth, LOC per function/class, parameter count
Understandability / Comprehensibility — Naming clarity, control-flow readability, documentation of non-obvious logic, consistency
Technical Debt Indicators — TODO/FIXME counts, duplication, magic numbers, lint suppressions, stale comments
Coupling and Dependency Depth — Afferent/efferent coupling, inheritance depth, dependency tree depth, boundary respect
Code Smell Density — God classes, long methods, feature envy, shotgun surgery, dead code

各分段的锚点位于

references/rubric.md

。

结构复杂度（Structural Complexity）——圈复杂度、嵌套深度、每个函数或类的 LOC、参数数量
可理解性 / 易懂性（Understandability / Comprehensibility）——命名清晰度、控制流可读性、非显而易见逻辑的文档说明、一致性
技术债指标（Technical Debt Indicators）——TODO/FIXME 数量、重复代码、magic number、lint suppression、陈旧注释
耦合与依赖深度（Coupling and Dependency Depth）——afferent/efferent coupling、继承深度、依赖树深度、边界遵循情况
code smell 密度（Code Smell Density）——God Class、long method、feature envy、shotgun surgery、dead code

Output Format

输出格式

Write the report at the root of the repository that contains the target (the nearest ancestor with

.git

; the target directory itself if there is none), unless the user names a path:

Whole repository:
```
docs/maintainability-review.md
```

A subdirectory or file set:

docs/maintainability-review-<scope-slug>.md

(e.g.

docs/maintainability-review-scripts-fitness-config.md

), so a scoped review does not overwrite the whole-repo report.

Use this structure:

markdown

undefined

将报告写入包含目标的仓库根目录（最近的包含

.git

的祖先目录；如果没有，则写入目标目录本身），除非用户指定了路径：

整个仓库：
```
docs/maintainability-review.md
```

子目录或文件集：

docs/maintainability-review-<scope-slug>.md

（例如

docs/maintainability-review-scripts-fitness-config.md

），避免范围审查覆盖整个仓库的报告。

使用以下结构：

markdown

undefined

Maintainability & Understandability Fitness Review

Target: <path(s) reviewed; languages; N source files, N non-blank LOC; excluded: ...> Config: <copied from resolver output> Effective weights: <copied from resolver output>

Direct Answer

(Only when the user asked a specific question, e.g. "is cli.py getting too big?" Answer it in 2-4 sentences with the numbers.)

Summary

Overall fitness score: X.X / 10 (mean of <list of scored dimensions>) — <Healthy / Needs Attention / Critical>

Dimension	Score	Key Finding
Structural Complexity	X/10	...
Understandability	X/10	...
Technical Debt Indicators	X/10	...
Coupling and Dependency Depth	X/10 or N/A — reason	...
Code Smell Density	X/10	...

Overall fitness score: X.X / 10 (mean of <list of scored dimensions>) — <Healthy / Needs Attention / Critical>

Dimension	Score	Key Finding
Structural Complexity	X/10	...
Understandability	X/10	...
Technical Debt Indicators	X/10	...
Coupling and Dependency Depth	X/10 or N/A — reason	...
Code Smell Density	X/10	...

Detailed Findings

Finding 1: [Title]

Severity: CRITICAL / HIGH / MEDIUM / LOW
Confidence: X/10
Dimension: [which scoring dimension]
Location: file:line
Description: What the issue is and why it matters.
Evidence: The specific code pattern or metric found (secrets as
```
<redacted>
```
).
Impact: What could go wrong during maintenance or refactoring.
Remediation: Concrete fix with code example or specific steps.

(repeat for each finding, ordered by severity)

Severity: CRITICAL / HIGH / MEDIUM / LOW
Confidence: X/10
Dimension: [which scoring dimension]
Location: file:line
Description: What the issue is and why it matters.
Evidence: The specific code pattern or metric found (secrets as
```
<redacted>
```
).
Impact: What could go wrong during maintenance or refactoring.
Remediation: Concrete fix with code example or specific steps.

(repeat for each finding, ordered by severity)

Structural Complexity (X/10)

Evidence: file:line references
Issues found
Recommendations

(repeat for each dimension)

Evidence: file:line references
Issues found
Recommendations

(repeat for each dimension)

Action Items (up to 5, by impact)

[CRITICAL/HIGH/MEDIUM] Description -- file:line

(Fewer than 5 is fine; do not pad with low-value items.)

[CRITICAL/HIGH/MEDIUM] Description -- file:line

(Fewer than 5 is fine; do not pad with low-value items.)

Metrics Summary

Measured with scripts/metrics.py (<ast | brace (approximate)>); values marked (read) were measured by reading the code. Targets from the rubric's threshold table.

Metric	Observed	Target / Finding	Status
Max LOC per function	X (file:line)	<= 30 / > 50	...
Max cyclomatic complexity	X (file:line)	<= 10 / > 15	...
Max nesting depth	X (file:line)	<= 3 / > 4	...
Max parameters	X (file:line)	<= 4 / > 5	...
Largest class (or closure/stateful module used instead)	X (file:line)	<= 300 / > 500	...
Largest file (non-blank LOC)	X (file)	<= 500 / > 1000	...
Untracked TODO/FIXME/HACK	X	< 5 / >= 5	...
Lint/type suppressions	X	justified / blanket or >= 5 unjustified	...

Measured with scripts/metrics.py (<ast | brace (approximate)>); values marked (read) were measured by reading the code. Targets from the rubric's threshold table.

Metric	Observed	Target / Finding	Status
Max LOC per function	X (file:line)	<= 30 / > 50	...
Max cyclomatic complexity	X (file:line)	<= 10 / > 15	...
Max nesting depth	X (file:line)	<= 3 / > 4	...
Max parameters	X (file:line)	<= 4 / > 5	...
Largest class (or closure/stateful module used instead)	X (file:line)	<= 300 / > 500	...
Largest file (non-blank LOC)	X (file)	<= 500 / > 1000	...
Untracked TODO/FIXME/HACK	X	< 5 / >= 5	...
Lint/type suppressions	X	justified / blanket or >= 5 unjustified	...

Checklist Reference

See review-maintainability/references/checklist.md for the full checklist.

Reference

Based on Fundamentals of Maintainability and guidance from https://jeffbailey.us/categories/fundamentals/

undefined

Based on Fundamentals of Maintainability and guidance from https://jeffbailey.us/categories/fundamentals/

undefined