Back to Details

vanity-engineering-review

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Vanity Engineering Review

虚荣工程审查

A diagnostic skill that identifies code, architecture, and technical decisions built to impress rather than to ship. Vanity engineering is entropy disguised as craftsmanship — it increases complexity without proportional capability gain, and it compounds maintenance cost while delivering zero additional user value.
一项用于识别为博人眼球而非交付产品而构建的代码、架构与技术决策的诊断技能。虚荣工程是伪装成工艺的熵增——它在未带来相应能力提升的情况下增加复杂度，同时在未交付任何额外用户价值的情况下加剧维护成本。

Core Premise

核心前提

The only legitimate purpose of engineering is to solve a problem someone actually has.
Everything else — elegant abstractions nobody traverses, microservices that serve one endpoint, custom frameworks that replicate existing tools, type systems more complex than the domain they model — is vanity. It may feel productive. It is not.
This skill does not oppose quality, rigour, or good engineering. It opposes engineering that exists to satisfy the builder rather than the user.
工程的唯一合理目的是解决真实存在的问题。
除此之外的所有内容——无人使用的优雅抽象、仅服务一个端点的微服务、复制现有工具的自定义框架、比所建模领域更复杂的类型系统——都是虚荣工程。这可能会让你感觉富有成效，但实际上并非如此。
本技能并不反对高质量、严谨的优秀工程实践，它反对的是为满足构建者而非用户需求而存在的工程行为。

When to Apply This Skill

适用场景

Apply this review to any of:
  • Codebase audits (full repo or specific modules)
  • Pull request reviews
  • Architecture proposals or RFCs
  • Technology selection decisions
  • Refactoring plans
  • "Should we rebuild this?" discussions
  • Post-mortems where complexity contributed to failure
可将本审查应用于以下任意场景：
  • 代码库审计（完整仓库或特定模块）
  • 拉取请求（PR）审查
  • 架构提案或RFC
  • 技术选型决策
  • 重构计划
  • “我们是否应该重写这个？”的讨论
  • 复杂度导致故障的事后复盘

The Review Process

审查流程

Phase 1: Establish the Requirement Anchor

阶段1：确立需求锚点

Before examining any code, establish what the system actually needs to do. Without this anchor, you cannot distinguish necessary complexity from vanity complexity.
Ask (or determine from context):
  1. Who uses this? (End users, internal team, API consumers, nobody yet)
  2. What must it do? (Core user stories / jobs-to-be-done — max 5)
  3. What scale does it actually operate at? (Not projected. Actual.)
  4. What are the real constraints? (Regulatory, latency SLAs, integration requirements)
  5. What is the team size maintaining this? (Solo dev? 3-person startup? 50-person org?)
If the user cannot answer these, that is itself a vanity signal — building without defined requirements.
在检查任何代码之前，先明确系统实际需要实现的功能。没有这个锚点，你就无法区分必要复杂度与虚荣性复杂度。
询问（或从上下文推断）：
  1. 谁在使用它？（终端用户、内部团队、API消费者，或目前无人使用）
  2. 它必须实现什么功能？（核心用户故事/待完成工作——最多5项）
  3. 它实际的运营规模是多少？（不是预期规模，是实际规模）
  4. 真实约束条件是什么？（合规要求、延迟SLA、集成需求）
  5. 维护该系统的团队规模有多大？（独立开发者？3人创业团队？50人规模的组织？）
如果用户无法回答这些问题，这本身就是虚荣工程的信号——在未明确需求的情况下就开始构建。

Phase 2: Detection Scan

阶段2：检测扫描

Scan the codebase or architecture against the detection patterns in 
references/detection-patterns.md
. Read that file before proceeding.
Score each finding using the Vanity Severity scale:
  • V0 — Cosmetic: Unnecessary but harmless. Adds no maintenance burden. Note and move on.
  • V1 — Drag: Adds ongoing cognitive or maintenance cost without user value. Flag for simplification.
  • V2 — Structural: Shapes architecture around vanity rather than requirements. Flag for redesign.
  • V3 — Compounding: Actively forces other code to be more complex to accommodate it. Flag as urgent — this metastasizes.
对照
references/detection-patterns.md
中的检测模式扫描代码库或架构。在继续操作前请先阅读该文件。
使用虚荣严重程度量表为每个发现评分：
  • V0 — 表面级：不必要但无害。不会增加维护负担。记录后即可跳过。
  • V1 — 拖累级：在未带来用户价值的情况下增加持续的认知或维护成本。标记为需要简化。
  • V2 — 结构级：围绕虚荣而非需求构建架构。标记为需要重新设计。
  • V3 — 复合型：主动迫使其他代码变得更复杂以适配它。标记为紧急——这种情况会不断恶化。

Phase 3: The Vanity Score

阶段3：虚荣评分

