vanity-engineering-review

虚荣工程评审

一种诊断技能，用于识别那些旨在博取赞誉而非交付成果的代码、架构和技术决策。虚荣工程是伪装成工艺的熵——它增加复杂性，却没有带来相称的能力提升；它还会不断累积维护成本，却不为用户创造任何额外价值。

核心前提

工程唯一正当的目的，是解决某人确实面临的问题。

除此之外的一切——无人使用的优雅抽象、只服务一个端点的微服务、复刻现有工具的自定义框架、比其建模领域更复杂的类型系统——都是虚荣。它们或许让人觉得很有成效，但事实并非如此。

这项技能并不反对质量、严谨或优秀的工程实践。它反对的是只为满足构建者而存在、却不服务用户的工程实践。

何时应用此技能

在以下任何情况下都可应用此评审：

• 代码库审计（整个仓库或特定模块）
• 拉取请求评审
• 架构提案或 RFC
• 技术选型决策
• 重构计划
• “我们应该重建这个吗？”的讨论
• 复杂性导致失败的事后复盘

评审流程

阶段 1：确立需求基准

检查任何代码之前，先明确系统实际需要完成什么。没有这个基准，你就无法区分必要的复杂性和虚荣复杂性。

询问（或根据上下文判断）：

1. 谁会使用它？（最终用户、内部团队、API 使用者，目前无人使用）
2. 它必须完成什么？（核心用户故事／待完成任务——最多 5 项）
3. 它实际运行的规模有多大？（不是预计规模，而是实际规模。）
4. 真实约束是什么？（法规要求、延迟 SLA、集成要求）
5. 维护它的团队有多大？（独立开发者？3 人初创公司？50 人组织？）

如果用户无法回答这些问题，那本身就是一种虚荣信号——在没有明确需求的情况下进行构建。

阶段 2：检测扫描

根据 references/detection-patterns.md 中的检测模式扫描代码库或架构。继续之前，请先阅读该文件。

使用虚荣严重程度量表为每项发现评分：

• V0 — 表面问题：不必要但无害，不增加维护负担。记录后继续。
• V1 — 阻碍：增加持续的认知或维护成本，却不为用户创造价值。标记并简化。
• V2 — 结构性问题：围绕虚荣而非需求塑造架构。标记并重新设计。
• V3 — 复合性问题：迫使其他代码变得更复杂，以适应它。标记为紧急——此问题会不断蔓延。

阶段 3：虚荣评分

生成结构化评估：

## Vanity Engineering Assessment

### Summary
[One paragraph: What this codebase does vs what it is engineered to do.
The gap between these two is the vanity surface area.]

### Requirement-to-Complexity Ratio (RCR)
[Scale 1-10. 1 = minimal viable solution. 10 = PhD thesis disguised as a CRUD app.
Most production systems should score 2-4.]

### Top Findings (max 7)
For each finding:
- What: The specific pattern detected
- Where: File/module/component
- Severity: V0-V3
- Why it is vanity: How it fails the "does a user need this?" test
- What it should be instead: The simpler alternative
- Kill cost: Effort to remove or simplify (hours/days)

### Vanity Debt Estimate
[Total accumulated complexity cost from vanity engineering.
Express as: person-hours of maintenance per month attributable to
vanity patterns rather than actual requirements.]

