review-algorithms

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Algorithm & Data Structure Fitness Review

算法与数据结构适配度审查

Analyze the codebase (or the files, modules, or questions the user names) for algorithm and data structure fitness. Identify correctness risks, inappropriate structure choices, concurrency hazards, and edge case gaps using evidence from the code. This review asks "is this correct? is this the right approach? will this break?" -- not "is this fast enough?"

Reference: Fundamentals of Algorithms — see also Fundamental Algorithmic Patterns, Fundamental Data Structures, and Fundamentals

分析代码库（或用户指定的文件、模块或问题）中的算法与数据结构适配度。依据代码中的证据，找出正确性风险、不合适的数据结构选择、并发隐患和边界情况缺口。本次审查关注的是“这是否正确？方法是否合适？会不会出错？”，而不是“是否足够快？”

参考：Fundamentals of Algorithms——另见 Fundamental Algorithmic Patterns、Fundamental Data Structures 和 Fundamentals。

Domain Knowledge

领域知识

```
references/rubric.md
```
is the scoring source: severity definitions, the proof required for HIGH and CRITICAL, 1-10 anchors per dimension, the N/A rule, and how to compute the overall score. Read it first; it is short.
```
references/checklist.md
```
is what to look for during steps 4-6.
```
references/wisdom.md
```
is optional background generated from the blog posts linked above (4,000+ lines). Grep it by heading for a specific question (for example
```
grep -n "^### " references/wisdom.md
```
); never read it whole.