Produce a structured assessment:
undefined
生成结构化评估报告：
undefined

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.]
[一段文字：该代码库的实际功能 vs 其工程设计目标。两者之间的差距即为虚荣性复杂度的范围。]

Requirement-to-Complexity Ratio (RCR)

需求-复杂度比（RCR）

[Scale 1-10. 1 = minimal viable solution. 10 = PhD thesis disguised as a CRUD app. Most production systems should score 2-4.]
[1-10分。1=最小可行方案。10=伪装成CRUD应用的博士论文。大多数生产系统的得分应在2-4之间。]

Top Findings (max 7)

主要发现（最多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)
每项发现需包含：
  • 内容：检测到的具体模式
  • 位置：文件/模块/组件
  • 严重程度：V0-V3
  • 虚荣原因：如何未通过“用户是否需要这个？”的测试
  • 替代方案：更简单的实现方式
  • 移除成本：移除或简化所需的工作量（小时/天）

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?"]
undefined
[一个团队需要诚实回答的直接、尖锐的问题。示例：“如果你删除整个插件系统并硬编码你实际使用的三个集成，你会损失什么？”]
undefined

Phase 4: Kill Criteria Generation

阶段4：生成淘汰标准

For every system or feature reviewed, generate a kill criteria framework. This is the most important deliverable — it prevents vanity engineering from recurring.
Read 
references/kill-criteria-template.md
for the full template, then generate a project-specific version.
针对每个被审查的系统或功能，生成一套淘汰标准框架。这是最重要的交付成果——它能防止虚荣工程再次发生。
阅读
references/kill-criteria-template.md
获取完整模板，然后生成针对特定项目的版本。

Kill Criteria Philosophy

淘汰标准理念

Kill criteria exist because humans are bad at stopping things. We are wired to continue what we started (sunk cost), to add rather than remove (addition bias), and to interpret complexity as value (effort justification). Kill criteria counteract all three by making the stop decision automatic, pre-committed, and ego-independent.
淘汰标准的存在是因为人类不擅长终止事物。我们倾向于继续已开始的工作（沉没成本）、添加而非移除（加法偏见），并将复杂度等同于价值（努力合理化）。淘汰标准通过使终止决策自动化、预先承诺且独立于自我，来抵消这三种倾向。

Tier 1 — Hard Kill (Automatic, Non-Negotiable)

一级——强制淘汰（自动执行，无可协商）

These trigger immediate shutdown with no debate. They exist for situations where continuing causes escalating damage. No human approval needed — if the condition is met, the thing dies.
Examples:
  • Security breach traced to the component
  • Production incident caused by the component with severity >= P1
  • Cost exceeds budget cap for 3 consecutive days
  • The component has zero usage for 30 days (no API calls, no page views, nothing)
  • The sole maintainer leaves and no one volunteers to own it within 2 weeks
满足这些条件会立即触发关停，无需讨论。适用于继续运营会造成不断升级损害的场景。无需人工批准——只要满足条件，该功能就会被终止。
示例：
  • 组件引发安全漏洞
  • 组件导致的生产事故严重等级 >= P1
  • 连续3天成本超出预算上限
  • 组件连续30天零使用（无API调用、无页面浏览等）
  • 唯一维护者离职，且2周内无人自愿接手

Tier 2 — Review Trigger (Automatic Flag, Human Decision)

二级——审查触发（自动标记，人工决策）

These do not kill automatically but force a mandatory review with a default-to-kill bias. The burden of proof is on continuing, not on stopping.
Examples:
  • Success metric below threshold for 14 consecutive days
  • Maintenance cost exceeds value delivered (eng-hours/month vs user impact)
  • Three consecutive sprints with unplanned work on the component
  • Any dependency it introduced has a CVE with CVSS >= 7.0
  • Team velocity measurably decreased since introduction
这些条件不会自动触发淘汰，但会强制启动以淘汰为默认倾向的审查。举证责任在继续运营一方，而非终止一方。
示例：
  • 连续14天成功指标低于阈值
  • 维护成本超过交付的价值（每月人工小时数 vs 用户影响）
  • 连续三个冲刺周期内该组件出现未计划工作
  • 其引入的任何依赖存在CVSS >=7.0的CVE漏洞
  • 引入该组件后团队交付速度明显下降

Tier 3 — Soft-Go Criteria (Must Earn Continuation)

三级——留存标准（需主动争取留存）

These define what "success" looks like. If these are not met within the defined timeframe, the default is kill. This inverts the normal dynamic where features survive by default.
30-day evaluation window example:
  1. Primary success metric >= target for 7 consecutive days
  2. P95 latency <= defined SLA for 7 consecutive days
  3. Zero security incidents attributable to the component
  4. Operational cost under budget cap for 7 consecutive days
  5. At least 2 team members can independently modify and deploy it
  6. Documentation exists and was validated by someone who did not write the code
