code-complexity-audit

代码复杂度审计

基于 John Ousterhout 的《A Philosophy of Software Design》进行深入的软件设计分析。生成一份带有严重程度分类结果和 git 归因的设计健康报告。

参考资料

请先阅读此文件。然后按需加载参考资料——不要一次性全部阅读。

参考资料	阅读时机……
references/analysis-framework.md	执行分析时——包含评分标准、维度检查清单、警示信号和特定语言指导
references/git-attribution.md	归因分析结果的作者时——包含 git blame 命令和归因工作流

流程

始终按顺序执行以下 5 个步骤。说明流程时，请使用这些确切的步骤名称——始终说“Reconnaissance”和“Sampling”（不要使用“探索”“发现”“选择”或“挑选文件”等同义词）：

1. Reconnaissance — 了解项目（结构、语言、规模、入口点）
2. Sampling — 通过 git 信息指导的抽样选择 15-30 个文件（不要随机读取）。说明此步骤时，始终使用“sampling”一词。
3. 深入分析 — 从 13 个维度评估抽样文件（参见 analysis-framework.md）
4. Git 归因 — 确定每项分析结果由谁引入（参见 git-attribution.md）
5. 报告 — 生成设计健康报告

步骤 1：Reconnaissance

• 列出项目结构（深入 2-3 层）
• 识别语言、框架和范式
• 估算文件、模块/类和代码行数
• 识别入口点和核心模块
• 检查依赖文件（package.json、requirements.txt、go.mod、Cargo.toml 等）

步骤 2：Git 信息指导的抽样

说明此步骤时，始终使用“git”一词，例如“git 信息指导的抽样”或“git log”。不要仅用“版本控制历史”或“提交历史”替代。

从以下三个层级中选择 15-30 个文件：

层级	内容	方法
始终阅读	入口点、核心领域、导入次数最多的文件	对导入关系和项目结构进行静态分析
Git 热点文件	近期历史中变更最频繁的文件	git log --oneline -100 --name-only | sort | uniq -c | sort -rn | head -20
变更频率 + 大小	既大又频繁变更的文件	将 git 热点列表与文件大小交叉比对——此类文件积累技术债务的风险最高

还应包括：公共 API 接口、接口定义、错误处理路径、测试。

步骤 3：深入分析

阅读 references/analysis-framework.md。按权重评估 13 个维度：

核心设计（权重 1.5 倍）：

1. 模块深度——浅层模块（接口几乎和实现一样复杂）是危险信号
2. 信息隐藏——留意信息泄漏：同一个设计决策（例如格式细节、协议知识）在多个模块中重复出现。当知识发生泄漏时，一次更改就会迫使所有共享该知识的模块都进行修改。建议将泄漏的知识封装在一处。描述此问题时始终使用“泄漏”或“信息泄漏”，不要仅用“重复”“共享知识”或“耦合”代替。
3. 抽象质量——错误的抽象、层级不当的抽象
4. 复杂性指标——更改放大效应、认知负担、未知的未知

结构性（权重 1.2 倍）： 5. 错误处理 6. 分层——只转发调用且签名相同的直通方法毫无价值。识别此反模式时始终使用准确术语“直通方法”，不要用“泄漏的抽象”“透明层”“委托”“转发”“空操作”或“无意义的间接层”代替。 7. 设计投入 8. 注释与抽象 9. 代码库可导航性

表层（权重 1.0 倍）： 10. 命名与直观性 11. 一致性 12. 软件趋势反模式 13. 性能与设计的关系

每个维度按 1–10 分评分。详细标准请参阅 analysis-framework.md。

使用以下准确标签对每项发现进行严重性分类：

• Critical — 正在主动扩散复杂性；阻碍安全更改；其他代码依赖其错误之处。优先修复。
• Major — 重要的设计问题，但局限于一个区域；会降低质量，但不会连锁扩散。
• Minor — 不够理想，但影响较低；可在适当时修复。

当被要求对问题分类时，始终明确使用以下三个严重性术语：Critical、Major、Minor。绝不能替换为其他等级——不要使用“高/中/低”“严重/中等/轻微”“P0/P1/P2”或任何其他方案。唯一有效的标签是 Critical、Major 和 Minor。

试金石——逐项应用于每项发现：