```
references/rubric.md
```
是评分依据：包含严重程度定义、HIGH 和 CRITICAL 所需证明、各维度 1-10 分锚点、N/A 规则，以及总体分数的计算方式。请先阅读它；文件很短。
```
references/checklist.md
```
是执行步骤 4-6 时需要检查的内容。
```
references/wisdom.md
```
是根据上述博客文章生成的可选背景资料（4,000+ 行）。按标题使用 Grep 查找特定问题（例如
```
grep -n "^### " references/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. 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 位于插件

scripts/

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

SKILL.md

的目录。

<target>

是待审查的文件或目录。CLI 会向上遍历以发现模块级 override，并将它与根配置合并。将 resolver 输出中的

Config:

和

Effective weights:

行包含在最终报告的前 10 行内，作为溯源信息（AC-03.1、AC-08.2）。由

<!-- BEGIN_EFFECTIVE_CONFIG_JSON -->

<!-- END_EFFECTIVE_CONFIG_JSON -->

标记的 JSON 块中的

effective

对象包含权重、状态阈值、安全设置和评分信息，可用于任何程序化需求。

Workflow

工作流

Read the rubric and checklist --

references/rubric.md

, then skim

references/checklist.md

Scope the review -- The target is what the user named (files, directory, or question), else the repository. If the user asked specific questions ("is it deterministic?", "any races?"), note them; the report answers them first.
Decide which dimensions apply -- For each of the six dimensions, decide whether anything in scope can be evaluated. Mark the rest
```
N/A -- <reason>
```
with evidence for the absence (rubric.md, "N/A"). Concurrency Safety is N/A for single-threaded code; do not fill it with hypothetical races between overlapping runs.
Map the logic that can be wrong -- Algorithms are not only sorts, graphs, and DP. Include:
- sorting, searching, traversal, recursion, nested loops, custom data structures;
- merge, override, and precedence logic (config chains, layered defaults, dict merges);
- validation and parsing: what a validator accepts versus what downstream code assumes;
- path, slice, and index arithmetic (walk-up-to-root loops,
```
[:n]
```
  vs
```
[:n+1]
```
  );
- dedupe, ordering, and anything whose output is stored, diffed, or compared between runs;
- loops bounded by a stop condition: what happens when the input starts outside the expected tree (a path above or beside the project root);
- parallel lists re-paired with
```
zip
```
  , and error messages: does the message name the file or value that is actually wrong? Use Grep/Glob to find these, then read the code around each. Where one rule is enforced on one path (single file, proposal, write) but not on another (merged chain, read), check whether the other path can reach the same bad state.
Evaluate each applicable dimension against
```
references/checklist.md
```
: algorithm choice, data structure fit, complexity, concurrency, edge cases, correctness patterns.
Probe edge inputs -- Running the code finds bugs that reading misses. For each hotspot, call the function or run the CLI on edge inputs: empty, one element, boundary index, the root or top level, a target outside the project,
```
null
```
/
```
[]
```
/ a scalar where an object is expected, wrong-typed values (
```
"1"
```
for
```
1
```
), unknown keys, values the validator accepts that the consumer might not, and a second
```
PYTHONHASHSEED
```
(or equivalent) where output order matters. Work in a scratch directory or temp files; never modify the user's files. Every edge input a user can type or put in a file is supported input, so a defect it triggers is a finding at whatever severity its impact earns, including LOW.
Confirm HIGH and CRITICAL findings -- Every HIGH or CRITICAL finding needs a minimal reproduction: the command or snippet you ran and the output you observed. A finding you cannot reproduce but can see plainly in the code stays in the report at MEDIUM or LOW with "not reproduced: <why>" in its Reproduction field; drop it only when the code does not support it (rubric.md, "Proof for HIGH and CRITICAL"). Severity follows impact, so a reproduced finding keeps the severity its impact earns: a validator that passes input the next command crashes on is still that, even when the fix is one line.
Score each applicable dimension with file:line evidence, using the anchors in
```
references/rubric.md
```
. Compute the overall per rubric.md.
Self-check, then write the report (see Output Format). Before writing, check that:
- every cited file:line exists and says what the finding claims;
- every finding has confidence >= 7, and every HIGH/CRITICAL has a Reproduction;
- no finding depends on an unsupported setup (rubric.md, "Not a finding"), and no reproduced or code-evident defect was left out just because it is LOW;
- the overall equals the stated computation over the named dimensions;
- no secret values are reproduced (refer to secrets by file:line only).

阅读评分标准与检查清单——先阅读
```
references/rubric.md
```
，然后浏览
```
references/checklist.md
```
。
确定审查范围——审查目标是用户指定的文件、目录或问题；如果用户未指定，则审查整个仓库。如果用户提出了具体问题（例如“它是确定性的吗？”“存在竞态吗？”），请记录这些问题；报告应优先回答这些问题。
确定适用的维度——针对六个维度中的每一个，判断审查范围内是否有可评估的内容。对于其余维度，标记为
```
N/A -- <reason>
```
，并提供未涉及该维度的证据（rubric.md 中的“N/A”）。单线程代码的并发安全为 N/A；不要用重叠运行之间可能存在的假设性竞态来填充该维度。
梳理可能出错的逻辑——算法不仅包括排序、图和 DP，还包括：
- 排序、搜索、遍历、递归、嵌套循环和自定义数据结构；
- 合并、override 和优先级逻辑（config 链、分层默认值、
```
dict
```
  合并）；
- 验证与解析：validator 接受的内容与下游代码所假设的内容是否一致；
- 路径、切片和索引运算（向上遍历至根节点的循环、
```
[:n]
```
  与
```
[:n+1]
```
  ）；
- 去重、排序，以及输出会被存储、比较差异或在多次运行之间进行比较的任何逻辑；
- 由停止条件限定的循环：输入从预期树之外开始时会发生什么，例如路径位于项目根节点之上或旁边；
- 使用
```
zip
```
  重新配对的并行列表，以及错误消息：消息是否指明了真正有误的文件或值？使用 Grep/Glob 查找这些内容，然后阅读相关代码附近的上下文。如果某条规则在一条路径上得到执行（例如单一文件、proposal 或写入），但在另一条路径上未得到执行（例如合并链或读取），请检查后一条路径是否可能进入同样的错误状态。
根据
references/checklist.md
评估每个适用维度——算法选择、数据结构适配度、复杂度、并发、边界情况和正确性模式。
探测边界输入——运行代码可以发现仅靠阅读容易遗漏的缺陷。对于每个风险点，使用边界输入调用函数或运行 CLI：空输入、单元素、边界索引、根节点或顶层、项目外部的目标、需要对象却传入
```
null
```
/
```
[]
```
/ 标量的情况、类型错误的值（例如用
```
"1"
```
代替
```
1
```
）、未知键、validator 接受但 consumer 可能不接受的值，以及在输出顺序重要时使用第二个
```
PYTHONHASHSEED
```
（或等效机制）。请在临时目录或临时文件中操作；绝不修改用户的文件。用户可以键入或放入文件的每个边界输入都属于受支持输入，因此它触发的缺陷都应作为发现，并依据实际影响获得相应严重程度，包括 LOW。
确认 HIGH 和 CRITICAL 发现——每个 HIGH 或 CRITICAL 发现都需要最小复现：列出你运行的命令或代码片段，以及观察到的输出。对于无法复现但从代码中可明确看出的发现，应将其保留在报告中，严重程度为 MEDIUM 或 LOW，并在 Reproduction 字段中写明“not reproduced: <why>”；仅当代码不支持该发现时才能将其删除（rubric.md 中的“Proof for HIGH and CRITICAL”）。严重程度取决于实际影响，因此已复现的发现应保留其影响所对应的严重程度：例如 validator 接受了会导致下一条命令崩溃的输入时，即使修复只需一行，严重程度也不应降低。
评分——根据
```
references/rubric.md
```
中的锚点，使用 file:line 证据对每个适用维度进行评分。按照 rubric.md 的方法计算总体分数。
自检，然后编写报告（参见输出格式）。编写前请检查：
- 每个引用的 file:line 都存在，且内容确实支持该发现；
- 每个发现的置信度均 >= 7，且每个 HIGH/CRITICAL 都有 Reproduction；
- 没有发现依赖不受支持的配置（rubric.md 中的“Not a finding”），也没有因为严重程度为 LOW 而遗漏任何已复现或从代码中明确可见的缺陷；
- 总体分数等于根据已命名维度计算出的结果；
- 不复现任何机密值（仅通过 file:line 引用机密信息）。

Confidence and Severity

置信度与严重程度

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

Is this a real pattern in the code, not a guess about runtime behavior?
Can you point to a specific file and line?
Is it reachable in normal, supported use of this code?

If any answer is no, do not report it. Missing a theoretical issue costs less than a report full of noise, because readers stop trusting the real findings. The filter is about whether a defect is real, not how important it is: a reproduced bug, or one the code plainly shows, is not noise even at LOW, and leaving it out hides real defects from the reader. Noise is speculation: guesses about runtime behavior, setups the code does not support, and style. Severity levels (CRITICAL, HIGH, MEDIUM, LOW), with algorithm-specific examples, are defined in

references/rubric.md

仅报告置信度 >= 7/10 的发现。对于每个发现，询问：

这是代码中真实存在的模式，而不是对运行时行为的猜测吗？
能否指向一个具体文件和行号？
在代码正常且受支持的使用方式中是否能够触及？

如果任一答案为否，则不要报告。遗漏一个理论问题的影响，小于提交一份充满噪声的报告，因为读者会因此不再信任真正的发现。筛选标准是缺陷是否真实存在，而不是其重要程度：已复现的缺陷，或代码中明确可见的缺陷，即使为 LOW 也不是噪声；将其遗漏会向读者隐藏真实缺陷。噪声指的是推测：关于运行时行为、代码不支持的配置以及代码风格的猜测。严重程度等级（CRITICAL、HIGH、MEDIUM、LOW）及算法相关的示例定义在

references/rubric.md

中。

Scoring Dimensions (1-10 each)

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

Score anchors for each dimension are in

references/rubric.md

; what to check is in

references/checklist.md

Algorithm Choice -- Whether algorithms match problem structure: sorting strategy, search approach, graph traversal, merge/precedence logic, divide-and-conquer, dynamic programming, greedy, batching
Data Structure Selection -- Whether collections match access patterns, ordered vs unordered, bounded vs unbounded, mutable vs immutable, concurrent structures where needed
Complexity Awareness -- Hidden quadratic behavior, unnecessary recomputation, unbounded growth, string concatenation in loops, amortized cost awareness
Concurrency Safety -- Shared mutable state protection, race conditions, lock ordering, atomic operations, thread-safe collections, ownership model (N/A when nothing in scope is concurrent)
Edge Case Handling -- Empty collections, null inputs, boundary values, off-by-one errors, validator/consumer agreement, integer overflow, floating-point comparison, division by zero, Unicode
Correctness Patterns -- Invariant maintenance, idempotency, determinism, error propagation, loop termination, precondition/postcondition checks, equality/hash consistency

各维度的评分锚点位于

references/rubric.md

；需要检查的内容位于

references/checklist.md

。

算法选择——算法是否与问题结构匹配：排序策略、搜索方式、图遍历、合并/优先级逻辑、分治、动态规划、贪心、批处理
数据结构选择——集合是否与访问模式匹配：有序与无序、有界与无界、可变与不可变，以及需要并发时是否采用并发安全结构
复杂度意识——隐藏的二次复杂度、不必要的重复计算、无界增长、循环中的字符串拼接、摊销成本意识
并发安全——共享可变状态保护、竞态条件、锁顺序、原子操作、线程安全集合、所有权模型（审查范围内不存在并发时为 N/A）
边界情况处理——空集合、
```
null
```
输入、边界值、差一错误、validator/consumer 一致性、整数溢出、浮点比较、除零、Unicode
正确性模式——不变量维护、幂等性、确定性、错误传播、循环终止、前置/后置条件检查、相等性/hash 一致性

Output Format

输出格式

Write the report to

docs/algorithms-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 set of files, write

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

instead (for example

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

) so a scoped run does not replace the whole-repo report.

markdown

undefined

除非用户提供路径，否则将报告写入目标所在仓库根目录的

docs/algorithms-review.md

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

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

（例如

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

），以免范围受限的运行覆盖整个仓库的报告。

markdown

undefined

Algorithm & Data Structure 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 specific questions. Answer each in one to three sentences, citing the finding numbers below.)

Summary

Overall fitness score: X.X / 10 (mean of <named scored dimensions>; status <band>)

Dimension	Score	Key Finding
Algorithm Choice	X/10	...
Data Structure Selection	X/10	...
Complexity Awareness	X/10	...
Concurrency Safety	X/10 or N/A -- reason	...
Edge Case Handling	X/10	...
Correctness Patterns	X/10	...

Overall fitness score: X.X / 10 (mean of <named scored dimensions>; status <band>)

Dimension	Score	Key Finding
Algorithm Choice	X/10	...
Data Structure Selection	X/10	...
Complexity Awareness	X/10	...
Concurrency Safety	X/10 or N/A -- reason	...
Edge Case Handling	X/10	...
Correctness Patterns	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 found.
Reproduction: (required for HIGH/CRITICAL) command or snippet run, and the observed output.
Impact: What goes wrong, and on which input.
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.
Reproduction: (required for HIGH/CRITICAL) command or snippet run, and the observed output.
Impact: What goes wrong, and on which input.
Remediation: Concrete fix with code example or specific steps.

(repeat for each finding, ordered by severity)

Algorithm Choice (X/10)

Evidence: file:line references, including what was checked and found sound
Issues found
Recommendations

(repeat for each dimension; for N/A dimensions give the reason and evidence of absence)

Evidence: file:line references, including what was checked and found sound
Issues found
Recommendations

(repeat for each dimension; for N/A dimensions give the reason and evidence of absence)

Top Action Items (up to 5, by impact)

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

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

Reference

Based on Fundamentals of Algorithms, Fundamental Algorithmic Patterns, Fundamental Data Structures, and guidance from https://jeffbailey.us/categories/fundamentals/

undefined

Based on Fundamentals of Algorithms, Fundamental Algorithmic Patterns, Fundamental Data Structures, and guidance from https://jeffbailey.us/categories/fundamentals/

undefined