review-architecture

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Software Architecture Fitness Review

软件架构适配度评审

Analyze the codebase (or specified files/modules) for software architecture fitness. Identify structural problems, design violations, and maintainability risks using evidence from the code.

Reference: Fundamentals of Software Architecture, Fundamentals of Software Design, Fundamentals of API Design and Contracts — see also Fundamentals

分析代码库（或指定文件/模块）的软件架构适配度。基于代码中的证据，识别结构问题、设计违规和可维护性风险。

参考：Fundamentals of Software Architecture、Fundamentals of Software Design、Fundamentals of API Design and Contracts——另请参阅 Fundamentals。

Domain Knowledge

领域知识

```
references/rubric.md
```
is the scoring source: severity definitions, score anchors for each dimension, the N/A rule, and how to compute the overall. Read it first; it is short.
```
references/checklist.md
```
is what to inspect during the analysis steps. Its numeric thresholds (70% fan-in, 500-line classes, 50-line functions, 4 nesting levels) match the rubric.
```
references/wisdom.md
```
is optional background, auto-generated from the articles below. It has no rubric. Grep it by heading for a specific question (
```
grep -n '^#' references/wisdom.md
```
, then read one section); never read it whole.
```
scripts/import_graph.py
```
builds the internal import graph for Python and JS/TS so every run does not hand-roll one.

```
references/rubric.md
```
是评分依据：包含严重程度定义、各维度的评分锚点、N/A 规则以及总分的计算方式。先阅读该文件；其篇幅很短。
```
references/checklist.md
```
是分析步骤中需要检查的内容。其数值阈值（70% fan-in、500 行的类、50 行的函数、4 层嵌套）与评分标准一致。
```
references/wisdom.md
```
是可选的背景资料，根据下方文章自动生成，不包含评分标准。按标题使用 Grep 查找特定问题（
```
grep -n '^#' references/wisdom.md
```
，然后读取一个章节）；切勿一次性通读。
```
scripts/import_graph.py
```
用于为 Python 和 JS/TS 构建内部导入图，避免每次运行时都手工实现导入图。

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. Copy the

Config:

and

Effective weights:

lines from the resolver output into the report header (the template has the slot; they must land within the first 10 lines as the provenance trail, AC-03.1, AC-08.2). The weights are for the review-full aggregate; this report uses only

statusThresholds

. 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 提供，位于 plugin 的

scripts/

目录中向上两级处。如果 Agent 无法展开该变量，请替换为包含此

SKILL.md

的目录。

<target>

是正在评审的文件或目录。CLI 会向上遍历以发现模块级覆盖配置，并将其与根配置合并。将解析器输出中的

Config:

和

Effective weights:

行复制到报告头中（模板中已有对应位置；这些行必须位于前 10 行内，以作为溯源记录 AC-03.1、AC-08.2）。这些权重用于 review-full 聚合；本报告仅使用

statusThresholds

。由

<!-- BEGIN_EFFECTIVE_CONFIG_JSON -->

<!-- END_EFFECTIVE_CONFIG_JSON -->

界定的 JSON 代码块内的

effective

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

Workflow

工作流

Load the rubric — Read

references/rubric.md

and

references/checklist.md