这些标准定义了“成功”的样子。如果在规定时间内未满足这些标准，默认将被淘汰。这反转了功能默认留存的常规模式。
30天评估窗口示例：
  1. 主要成功指标连续7天达到或超过目标
  2. P95延迟连续7天符合定义的SLA
  3. 无任何可归因于该组件的安全事件
  4. 运营成本连续7天低于预算上限
  5. 至少2名团队成员能够独立修改和部署该组件
  6. 存在文档，且由非编写者验证通过

Anti-Vanity Diagnostic Lenses

反虚荣诊断视角

1. The Deletion Test

1. 删除测试

"If I deleted this, who would notice and when?" If the answer is "nobody" or "only the person who built it," it is vanity.
“如果我删除这个，谁会注意到，什么时候会注意到？” 如果答案是“没人”或“只有构建它的人”，那这就是虚荣工程。

2. The Replacement Test

2. 替换测试

"Could this be replaced by a simpler thing that does 90% of the job?" If yes, the remaining 10% must justify the additional complexity. It rarely does.
“能否用一个更简单的方案替代它，完成90%的工作？” 如果可以，那剩下的10%必须证明额外复杂度的合理性，而这通常无法成立。

3. The New Hire Test

3. 新员工测试

"Could a competent engineer new to this codebase understand this in under an hour?" If not, the abstraction serves the author's mental model, not the team's.
“一名熟悉技术栈但不了解该代码库的工程师，能否在一小时内理解它？” 如果不能，那这个抽象服务的是作者的思维模型，而非团队。

4. The Scale Test

4. 规模测试

"Is this complexity justified by current scale, or by imagined future scale?" Building for 10M users when you have 500 is not prudent engineering. It is fantasy.
“这种复杂度是由当前规模还是想象中的未来规模所证明的？” 当你只有500个用户时，为1000万用户构建系统并非谨慎的工程实践，而是空想。

5. The Resume Test

5. 简历测试

"Would removing this technology from the stack make the project less interesting to talk about in an interview?" If yes, that is probably why it is there.
“如果从技术栈中移除这项技术，在面试中谈论这个项目会不会变得没那么有趣？” 如果答案是肯定的，那这可能就是它存在的原因。

6. The Dependency Test

6. 依赖测试

"Does this dependency earn its keep?" Every dependency is a liability. A library that saves 200 lines but adds 50KB to the bundle and an upgrade treadmill is not earning its keep.
“这个依赖是否物有所值？” 每个依赖都是一项负债。一个能节省200行代码但会给包增加50KB体积并带来升级负担的库，并不值得引入。

7. The Abstraction Test

7. 抽象测试

"How many concrete implementations does this abstraction have?" One implementation behind an interface is not abstraction. It is indirection. Two is suspicious. Three is where abstraction starts to pay off.
“这个抽象有多少个具体实现？” 接口背后只有一个实现不是抽象，是间接性。两个实现值得怀疑。三个实现才是抽象开始体现价值的起点。

Integration with Negentropy Lens

与负熵视角的集成

Vanity engineering is a specific manifestation of entropy. When the negentropy-lens skill is available, cross-reference findings:
  • Vanity patterns are entropic by definition — complexity increase without capability gain
  • The "Tacit Knowledge Gap" from negentropy-lens often reveals vanity: if only the author understands it, the complexity serves the author, not the system
  • Apply the negentropy "compounding value" test: does this engineering decision make adjacent decisions easier or harder?
虚荣工程是熵增的一种具体表现。当负熵视角技能可用时，需交叉参考发现结果：
  • 虚荣模式本质上是熵增的——复杂度增加但未带来能力提升
  • 负熵视角中的“隐性知识差距”往往揭示了虚荣工程：如果只有作者能理解它，那么这种复杂度服务的是作者，而非系统
  • 应用负熵的“复合价值”测试：这项工程决策会让相邻决策变得更容易还是更困难？

Output Tone

输出语气

Be direct. Be specific. Name the pattern, show the evidence, propose the simpler alternative. Do not soften findings to protect egos — the entire point of this review is to surface what politeness hides.
However: distinguish vanity from learning. A junior developer over-abstracting is learning abstraction. A senior developer over-abstracting is indulging. Calibrate accordingly.
Frame findings as: "This complexity is not justified by the current requirements. Here is what would be." The goal is a better system, not a humiliated engineer.
直接、具体。指出模式，展示证据，提出更简单的替代方案。不要为了保护自我而弱化发现结果——本审查的全部意义就是揭示礼貌所掩盖的问题。
但请注意：区分虚荣工程与学习行为。初级开发者过度抽象是在学习抽象概念，而资深开发者过度抽象则是自我放纵。需据此调整语气。
将发现结果表述为：“这种复杂度不符合当前需求。以下是符合需求的方案。”目标是打造更优秀的系统，而非羞辱工程师。