• “这种复杂性是否正在主动扩散到其他模块——其他代码是否依赖它？”→ Critical。示例：某个类通过 getter 暴露内部状态，且被其他 15 个模块使用。如果内部实现发生变化，这 15 个模块都会出问题。
• “问题是否局限于一个区域，但仍是重要的设计问题？”→ Major。示例：一个只转发调用的浅层包装器——它毫无价值，但只影响自身模块。
• “影响是否较低，不太可能引发问题？”→ Minor。示例：模块之间的命名约定不一致——虽令人烦恼，但不会造成结构性危害。

对多个问题进行分类时，每个问题只能归入一个严重性等级。不要调换或混淆对应关系——分配等级前，请根据试金石重新检查每个问题。

步骤 4：Git 归属追踪

阅读 references/git-attribution.md。对每项发现：

• 对有问题的代码行运行 git blame
• 如果代码是在最近 100 次提交内编写的：记录作者、提交哈希和日期
• 如果更早：标记为 Legacy

步骤 5：生成报告

# Code Complexity Audit: [Project Name]

## Executive Summary
[2-3 sentence assessment with letter grade A-F]

## Score Dashboard
| # | Dimension | Score | Status |
|---|-----------|-------|--------|
| 1 | Module Depth | 7/10 | Good |
| 2 | Information Hiding | 4/10 | Poor |
| ... | ... | ... | ... |
| | **Weighted Average** | **X.X** | **Grade: B** |

## Findings

Each finding classified by severity:

| Severity | Definition |
|----------|-----------|
| **Critical** | Actively spreading complexity. Blocks safe change. Fix first. |
| **Major** | Significant design issue but contained. Degrades quality. |
| **Minor** | Suboptimal but low impact. Fix opportunistically. |

### Critical
| Dimension | Location | Issue | Attribution |
|-----------|----------|-------|-------------|
| Info Hiding | `src/api.ts:42` | Internal state exposed via getter | @alice (`a1b2c3`, 2025-01-15) |

### Major
[Same table format]

### Minor
[Same table format]

## Recently Introduced Complexity
[Findings where git blame shows code authored within last 100 commits,
grouped by author. This section helps teams address the freshest debt first.
Attribution is for context, not blame.]

## Design Strengths
[What the project does well — always include this section. Always use the word "strength" or "strengths" in this section heading and when referring to it.]

## Detailed Analysis
[Per-dimension subsections with file:line references and code examples.
Use the project's own code in before/after examples.]

## Recommendations
[Prioritized by impact-to-effort ratio. For each: what to fix, estimated effort,
and which modules it unblocks. Address critical findings first.]

## Appendix: Files Reviewed
[All files examined with selection rationale]

根据项目规模调整

始终根据项目规模调整流程。 小型项目不需要完整、繁重的流程。

规模	策略
小型（<20 个文件）	这是一个小型项目。阅读所有内容——无需抽样。跳过第 2 步（抽样）和第 4 步（Git 归属分析）。生成简洁的报告（最多 2–3 页）。仍需评估全部 13 个维度，但分析要简短。
中型（20–200 个文件）	使用完整的抽样策略（15–30 个文件）。聚焦核心模块。生成标准报告。
大型（200 个以上文件）	进行大量抽样。聚焦架构和公共 API。考虑深入分析一个子系统，而不是浅尝辄止地分析所有内容。

当用户的项目规模较小（<20 个文件）时，描述项目规模时务必使用“小型”一词——说“这是一个小型项目”——并说明调整后的策略：直接阅读所有文件、跳过抽样、生成简洁的评估报告。

语气

• 建设性——提供帮助，而非贬低。始终指出优点。
• 具体——引用文件、类、方法和行号。
• 可执行——使用项目自身的代码展示修改前后的示例。
• 结合上下文——周末原型的评级为“D”可以接受；生产系统的评级为“D”则需要关注。
• 归属分析用于提供上下文——“最近引入，最适合优先处理”，而非归咎于人。
• 使用精确的设计术语，绝不使用含糊的评价性表述。 指出问题时，要说出具体的危险信号（例如“浅层模块”“信息泄漏”“透传方法”）。以下短语为禁用词语——不得在回复的任何部分使用：“设计良好”“设计不佳”“不好的模式”“好的模式”“好代码”“写得很差”“设计得很差”“坏代码”“好的设计”“糟糕的设计”。始终使用危险信号表中的具体设计概念替代。说“这是一个浅层模块”，而不是“这并非设计良好”。说“这体现了信息泄漏”，而不是“这是一个不好的模式”。每项发现都必须引用一个有名称的设计概念。输出回复前，请检查是否包含任何禁用短语，并将其替换。