review-full

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Full Project Fitness Review

全面项目健康度审查

Run the ten domain review skills in parallel and combine their results into one weighted fitness report. This skill does not score code itself; it decides scope, reads weights from the resolver, aggregates, and shows its arithmetic so the overall can be checked by hand.

并行运行十个领域审查 skill，并将结果合并为一份加权健康度报告。本 skill 本身不直接对代码评分；它负责确定审查范围、从 resolver 读取权重、聚合结果并展示算术过程，以便手动核对总分。

Configuration

配置

Always invoke the resolver CLI to read effective weights and thresholds. Never load

fitness-config.json

directly. The CLI walks up from the review target to find module overrides and merges them with the root config per ADR-001 / ADR-002 / ADR-005.

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>

follows the scope chosen in Step 1:

User-given path: that file or directory.
Pending changes: each changed file. Override files are often gitignored, so a module override can govern a changed file without showing up in
```
git status
```
; resolving per file is the only way to catch it. Group the files by the
```
Config:
```
line they resolve to.
Whole project: the repository root (per ADR-005, only the root config applies at root scope).

Before using any output, run the same command with

validate

in place of

show

for every target.

show

exits 0 even when merged weights do not sum to 100 (its table prints

total ... ERROR

);

validate

exits 1. If validation fails, stop and show the user the error instead of scoring against a broken config.

From each

show

output keep:

The
```
Config:
```
line (which config files were applied;
```
built-in defaults
```
means none was found).
The
```
Effective weights:
```
line (all 10 domains).

The JSON block between

<!-- BEGIN_EFFECTIVE_CONFIG_JSON -->

and

<!-- END_EFFECTIVE_CONFIG_JSON -->

, which carries the weights and

statusThresholds

Save each

show

output to a temp file;

scripts/overall.py

reads it. Never hardcode weights here: a per-directory override must change scoring without editing this file (ADR-002 / FR-7). With no config at all, the resolver's built-in defaults are the weights listed in README.md under Reports.

始终调用 resolver CLI 以读取有效权重和阈值。绝不直接加载

fitness-config.json

。CLI 会从审查目标向上查找模块级覆盖配置，并依据 ADR-001 / ADR-002 / ADR-005 将其与根配置合并。

bash

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

${CLAUDE_SKILL_DIR}

是本 skill 所在目录；resolver 位于插件的

scripts/

目录下、相对位置高两层。如果 Agent 未展开该变量，请替换为包含此

SKILL.md

的目录。

其中

<target>

取决于步骤 1 选定的范围：

用户指定路径： 该文件或目录。
待处理更改： 每个已更改文件。覆盖文件通常被 gitignore，因此模块级覆盖配置可能适用于某个已更改文件，却不会出现在
```
git status
```
中；只有按文件解析才能发现它。按各文件解析出的
```
Config:
```
行对文件进行分组。
整个项目： 仓库根目录（依据 ADR-005，在根目录范围内仅根配置生效）。

在使用任何输出之前，针对每个目标运行同一命令，将

show

替换为

validate

。即使合并后的权重之和不等于 100，

show

也会以状态码 0 退出（其表格会打印

total ... ERROR

）；

validate

则以状态码 1 退出。如果验证失败，请停止操作并向用户显示错误，而不是依据损坏的配置评分。

从每个

show

输出中保留：

```
Config:
```
行（已应用哪些配置文件；
```
built-in defaults
```
表示未找到任何配置）。
```
Effective weights:
```
行（全部 10 个领域）。

<!-- BEGIN_EFFECTIVE_CONFIG_JSON -->

与

<!-- END_EFFECTIVE_CONFIG_JSON -->

之间的 JSON 块，其中包含权重和

statusThresholds

。

将每个

show

输出保存到临时文件；

scripts/overall.py

会读取它。这里绝不硬编码权重：目录级覆盖配置必须能够在不编辑此文件的情况下改变评分（ADR-002 / FR-7）。如果完全没有配置，resolver 的内置默认权重就是 README.md 中 Reports 部分列出的权重。

Workflow

工作流

Step 1: Identify Review Scope

步骤 1：确定审查范围

Pick the first that applies. An explicit request beats inferred state:

The user named files, directories, or a module: review those.
There are uncommitted changes (
```
git status --porcelain
```
, covering staged, unstaged, and untracked files): review the changed files.
Otherwise: review the whole repository.

Record the scope for the

**Scope:**