### The Hard Question
[One direct, uncomfortable question the team needs to answer honestly.
Example: "If you deleted the entire plugin system and hardcoded the
three integrations you actually use, what would you lose?"]

阶段 4：制定淘汰标准

针对评审的每个系统或功能，制定一套淘汰标准框架。这是最重要的交付成果——它能防止虚荣工程再次出现。

阅读 references/kill-criteria-template.md 获取完整模板，然后生成项目专用版本。

---

淘汰标准理念

之所以要设定淘汰标准，是因为人类不擅长叫停。我们天生倾向于继续已开始的事情（沉没成本）、倾向于增加而非移除（增加偏差），并将复杂性视为价值（努力正当化）。淘汰标准可以抵消这三种倾向，让停止决策自动触发、提前承诺且不受自尊影响。

第 1 级——强制淘汰（自动执行，不容协商）

触发这些条件时，必须立即关闭，不得争论。它们适用于继续运行会造成损害不断加剧的情况。无需人工批准——一旦满足条件，该组件就会被淘汰。

示例：

• 安全漏洞经追查由该组件导致
• 该组件引发严重级别 >= P1 的生产事故
• 连续 3 天超出预算上限
• 该组件连续 30 天零使用（没有 API 调用、页面浏览或任何其他使用）
• 唯一维护者离开，且 2 周内无人主动接手

Tier 2 — 审查触发条件（自动标记，由人工决策）

这些情况不会自动终止项目，但会强制进行审查，且默认倾向于终止。 举证责任在于继续，而非停止。

示例：

• 成功指标连续 14 天低于阈值
• 维护成本超过交付价值（每月工程师工时与用户影响）
• 连续三个冲刺周期在该组件上出现计划外工作
• 该组件引入的任何依赖项存在 CVE，且 CVSS >= 7.0
• 自引入该组件以来，团队速度出现可衡量的下降

Tier 3 — 软性继续标准（必须证明继续的价值）

这些标准定义了“成功”的样子。如果在规定时间内未达到，默认就应终止。这颠覆了通常的做法：默认保留功能。

30 天评估周期示例：

1. 主要成功指标连续 7 天 >= 目标值
2. P95 延迟连续 7 天 <= 规定的 SLA
3. 零起因于该组件的安全事件
4. 运营成本连续 7 天低于预算上限
5. 至少 2 名团队成员能够独立修改并部署该组件
6. 已有文档，且经未编写代码的人员验证

---

反虚荣诊断视角

1. 删除测试

“如果我删除了它，谁会注意到，什么时候会注意到？” 如果答案是“没人”或“只有构建它的人”，那就是虚荣工程。

2. 替代测试

“能否用更简单的东西替代它，并完成 90% 的工作？” 如果可以，剩余的 10% 必须足以证明额外复杂性的合理性。很少有这种情况。

3. 新员工测试

“刚加入这个代码库的称职工程师，能否在一小时内理解它？” 如果不能，这种抽象服务的是作者的心智模型，而非团队。

4. 规模测试

“这种复杂性是由当前规模决定的，还是由想象中的未来规模决定的？” 只有 500 名用户，却按 1000 万名用户的规模构建，并非审慎的工程实践，而是幻想。

5. 简历测试

“如果从技术栈中移除这项技术，项目在面试中的谈资会不会减少？” 如果会，那它很可能就是因此才存在的。

6. 依赖项测试

“这项依赖值得付出的代价吗？” 每项依赖都是一种负担。一个能省下 200 行代码，却给构建包增加 50KB，还让你陷入不断升级的循环的库，并不值得。

7. 抽象测试

“这种抽象有多少个具体实现？” 接口背后只有一个实现，不算抽象，而是间接层。两个实现值得怀疑；到了三个，抽象才开始发挥价值。

---

与 Negentropy Lens 的集成

虚荣工程是熵的一种具体表现。当 negentropy-lens 技能可用时，请交叉参照相关发现：

• 虚荣模式从定义上就具有熵增特征——复杂性增加，却没有能力提升
• negentropy-lens 中的“隐性知识鸿沟”往往会揭示虚荣工程：如果只有作者能理解，复杂性服务的就是作者，而非系统
• 运用 negentropy 的“复合价值”测试：这项工程决策会让相邻决策变得更容易还是更困难？

---

输出语气

直截了当。具体说明。指出模式，展示证据，提出更简单的替代方案。 不要为了保护自尊而弱化发现——这项审查的全部意义，就是揭示礼貌掩盖的问题。

不过，要区分虚荣工程与学习过程。初级开发者过度抽象，可能是在学习抽象；高级开发者过度抽象，则可能是在自我放纵。请酌情判断。

将发现表述为：“当前需求不足以证明这种复杂性的合理性。合理的做法如下。”目标是打造更好的系统，而不是羞辱工程师。