review-performance

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Performance and Scalability Fitness Review

性能与可扩展性健康度审查

Analyze the codebase (or specified files/modules) for performance and scalability fitness. Identify hot paths, inefficient patterns, and scaling bottlenecks using evidence from the code.

Reference: Fundamentals of Software Performance, Fundamentals of Software Scalability, Fundamentals of Software Caching — see also Fundamentals

分析代码库（或指定的文件/模块）的性能与可扩展性健康度。基于代码中的证据，找出热路径、低效模式和扩展瓶颈。

参考：软件性能基础、软件可扩展性基础、软件缓存基础——另见基础

Domain Knowledge

领域知识

Three references, with different jobs:

```
references/rubric.md
```
is the scoring source: severity definitions, 1-10 anchors per dimension, where a finding belongs, the N/A rule, and the overall-score computation. Read it first; it is short. Using it keeps scores repeatable across runs.
```
references/checklist.md
```
is what to look for during the analysis steps, section by section.
```
references/wisdom.md
```
is optional background, auto-generated from the blog posts below. It has no rubric. Grep it by heading for a specific question (for example "percentiles" or "stampede"); never read it whole, it is about 86 KB.

Sources for wisdom.md:

三份参考资料各有不同用途：

```
references/rubric.md
```
是评分依据：包含严重程度定义、各维度 1-10 分的锚点、发现归属规则、不适用规则和总分计算方式。先阅读该文件；它篇幅很短。使用它可以确保多次运行之间的评分保持一致。
```
references/checklist.md
```
说明分析过程中需要逐节检查的内容。
```
references/wisdom.md
```
是可选的背景资料，根据下方博客文章自动生成。它不包含评分规则。可以按标题 grep 查找特定问题，例如“percentiles”或“stampede”；切勿全文读取，因为它约有 86 KB。

wisdom.md 的来源：

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 verbatim into the report header (see Output Format) as the provenance trail (AC-03.1, AC-08.2); they record exactly which config produced the scores, so a paraphrase or a pointer to another file breaks the trail. 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; use its

statusThresholds

for the status band.

The resolver resolves from the target's location, not your working directory, so pass the target as an absolute path when it lives in another repository. When the request names several targets, run the resolver once per target. If every run prints the same

Config:

and

Effective weights:

lines, copy them once. If they differ, copy each pair, prefixed with its target (

Config (scripts/): ...

), and keep all of them in the header.

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

fitness-config.json

。

bash

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

${CLAUDE_SKILL_DIR}

是此 skill 所在的目录；resolver 随插件提供，位于上两级的

scripts/

中。如果你的 Agent 无法展开该变量，请替换为包含此

SKILL.md

的目录。

其中，

<target>

是待审查的文件或目录。CLI 会从目标所在位置逐级向上查找模块覆盖配置，并将其与根配置合并。将 resolver 输出中的

Config:

和

Effective weights:

行原样复制到报告头部（见“输出格式”），作为来源追踪记录（AC-03.1、AC-08.2）；这些行会准确记录生成评分所使用的配置，任何改写或改为指向其他文件都会破坏追踪链。由

<!-- BEGIN_EFFECTIVE_CONFIG_JSON -->

<!-- END_EFFECTIVE_CONFIG_JSON -->

限定的 JSON 代码块中的

effective

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

statusThresholds

判断状态区间。

resolver 根据目标所在位置而不是当前工作目录进行解析，因此当目标位于另一个仓库中时，应将目标作为绝对路径传入。当请求指定多个目标时，对每个目标分别运行一次 resolver。如果每次运行输出的

Config:

和

Effective weights:

行都相同，只需复制一次。如果它们不同，则分别复制每一对内容并添加目标前缀（例如

Config (scripts/): ...

），并将它们全部保留在头部。

Workflow

工作流

Read the rubric and checklist — Read
```
references/rubric.md
```
, then
```
references/checklist.md
```
. Do not read
```
wisdom.md
```
up front.
Scope and resolve — Settle the target path(s) and run the resolver for each (see Configuration). Note the repository root that contains the target; the report goes there.
Decide applicability — For each of the six dimensions, decide whether the target has anything for it to evaluate (any DB access? any cache or repeated expensive work? any batch or streaming job?). Mark the rest
```
N/A
```
with a reason and a cited absence, per rubric.md. This keeps placeholder scores out of the average and out of review-full.
Identify hot paths — Find where work grows with input. The kind of code decides where to look:
- Services: request handlers, API endpoints, message consumers, background workers.
- CLIs and scripts: the
```
main
```
  /entry point and the loop over files, rows, or items it processes.
