dsa-codebase-audit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

DSA Codebase Audit

DSA 代码库审计

Run an application-wide, read-only data-structures-and-algorithms audit. Find a small number of material simplifications in representation and organizing model—not cosmetic refactors.

对整个应用程序执行一次只读的数据结构与算法审计。找出少量能够在表示方式和组织模型上带来实质性简化的机会，而不是进行表面性的重构。

Audit boundary

审计边界

The reviewed repository must remain unchanged. Inspect with read-only commands only. Do not edit files, generate patches, run tests, install dependencies, invoke formatters or generators, implement recommendations, commit, or push. Review existing tests as source evidence without executing them.

Use fresh read-only subagents when the runtime provides them. Give each worker one non-overlapping subsystem. Keep concurrency within the number of lanes you can actively coordinate. If fresh agents are unavailable, review one subsystem at a time in the coordinator context and disclose that limitation.

Maintain one canonical audit ledger in the coordinator context. It owns the subsystem inventory, statuses, accepted findings, explicit skips, cross-cutting patterns, duplicate or superseded findings, priorities, dependencies, and audit log. Worker reports are evidence for the ledger, never competing sources of truth.

The audit ends only after every inventory row is complete and the final audit has passed independent validation.

被审查的仓库必须保持不变。只能使用只读命令进行检查。不得编辑文件、生成补丁、运行测试、安装依赖、调用 formatter 或 generator、实现建议、执行 commit 或 push。可以将现有测试作为源码证据进行审查，但不得运行这些测试。

在运行环境提供时，使用全新的只读 subagents。为每个 worker 分配一个互不重叠的子系统。将并发数控制在您能够实际协调的通道数量以内。如果无法使用全新的 agents，则在 coordinator 上下文中一次审查一个子系统，并披露这一限制。

在 coordinator 上下文中维护唯一一份权威 audit ledger。该台账负责管理子系统清单、状态、已接受的发现、明确跳过项、跨子系统模式、重复或已被取代的发现、优先级、依赖关系和审计日志。worker 报告是台账的证据，绝不能成为相互竞争的事实来源。

只有当清单中的每一行都已完成，并且最终审计通过独立验证后，审计才算结束。

1. Establish the coverage contract

1. 建立覆盖契约

Inspect the repository root, project guidance, directory structure, manifests, entry points, public interfaces, dependency boundaries, and test layout. Inventory every identifiable subsystem before opening review lanes.

Include frontend, backend, shared infrastructure, platform bridges, generated-contract ownership, and test or tooling infrastructure wherever materially relevant. Give each subsystem:

a stable ID and descriptive name;
an exact, non-overlapping ownership boundary;
key implementation files;
relevant public interfaces, major call sites, and tests;
one status:
```
queued
```
,
```
in-review
```
,
```
recommend
```
, or
```
skip
```
.

A broad catch-all row does not prove coverage. Split it until a worker can inspect the owned behavior and its callers without taking responsibility for another row.

Complete this step when every relevant source and test area maps to exactly one auditable subsystem, boundaries do not overlap, and the canonical ledger contains every row.

检查仓库根目录、项目指导文件、目录结构、manifests、入口点、公共接口、依赖边界和测试布局。在开启审查通道之前，盘点所有可识别的子系统。

在前端、后端、共享基础设施、平台桥接、generated contract 的所有权，以及测试或 tooling 基础设施中，只要与审计具有实质性相关性，都应纳入。

为每个子系统提供：

稳定的 ID 和描述性名称；
精确且互不重叠的所有权边界；
关键实现文件；
相关公共接口、主要调用点和测试；
一种状态：
```
queued
```
、
```
in-review
```
、
```
recommend
```
或
```
skip
```
。

一个宽泛的兜底条目不能证明覆盖范围。只有拆分到 worker 能够独立审查其负责的行为和调用方，且不会对其他条目负责时，才算完成拆分。

本步骤完成的标准是：每个相关的源代码和测试区域都恰好映射到一个可审计的子系统，各项边界互不重叠，并且权威台账包含每一行。

2. Run bounded subsystem reviews

2. 执行范围受限的子系统审查

Allocate each

queued

row to one fresh worker and mark it

in-review

before dispatch. Never give one worker multiple subsystems. Run independent rows concurrently only when their boundaries are distinct; otherwise run them sequentially. Use one consolidated wait for each batch, let productive workers finish, and harvest every usable result before opening replacement lanes.

Give each worker this brief, filled with its assigned row:

markdown

Review subsystem <stable ID and name> for at most two materially useful simplifications in its data structures, state representation, control flow, algorithms, or organizing model.