line exactly (for example,

Pending changes: scripts/fitness_config/render.py

Directory: scripts/fitness_config

). Other skills read that line to tell a diff review from a folder review.

选择最先适用的一项。明确请求优先于推断状态：

用户指定了文件、目录或模块：审查这些内容。
存在未提交的更改（
```
git status --porcelain
```
，涵盖已暂存、未暂存和未跟踪文件）：审查已更改的文件。
否则：审查整个仓库。

准确记录

**Scope:**

行中的范围（例如

Pending changes: scripts/fitness_config/render.py

或

Directory: scripts/fitness_config

）。其他 skill 会读取该行，以区分差异审查和目录审查。

Step 2: Resolve and Validate Config

步骤 2：解析并验证配置

Run

validate

then

show

per the Configuration section for each target. With pending changes spanning several configs, keep one saved

show

output per group and note which files belong to which.

针对每个目标，按照“配置”部分先运行

validate

，再运行

show

。如果待处理更改跨越多个配置，为每组保存一份

show

输出，并注明哪些文件属于哪一组。

Step 3: Decide Which Domains Apply

步骤 3：确定适用领域

Mark a domain N/A, with a reason, instead of launching it when:

Accessibility: no frontend files in scope (HTML, CSS, JSX, TSX, Vue, Svelte). Reason:
```
Skipped - no frontend code detected
```
.
Data: no database code in scope (SQL, migrations, ORM models, database config). Reason:
```
Skipped - no database code detected
```
.
Weight 0: the effective weight is 0 in every config group. Reason:
```
Skipped - weight 0 in config
```
.
Process, for a pending-changes scope: the diff touches no docs, CI, dependency manifests, or contributor files. Process judges the repository, not a diff, so scoring it would dilute the real findings. Reason:
```
Skipped - diff touches no process files
```
.

Detect within the scope, not the whole repository, so a diff review is not padded by unrelated code.

在以下情况下，将领域标记为 N/A 并说明原因，而不是启动相应审查：

可访问性： 范围内没有前端文件（HTML、CSS、JSX、TSX、Vue、Svelte）。原因：
```
Skipped - no frontend code detected
```
。
数据： 范围内没有数据库代码（SQL、迁移、ORM 模型、数据库配置）。原因：
```
Skipped - no database code detected
```
。
权重为 0： 每个配置组中的有效权重均为 0。原因：
```
Skipped - weight 0 in config
```
。
待处理更改范围内的流程： 差异未涉及文档、CI、依赖清单或贡献者文件。流程评估的是整个仓库，而非差异；若为其评分，会稀释真正发现的严重问题。原因：
```
Skipped - diff touches no process files
```
。

仅在审查范围内检测，不要在整个仓库中检测，避免差异审查被无关代码填充。

Step 4: Launch the Applicable Reviews in Parallel

步骤 4：并行启动适用的审查

Use the Task tool to launch one agent per applicable domain, passing the same scope (paths or changed-file list) to each:

Architecture (
```
/review:review-architecture
```
) - Design, coupling, naming, API fitness
Security (
```
/review:review-security
```
) - Vulnerability and compliance fitness
Reliability (
```
/review:review-reliability
```
) - Operations, observability, availability fitness
Testing (
```
/review:review-testing
```
) - Test strategy and quality fitness
Performance (
```
/review:review-performance
```
) - Scalability and efficiency fitness
Algorithms (
```
/review:review-algorithms
```
) - Algorithm choice, data structures, concurrency, correctness fitness
Data (
```
/review:review-data
```
) - Schema design, migration safety, data integrity fitness
Accessibility (
```
/review:review-accessibility
```
) - UX and a11y fitness
Process (
```
/review:review-process
```
) - Development workflow and documentation fitness
Maintainability (
```
/review:review-maintainability
```
) - Complexity, understandability, technical debt, code smells fitness

Each domain skill also writes its own report:

docs/<domain>-review.md

for a whole-repo review, or

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

for a scoped one. Ask each agent to return its report path, overall score (X.X), dimension scores, findings with severity and file:line, and whether it found any CRITICAL.

While the agents run, stay quiet. Say once which domains are running, then do not post a message as each one finishes ("Security is in", "Still waiting on…"); the next message should be the combined result. Break silence only for a failed agent or one still running long after the rest.

使用 Task 工具为每个适用领域启动一个 Agent，并向每个 Agent 传入相同的审查范围（路径或已更改文件列表）：