- CI: scripts called from
```
.github/workflows/
```
  or similar; anything that walks the repo or fetches per item.
- Batch and ETL: the per-record or per-batch loop and its reads and writes.
- ML inference: model loading,
```
encode
```
  /
```
embed
```
  /
```
predict
```
  calls, similarity loops, and whether results are recomputed each run.
If the user named a symptom ("slow as post count grows"), start from the code that iterates over that collection.
Trace data flow — For each hot path, trace what gets queried, fetched, computed, and cached, from entry to output.
Analyze the applicable dimensions — Work through the matching
```
checklist.md
```
sections: algorithmic complexity (1, 5), database interactions (2), caching (3), scalability (4), resource utilization (6), data pipelines (7), and CLI/CI/batch/ML paths (8). Look at the actual line before writing a finding; grep hits are leads, not evidence.
Score — Assign severities and dimension scores from
```
rubric.md
```
, each with file:line evidence. File each finding under the one dimension rubric.md assigns it.
Self-check, then write — Before writing the report, re-open each cited location and confirm:
- every file:line exists and the line shows what the finding claims (line numbers drift as you read; fix them now);
- every finding has confidence >= 7;
- the overall equals the stated mean of the scored dimensions (with the CRITICAL cap applied);
- no secret values appear in the report (refer to secrets by file:line only).

阅读评分规则和检查清单——先阅读
```
references/rubric.md
```
，然后阅读
```
references/checklist.md
```
。不要预先阅读
```
wisdom.md
```
。
确定范围并解析配置——确定目标路径，并对每个路径运行 resolver（见“配置”）。记录包含目标的仓库根目录；报告将写入该目录。
判断适用性——对于六个维度中的每一个，判断目标是否存在可供评估的内容（是否有数据库访问？是否有缓存或重复的高开销工作？是否有批处理或流式作业？）。按照 rubric.md 的要求，将其余维度标记为
```
N/A
```
，并说明原因及缺失依据。这样可以防止占位分数被计入平均值和 review-full。
找出热路径——找出工作量随输入规模增长而增加的位置。代码类型决定查找位置：
- 服务：请求处理器、API 端点、消息消费者和后台 worker。
- CLI 和脚本：
```
main
```
  /入口点，以及遍历所处理文件、行或条目的循环。
- CI：
```
.github/workflows/
```
  或类似位置调用的脚本；遍历仓库或逐项获取内容的代码。
- 批处理和 ETL：逐记录或逐批次的循环及其读写操作。
- ML 推理：模型加载、
```
encode
```
  /
```
embed
```
  /
```
predict
```
  调用、相似度循环，以及结果是否在每次运行时重新计算。
如果用户指出了某种症状（例如“随着帖子数量增长而变慢”），则从遍历相应集合的代码开始检查。
追踪数据流——对于每条热路径，追踪从入口到输出过程中查询、获取、计算和缓存了哪些数据。
分析适用维度——逐节执行
```
checklist.md
```
中适用的检查：算法复杂度（1、5）、数据库交互（2）、缓存（3）、可扩展性（4）、资源利用率（6）、数据管道（7），以及 CLI/CI/批处理/ML 路径（8）。在写出发现之前查看实际代码行；grep 命中只是线索，不能作为证据。
评分——根据
```
rubric.md
```
分配严重程度和维度分数，并为每项发现提供 file:line 证据。按照 rubric.md 的规定，将每项发现归入其唯一对应的维度。
自检，然后撰写报告——在写入报告之前，重新打开每个引用位置并确认：
- 每个 file:line 均存在，且对应行显示了发现所声称的内容（阅读过程中行号可能发生变化；此时应予以修正）；
- 每项发现的置信度均 >= 7；
- 总分等于已评分维度所声明的平均值（并应用 CRITICAL 封顶规则）；
- 报告中不包含任何机密值（仅通过 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?

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) and their performance-specific examples are defined in

references/rubric.md

. Severity depends on whether the input grows and whether the path is hot, so state both in the finding.

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

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

如果任一答案为否，则不要报告该项。漏掉一个理论问题，优于让报告充斥噪声。

严重程度级别（CRITICAL、HIGH、MEDIUM、LOW）及其性能场景示例在

references/rubric.md

中定义。严重程度取决于输入是否会增长以及路径是否热，因此每项发现中都应说明这两点。