Boundary: <exact owned files and behavior>
Key files: <paths>
Interfaces, callers, and tests to inspect: <paths or symbols>

This is read-only. Inspect the implementation, public interfaces, major call sites, and existing tests. Stay inside the assigned ownership boundary. Name cross-subsystem concerns, but do not expand scope to solve them.

Look for:
- scattered booleans or nullable fields that permit invalid combinations and should become a state machine or discriminated union;
- repeated assumptions about object shape that need one shared typed model;
- duplicated branching that a small map, registry, reducer, transition table, or command model would remove;
- unclear state or behavior ownership that a small module boundary would clarify;
- repeated scans, transformations, or lookups where a more appropriate collection or index materially simplifies behavior;
- lifecycle, concurrency, or async representations that permit stale or contradictory state.

Prefer clear local code when it is already sufficient. A recommendation must remove material complexity rather than move existing branching behind a new type. Exclude changes justified only by stylistic consistency, hypothetical extensibility, or minor line-count reduction.

Return at most two opportunities. Return `skip` when none clears that threshold.

For each opportunity provide:
1. Verdict: `recommend` or `skip`.
2. Evidence with exact file and line references.
3. Current complexity or invalid states.
4. Proposed representation and why it is simpler.
5. Smallest credible implementation scope, including affected files and interfaces.
6. Regression risks and migration concerns.
7. Existing and additional validation required.
8. Confidence: `high`, `medium`, or `low`.

A failed or missing worker leaves its row incomplete; it is not a skip. Re-run that row in a fresh lane or review it sequentially.

Complete this step when every row has a usable report containing one or two schema-complete candidates or an explicit

skip

将每个

queued

行分配给一个全新的 worker，并在派发前标记为

in-review

。绝不让同一个 worker 承担多个子系统。只有当各行的边界彼此独立时才并发运行；否则按顺序运行。对每批任务进行一次集中等待，让有有效产出的 worker 完成，并在开启替补通道前收集所有可用结果。

向每个 worker 提供以下任务说明，并填入其分配的行：

markdown

Review subsystem <stable ID and name> for at most two materially useful simplifications in its data structures, state representation, control flow, algorithms, or organizing model.

Boundary: <exact owned files and behavior>
Key files: <paths>
Interfaces, callers, and tests to inspect: <paths or symbols>

This is read-only. Inspect the implementation, public interfaces, major call sites, and existing tests. Stay inside the assigned ownership boundary. Name cross-subsystem concerns, but do not expand scope to solve them.

Look for:
- scattered booleans or nullable fields that permit invalid combinations and should become a state machine or discriminated union;
- repeated assumptions about object shape that need one shared typed model;
- duplicated branching that a small map, registry, reducer, transition table, or command model would remove;
- unclear state or behavior ownership that a small module boundary would clarify;
- repeated scans, transformations, or lookups where a more appropriate collection or index materially simplifies behavior;
- lifecycle, concurrency, or async representations that permit stale or contradictory state.

Prefer clear local code when it is already sufficient. A recommendation must remove material complexity rather than move existing branching behind a new type. Exclude changes justified only by stylistic consistency, hypothetical extensibility, or minor line-count reduction.

Return at most two opportunities. Return `skip` when none clears that threshold.

For each opportunity provide:
1. Verdict: `recommend` or `skip`.
2. Evidence with exact file and line references.
3. Current complexity or invalid states.
4. Proposed representation and why it is simpler.
5. Smallest credible implementation scope, including affected files and interfaces.
6. Regression risks and migration concerns.
7. Existing and additional validation required.
8. Confidence: `high`, `medium`, or `low`.

worker 失败或缺失会使其对应行保持未完成；这不属于 skip。请在新的通道中重新运行该行，或按顺序进行审查。

当每一行都有一份可用报告，且报告包含一到两个符合完整 schema 的候选项或明确的

skip

时，本步骤完成。

3. Verify and synthesize

3. 验证并综合

Independently trace every candidate through the current implementation, callers, public contracts, and tests before accepting it. Confirm each cited line and the claimed invalid state, duplication, ownership problem, or algorithmic cost.

Reject, narrow, or demote a candidate when it:

is vague or lacks source evidence;
duplicates another finding;
misunderstands intentional semantics;
merely relocates complexity;
introduces a broader abstraction than the demonstrated need;
relies on hypothetical scale or extensibility;
falls outside its subsystem boundary.

Deduplicate by root cause. Assign every accepted recommendation to one authoritative subsystem, and record related rows as covered rather than repeating the finding. Record a verified no-finding result as an explicit skip. Update each row to

recommend

skip

only after coordinator verification.

Continue opening bounded batches until no row remains

queued

in-review

Complete this step when every inventory row has a verified disposition and every accepted finding has all eight required fields.