架构 (
```
/review:review-architecture
```
) - 设计、耦合、命名、API 适配度
安全性 (
```
/review:review-security
```
) - 漏洞与合规适配度
可靠性 (
```
/review:review-reliability
```
) - 运维、可观测性与可用性适配度
测试 (
```
/review:review-testing
```
) - 测试策略与质量适配度
性能 (
```
/review:review-performance
```
) - 可扩展性与效率适配度
算法 (
```
/review:review-algorithms
```
) - 算法选择、数据结构、并发与正确性适配度
数据 (
```
/review:review-data
```
) - Schema 设计、迁移安全与数据完整性适配度
可访问性 (
```
/review:review-accessibility
```
) - UX 与 a11y 适配度
流程 (
```
/review:review-process
```
) - 开发工作流与文档适配度
可维护性 (
```
/review:review-maintainability
```
) - 复杂度、可理解性、技术债务与代码异味适配度

每个领域 skill 还会写入自己的报告：整个仓库审查写入

docs/<domain>-review.md

，限定范围的审查写入

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

。要求每个 Agent 返回报告路径、总分（X.X）、各维度分数、带严重级别和 file:line 的发现，以及是否发现任何 CRITICAL。

Agent 运行期间保持沉默。先说明一次正在运行哪些领域，然后不要在每个领域完成时发布消息（“安全审查已完成”“仍在等待……”）；下一条消息应是合并结果。只有某个 Agent 失败，或在其余 Agent 完成后仍运行很久时，才打破沉默。

Step 5: Collect Domain Results

步骤 5：收集领域结果

For each domain, take the overall the domain skill reported (mean of its scored dimensions, capped at 4.0 when it has a CRITICAL). Keep one decimal; do not round to an integer. A domain becomes N/A when:

Step 3 skipped it.
Its review marked every dimension N/A. Reason:
```
N/A - no dimensions applied
```
.
Its agent failed or returned no score. Reason:
```
Failed - <what happened>
```
. Say so in the report; never invent a score for it.

对于每个领域，采用该领域 skill 报告的总分（其已评分维度的平均值；存在 CRITICAL 时上限为 4.0）。保留一位小数；不要四舍五入为整数。出现以下情况时，领域成为 N/A：

步骤 3 已跳过该领域。
审查将所有维度都标记为 N/A。原因：
```
N/A - no dimensions applied
```
。
Agent 失败或未返回分数。原因：
```
Failed - <what happened>
```
。在报告中如实说明；绝不虚构分数。

Step 6: Compute the Overall Score

步骤 6：计算总分

Run the bundled helper rather than doing the arithmetic in your head:

bash

python3 "${CLAUDE_SKILL_DIR}/scripts/overall.py" --resolver <saved-show-output> [--resolver <second-group>] \
  --scores "architecture=7.4,security=8.0,data=N/A,..." [--critical]

What it does, so you can check it:

Overall = Σ(weight × score) / Σ(weight) over scored domains with weight > 0. Dividing by the scored weights is the same as redistributing N/A weight proportionally.
CRITICAL cap: pass
```
--critical
```
when any domain reported a CRITICAL finding; the overall is capped at 4.0, matching the domain skills.
Status: a score at or above
```
statusThresholds.healthy[0]
```
is Healthy; at or above
```
needsAttention[0]
```
is Needs Attention; anything lower is Critical. Only the lower bounds count, so 7.5 is Needs Attention, not a gap. Defaults when absent: 8 / 5.
Several config groups: domain scores are shared, the weights differ. The helper prints one overall per group; the headline overall is the lowest, because the weakest module gates the ship decision.

Copy its

Arithmetic:

line(s) into the report.

运行随附的辅助脚本，而不是在脑中计算：

bash

python3 "${CLAUDE_SKILL_DIR}/scripts/overall.py" --resolver <saved-show-output> [--resolver <second-group>] \
  --scores "architecture=7.4,security=8.0,data=N/A,..." [--critical]

它的作用如下，便于你核对：

总分 = Σ(weight × score) / Σ(weight)，计算范围为权重 > 0 的已评分领域。除以已评分权重，等同于按比例重新分配 N/A 的权重。
CRITICAL 上限： 只要任一领域报告了 CRITICAL 发现，就传入
```
--critical
```
；总分上限为 4.0，与各领域 skill 保持一致。
状态： 分数大于或等于
```
statusThresholds.healthy[0]
```
时为 Healthy；大于或等于
```
needsAttention[0]
```
时为 Needs Attention；其余为 Critical。只有下限值参与判断，因此 7.5 属于 Needs Attention，而不是处于两者之间的空档。缺失时的默认值为 8 / 5。
多个配置组： 各领域分数共享，但权重不同。辅助脚本会为每组输出一个总分；标题总分数取最低值，因为最薄弱的模块会决定是否可以发布。