Scoring Dimensions (1-10 each)

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

Score anchors for each dimension are in

references/rubric.md

; checks for each are in

references/checklist.md

. A dimension with nothing to evaluate is

N/A

, not a number.

Algorithmic Efficiency — Big-O complexity of hot paths, data structure selection, bounded vs unbounded collections
Database Design — N+1 queries, indexing, connection pooling, result set bounding, query patterns
Caching Strategy — Cache coverage (including repeated model inference), TTL/invalidation, stampede protection, bounded growth, observability
Scalability Readiness — Stateless design, downstream resilience, database scaling, async or concurrent processing, backpressure
Resource Utilization — Memory bounds, connection pools, timeouts, payload sizing, model/client reuse, inference batching, thread/goroutine management
Data Pipeline Efficiency — Incremental processing, validation placement, error isolation, idempotency, schema handling

每个维度的评分锚点见

references/rubric.md

，相应检查项见

references/checklist.md

。没有可评估内容的维度应记为

N/A

，而不是数字。

算法效率——热路径的 Big-O 复杂度、数据结构选择、有界与无界集合
数据库设计——N+1 查询、索引、连接池、结果集大小限制、查询模式
缓存策略——缓存覆盖范围（包括重复的模型推理）、TTL/失效机制、stampede 防护、有界增长、可观测性
可扩展性准备度——无状态设计、下游韧性、数据库扩展、异步或并发处理、backpressure
资源利用率——内存边界、连接池、超时、载荷大小、模型/客户端复用、推理批处理、线程/goroutine 管理
数据管道效率——增量处理、校验环节的位置、错误隔离、幂等性、schema 处理

Output Format

输出格式

Write the report to

docs/performance-review.md

at the root of the repository that contains the target, unless the user gives a path. For a review scoped to a subdirectory or a file set, write

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

instead (for example

docs/performance-review-github-scripts.md

), so a scoped run does not replace the whole-repo report. Use this structure:

markdown

undefined

除非用户指定路径，否则将报告写入包含目标的仓库根目录下的

docs/performance-review.md

。对于限定到子目录或一组文件的审查，则改为写入

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

（例如

docs/performance-review-github-scripts.md

），以免限定范围的运行覆盖整个仓库的报告。使用以下结构：

markdown

undefined

Performance and Scalability Review

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

Direct Answer

(Only when the user asked a specific question, such as "why does this get slow?" Two to five sentences answering it, pointing at the findings below.)

Summary

Overall fitness score: X.X / 10 (mean of <list the scored dimensions>; <N/A dimensions> excluded) — <status band>

Dimension	Score	Key Finding
Algorithmic Efficiency	X/10	...
Database Design	X/10 or N/A — reason	...
Caching Strategy	X/10 or N/A — reason	...
Scalability Readiness	X/10 or N/A — reason	...
Resource Utilization	X/10 or N/A — reason	...
Data Pipeline Efficiency	X/10 or N/A — reason	...

Overall fitness score: X.X / 10 (mean of <list the scored dimensions>; <N/A dimensions> excluded) — <status band>

Dimension	Score	Key Finding
Algorithmic Efficiency	X/10	...
Database Design	X/10 or N/A — reason	...
Caching Strategy	X/10 or N/A — reason	...
Scalability Readiness	X/10 or N/A — reason	...
Resource Utilization	X/10 or N/A — reason	...
Data Pipeline Efficiency	X/10 or N/A — reason	...

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, whether the path is hot, and how the input grows.
Evidence: The specific code pattern found.
Impact: What gets slower or fails, and at what scale.
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, whether the path is hot, and how the input grows.
Evidence: The specific code pattern found.
Impact: What gets slower or fails, and at what scale.
Remediation: Concrete fix with code example or specific steps.

(repeat for each finding, ordered by severity)

Algorithmic Efficiency (X/10)

Evidence: file:line references
Issues found
Recommendations

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

Evidence: file:line references
Issues found
Recommendations

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

Top Action Items (by impact)

Up to 5; fewer is fine.

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

Up to 5; fewer is fine.

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

Checklist Reference

See references/checklist.md for the full performance checklist.

Reference

Based on Fundamentals of Software Performance, Fundamentals of Software Scalability, Fundamentals of Software Caching and guidance from https://jeffbailey.us/categories/fundamentals/

undefined

Based on Fundamentals of Software Performance, Fundamentals of Software Scalability, Fundamentals of Software Caching and guidance from https://jeffbailey.us/categories/fundamentals/

undefined