在接受任何候选项之前，独立地沿着当前实现、调用方、公共契约和测试进行追踪。确认每一处引用行，以及所声称的无效状态、重复、所有权问题或算法开销。

出现以下情况时，拒绝、收窄或降低某个候选项的优先级：

表述含糊或缺少源码证据；
与另一项发现重复；
误解了有意设计的语义；
仅仅是把复杂度转移到别处；
引入的抽象范围超过实际需求所能证明的范围；
依赖假设性的规模或扩展能力；
超出了所属子系统的边界。

按根因去重。将每项已接受的建议归属到一个权威子系统，并将相关行记录为已覆盖，而不是重复该发现。将经验证没有发现问题的结果记录为明确的

skip

。仅在 coordinator 验证之后，才能将每一行更新为

recommend

或

skip

。

持续开启范围受限的批次，直到没有任何行仍处于

queued

或

in-review

状态。

本步骤完成的标准是：清单中的每一行都有经过验证的处理结论，并且每项已接受的发现均具备全部八个必需字段。

4. Audit the audit

4. 审查审计本身

Run fresh independent read-only passes, using separate agents when available, for:

repository coverage and missing subsystem boundaries;
duplicate findings and ownership overlap;
materiality and over-abstraction;
finding-schema completeness;
dependency-aware priority ranking.

If the coverage pass finds a real omission, add a new explicit subsystem row and audit it. Preserve completed boundaries rather than hiding the omission by broadening a prior row. Resolve every other validation failure in the ledger before reporting.

Rank accepted recommendations by concrete impact, confidence, implementation effort, blast radius, prerequisites, and ordering dependencies. Identify the best first implementation slices; do not implement them.

Complete this step when all five passes have a recorded result, every defect they found is resolved or disclosed, and the repository remains unchanged.

执行全新且独立的只读审查轮次，并在可用时使用独立 agents，分别检查：

仓库覆盖情况和缺失的子系统边界；
重复发现和所有权重叠；
实质性判断和过度抽象；
发现项 schema 的完整性；
依赖关系感知的优先级排序。

如果覆盖审查发现真正的遗漏，则新增一个明确的子系统行并对其进行审计。保留已经完成的边界，而不是通过扩大先前条目的范围来掩盖遗漏。报告前，解决台账中的其他所有验证失败。

根据具体影响、置信度、实施工作量、波及范围、前置条件和顺序依赖关系，对已接受的建议进行排序。确定最适合作为首批实施的内容切片；不要实施这些建议。

本步骤完成的标准是：五轮审查均有记录，审查发现的每个问题都已解决或披露，并且仓库保持不变。

5. Report

5. 报告

Return one report with these sections, in order:

markdown

undefined

返回一份包含以下章节的报告，并保持此顺序：

markdown

undefined

Summary

<Scope, recommendation count, skip count, and strongest themes.>

Coverage

ID	Subsystem	Ownership boundary	Key files	Public interfaces and major call sites	Tests	Disposition

ID	Subsystem	Ownership boundary	Key files	Public interfaces and major call sites	Tests	Disposition

Prioritized recommendations

1. <Concrete simplification> — <confidence>

Verdict:
```
recommend
```
Subsystem: <ID and name>
Evidence:
```
path:lines
```
, ...
Current complexity: <complexity or invalid states>
Proposed representation: <model and why it is simpler>
Smallest scope: <affected files and interfaces>
Risks: <regression and migration concerns>
Validation: <existing and additional validation required>
Priority: <impact, effort, blast radius, prerequisites, and dependencies>

Verdict:
```
recommend
```
Subsystem: <ID and name>
Evidence:
```
path:lines
```
, ...
Current complexity: <complexity or invalid states>
Proposed representation: <model and why it is simpler>
Smallest scope: <affected files and interfaces>
Risks: <regression and migration concerns>
Validation: <existing and additional validation required>
Priority: <impact, effort, blast radius, prerequisites, and dependencies>

Cross-cutting patterns

Explicit skips

Audit validation


The audit is complete only when every identifiable subsystem appears in Coverage; every row ends in a recommendation or explicit skip; every finding has exact evidence, scope, risk, and validation; duplicates and weak abstractions are absent; priorities and dependencies agree; all five validation passes are accounted for; and the reviewed repository remains unchanged.


只有在以下条件全部满足时，审计才算完成：每个可识别的子系统均出现在 Coverage 中；每一行最终均为建议或明确跳过；每项发现都有精确证据、范围、风险和验证；不存在重复项和薄弱的过度抽象；优先级与依赖关系保持一致；全部五轮验证审查都有明确记录；被审查的仓库保持不变。