将其

Arithmetic:

行复制到报告中。

Step 7: Self-Check, Then Write the Report

步骤 7：自检，然后编写报告

Before writing, confirm:

Every cited file:line exists and says what the finding claims.
The overall and statuses match the helper output.
The
```
Config:
```
and
```
Effective weights:
```
lines are copied verbatim from the resolver.
No secret values appear; refer to secrets by file:line only.

Write

docs/fitness-report.md

at the root of the repository that contains the target, unless the user gives a path.

review-apply

and

fitness-config-init

read this fixed path. Use this structure:

markdown

undefined

编写前请确认：

每个引用的 file:line 都存在，且内容确实支持该发现。
总分和状态与辅助脚本输出一致。
```
Config:
```
和
```
Effective weights:
```
行逐字复制自 resolver 输出。
不出现任何密钥值；仅通过 file:line 引用密钥。

将报告写入仓库根目录的

docs/fitness-report.md

，除非用户另行指定路径。

review-apply

和

fitness-config-init

会读取这一固定路径。使用以下结构：

markdown

undefined

Project Fitness Report

Target: <path(s) or scope reviewed> Config: <copied from resolver output; one line per config group> Effective weights: <copied from resolver output; one line per config group> Date: YYYY-MM-DD Scope: <Directory: ... | Pending changes: file, file | Whole repository>

Overall Score: X.X / 10 (<status>)

Arithmetic: (<w>*<score> + ...) / <scored weight> = X.XX<, capped at 4.0 for a CRITICAL finding> Averaged: <domains included>. N/A: <domains excluded>.

Domain	Score	Status
Architecture	X.X/10	Healthy / Needs Attention / Critical
Data	N/A	Skipped - no database code detected
...all 10 domains...

Arithmetic: (<w>*<score> + ...) / <scored weight> = X.XX<, capped at 4.0 for a CRITICAL finding> Averaged: <domains included>. N/A: <domains excluded>.

Domain	Score	Status
Architecture	X.X/10	Healthy / Needs Attention / Critical
Data	N/A	Skipped - no database code detected
...all 10 domains...

Top 10 Action Items (Priority Order)

[CRITICAL] description - path:line
[HIGH] description - path:line

[CRITICAL] description - path:line
[HIGH] description - path:line

Domain Details

Architecture

Score X.X/10. Report: docs/architecture-review[-<scope-slug>].md <dimension scores and key findings with file:line>

Data

Skipped - no database code detected

...one section per domain, all 10...

Skipped - no database code detected

...one section per domain, all 10...

References

Based on guidance from Fundamentals. Each domain skill scores from its own

references/rubric.md


If the user asked a specific question ("is this safe to ship?"), add a `## Direct Answer` section right after the overall score. List up to 10 action items; fewer is fine when fewer findings clear confidence 7. Never pad the list.

Based on guidance from Fundamentals. Each domain skill scores from its own

references/rubric.md


如果用户提出了具体问题（例如“这可以安全发布吗？”），请在总分之后紧接着添加一个 `## Direct Answer` 章节。最多列出 10 个行动项；如果达到置信度 7 的发现较少，则可以列出更少。绝不要为了凑数而添加项目。

Action Item Prioritization

行动项优先级

Rank by severity first, then by domain weight, then by how easy the fix is:

CRITICAL - Security vulnerabilities, data loss risks, production outages
HIGH - Architecture violations causing maintenance burden, missing tests for critical paths, algorithm correctness issues, data integrity gaps
MEDIUM - Performance bottlenecks, observability gaps, process improvements, concurrency risks
LOW - Style issues, minor naming inconsistencies, nice-to-have improvements

Merge duplicates: when two domains flag the same file:line, list it once and name both domains.

先按严重级别排序，再按领域权重排序，最后按修复难度排序：

CRITICAL - 安全漏洞、数据丢失风险、生产环境中断
HIGH - 导致维护负担的架构违规、关键路径缺少测试、算法正确性问题、数据完整性缺口
MEDIUM - 性能瓶颈、可观测性缺口、流程改进、并发风险
LOW - 样式问题、轻微命名不一致、锦上添花的改进

合并重复项：当两个领域标记同一个 file:line 时，只列出一次，并注明两个领域。