Scope the review — Note the target (path or file set) and whether the user asked a specific question (for example "is
```
claude_client.py
```
too tangled?"). Map the structure with Glob/Grep: top-level directories, entry points, packages, dependency manifests, and where the tests for the target live (they may sit outside it). Decide what kind of system it is (script, library, CLI, layered app, services).
Decide applicability — For each of the 7 dimensions, decide whether anything in scope can be evaluated. Mark the rest N/A with a one-line reason (rubric.md, "N/A and evidence of absence"). A focused question narrows the emphasis, not the coverage: still score every applicable dimension, but go deepest on the ones asked about.
Map the dependency graph — Run the bundled script on the target (or its package root):
bash
```
python3 "${CLAUDE_SKILL_DIR}/scripts/import_graph.py" <target-dir>
```
It prints per-module line count, fan-in, fan-out and import lines, cycles (with import-time cycles separated from deferred ones), and modules imported by more than 70% of the others. Tests are excluded by default (
```
--include-tests
```
to add them);
```
--json
```
for machine output. For other languages, trace imports with Grep. Use these numbers as evidence for Coupling and Modularity rather than estimating.
Inspect each dimension — Walk the matching section of
```
checklist.md
```
for Coupling, Cohesion, Layering, Modularity, Naming, API Design and Maintainability. Read the code behind every candidate finding.
Verify each finding — Before keeping a candidate:
- Confirm the cited file:line says what the finding claims.
- Check the Impact by reading the code path end to end or running it (a CLI call, a tiny import, an existing test). If you could not verify it, say "unverified" in the Impact and lower confidence by at least 2. A correct citation with a wrong consequence is still a wrong finding.
- Drop anything below confidence 7 and count it.
Score — Score each applicable dimension with the rubric.md anchors, compute the overall per rubric.md (mean of scored dimensions, CRITICAL cap at 4.0), and apply status bands.
Self-check, then write — Confirm: every file:line exists and says what the finding claims; every reported finding has confidence >= 7; the overall equals the stated computation; every dimension below 6 has an action item; no secret values are reproduced (refer to secrets by file:line only). Then write the report.

加载评分标准——读取

references/rubric.md

和

references/checklist.md

。

确定评审范围——记录目标（路径或文件集），以及用户是否提出了具体问题（例如“
```
claude_client.py
```
是否过于纠缠？”）。使用 Glob/Grep 梳理结构：顶层目录、入口点、包、依赖清单，以及目标代码的测试所在位置（测试可能位于目标范围之外）。判断它属于哪种类型的系统（脚本、库、CLI、分层应用、服务）。
判断适用性——针对 7 个维度中的每一个，判断范围内是否有内容可供评估。将其余维度标记为 N/A，并附上一行原因（rubric.md 中的 "N/A and evidence of absence"）。聚焦问题只会收窄评审重点，并不会缩小覆盖范围：仍需为每个适用维度评分，但对用户询问的维度进行更深入的分析。
映射依赖图——对目标（或其包根目录）运行随附脚本：
bash
```
python3 "${CLAUDE_SKILL_DIR}/scripts/import_graph.py" <target-dir>
```
它会输出每个模块的行数、fan-in、fan-out 和 import 语句行、循环依赖（区分 import-time cycles 与 deferred cycles），以及被超过 70% 的其他模块 import 的模块。默认排除测试（使用
```
--include-tests
```
纳入测试）；使用
```
--json
```
生成机器可读输出。对于其他语言，使用 Grep 追踪 import。使用这些数据作为耦合性和模块化的证据，而不是依靠估算。
检查每个维度——逐一查看
```
checklist.md
```
中关于耦合性、内聚性、分层、模块化、命名、API 设计和可维护性的对应章节。读取每个候选发现背后的代码。
验证每个发现——保留候选发现前：
- 确认引用的 file:line 确实体现了发现所声称的问题。
- 通过端到端阅读代码路径或运行代码路径（执行一次 CLI 调用、一次小型 import 或现有测试）来检查 Impact。如果无法验证，请在 Impact 中注明 "unverified"，并将置信度至少降低 2。引用正确但所推断的后果错误，仍然属于错误发现。
- 丢弃置信度低于 7 的内容并计数。
评分——依据 rubric.md 中的锚点评分每个适用维度，按照 rubric.md 计算总分（取已评分维度的平均值，CRITICAL 上限为 4.0），并应用状态区间。
自检后编写报告——确认：每个 file:line 都存在且确实体现了发现所声称的问题；每个报告中的发现置信度均 >= 7；总分等于所声明的计算结果；每个低于 6 分的维度都有一项行动项；不复现任何密钥值（仅通过 file:line 引用密钥）。随后编写报告。

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?
Did you verify the stated Impact by reading or running the code path?

If any answer is no, do not report it (or lower its confidence until it drops out). It is better to miss a theoretical issue than to flood the report with noise. Record how many candidates were dropped so the reader knows the filter ran.

Severity definitions (CRITICAL, HIGH, MEDIUM, LOW) with architecture examples are in

references/rubric.md

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

这是代码中真实存在的模式，而不是对运行时行为的猜测吗？
能否指向一个具体文件及行号？
问题模式在正常执行中确实可以到达吗？
是否通过阅读或运行代码路径验证了所述 Impact？

如果任何一个答案为否，则不要报告该问题（或降低其置信度，直至问题被过滤掉）。漏报一个理论问题，比用噪声淹没报告更好。记录被丢弃的候选发现数量，让读者知道该过滤机制已执行。

严重程度定义（CRITICAL、HIGH、MEDIUM、LOW）及架构示例见

references/rubric.md

。

Scoring Dimensions (1-10 each)

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

Score anchors for each dimension are in

references/rubric.md

; the checks are in

references/checklist.md

Coupling — Cross-boundary import count, concrete vs abstract dependencies, shared mutable state, circular dependencies, temporal coupling
Cohesion — Single responsibility, functional cohesion, concern separation, change-reason analysis
Layering — Layer separation, dependency direction, skip-layer violations, infrastructure leakage
Modularity — Boundary clarity, public interfaces, information hiding, independent testability
Naming — Clarity, consistency, context-appropriateness, convention compliance, discoverability, truthfulness
API Design — Contract explicitness, error consistency, backward compatibility, semantic clarity, idempotency
Maintainability — Code smells, duplication, magic numbers, test coverage, documentation, dependency health

各维度的评分锚点见

references/rubric.md

，检查项见

references/checklist.md

。

耦合性——跨边界 import 数量、具体依赖与抽象依赖、共享可变状态、循环依赖、时间耦合
内聚性——单一职责、功能内聚、关注点分离、变更原因分析
分层——层次分离、依赖方向、跨层违规、基础设施泄漏
模块化——边界清晰度、公共接口、信息隐藏、独立可测试性
命名——清晰度、一致性、上下文适用性、约定遵循情况、可发现性、真实性
API 设计——契约明确性、错误一致性、向后兼容性、语义清晰度、幂等性
可维护性——代码坏味道、重复、魔法数字、测试覆盖率、文档、依赖健康度

Output Format

输出格式

Write the report to

docs/architecture-review.md

at the root of the repository that contains the target (

git -C <target> rev-parse --show-toplevel

; if the target is not in a git repo, the target directory), unless the user gives a path. When the review is scoped to a subdirectory or file set rather than the whole repo, write

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

instead (for example

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

) so a scoped run does not replace the whole-repo report. If the file already exists, overwrite it only when it is an earlier report from this skill (its first line is

# Software Architecture Fitness Review

); otherwise pick a new name and say so.

markdown

undefined

将报告写入包含目标的仓库根目录下的

docs/architecture-review.md

（

git -C <target> rev-parse --show-toplevel

；如果目标不在 Git 仓库中，则使用目标目录），除非用户指定了其他路径。当评审范围为子目录或文件集而非整个仓库时，改用

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

（例如

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

），从而避免局部评审覆盖整个仓库的报告。如果该文件已经存在，仅当它是此 skill 早期生成的报告（首行为

# Software Architecture Fitness Review

）时才可覆盖；否则请选择新文件名并说明。

markdown

undefined

Software Architecture Fitness Review

Target: <path(s) or scope reviewed> Config: <copied from resolver output> Effective weights: <copied from resolver output>

Direct Answer

(Only when the user asked a specific question. Answer it in 2-5 sentences with file:line evidence, e.g. fan-in/fan-out numbers from import_graph.py.)

Summary

Overall fitness score: X.X / 10 — <status band> (mean of <list of scored dimensions>; <CRITICAL cap applied / not applied>)

Dimension	Score	Status	Key Finding
Coupling	X/10	Healthy / Needs Attention / Critical	...
Cohesion	X/10	...	...
Layering	N/A — reason	—	...
Modularity	X/10	...	...
Naming	X/10	...	...
API Design	X/10	...	...
Maintainability	X/10	...	...

Dependency graph: <N modules, cycles, hubs, max fan-in/fan-out from import_graph.py>. Candidates dropped below confidence 7: <count> (<one-line gist each, or "none">).

Overall fitness score: X.X / 10 — <status band> (mean of <list of scored dimensions>; <CRITICAL cap applied / not applied>)

Dimension	Score	Status	Key Finding
Coupling	X/10	Healthy / Needs Attention / Critical	...
Cohesion	X/10	...	...
Layering	N/A — reason	—	...
Modularity	X/10	...	...
Naming	X/10	...	...
API Design	X/10	...	...
Maintainability	X/10	...	...

Dependency graph: <N modules, cycles, hubs, max fan-in/fan-out from import_graph.py>. Candidates dropped below confidence 7: <count> (<one-line gist each, or "none">).

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 found.
Impact: What could go wrong as the codebase evolves, and how you verified it (read path X -> Y, or ran Z).
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 found.
Impact: What could go wrong as the codebase evolves, and how you verified it (read path X -> Y, or ran Z).
Remediation: Concrete fix with code example or specific steps.

(repeat for each finding, ordered by severity)

Coupling (X/10)

Evidence: file:line references (or the place something is missing)
Issues found
Recommendations

(repeat for each dimension; N/A dimensions get one line with the reason)

Evidence: file:line references (or the place something is missing)
Issues found
Recommendations

(repeat for each dimension; N/A dimensions get one line with the reason)

Top Action Items (by impact)

Up to 5, fewer is fine. Every dimension scored below 6 needs at least one item; add items beyond 5 only for that.

[CRITICAL/HIGH/MEDIUM] Description -- file:line (Dimension)
...

Up to 5, fewer is fine. Every dimension scored below 6 needs at least one item; add items beyond 5 only for that.

[CRITICAL/HIGH/MEDIUM] Description -- file:line (Dimension)
...

Checklist Reference

See references/checklist.md for the full architecture checklist and references/rubric.md for the scoring anchors.

Reference

Based on Fundamentals of Software Architecture, Fundamentals of Software Design, Fundamentals of API Design and Contracts, and guidance from https://jeffbailey.us/categories/fundamentals/

undefined

Based on Fundamentals of Software Architecture, Fundamentals of Software Design, Fundamentals of API Design and Contracts, and guidance from https://jeffbailey.us/categories/fundamentals/

undefined