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 — cosmetic级：不必要但无害。不会增加维护负担。记录后即可跳过。
  • 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.]
[一段文字：说明该代码库的实际功能与设计目标之间的差异。两者的差距即为虚荣工程的影响范围。]

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.
“一名熟悉该技术栈的新工程师能否在1小时内理解这部分内容？” 如果不能，那这个抽象服务的是作者的思维模型，而非团队的需求。

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?
虚荣工程是熵增的一种具体表现。当Negentropy Lens技能可用时，可交叉参考发现的问题：
  • 虚荣模式本质上是熵增的——在未提升能力的情况下增加复杂度
  • 负熵视角中的“隐性知识差距”常常能揭示虚荣工程：如果只有作者能理解它，那这种复杂度服务的是作者，而非系统
  • 应用负熵的“复合价值”测试：这项工程决策会让相关决策变得更容易还是更困难？

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.
直接、具体。明确指出模式，展示证据，提出更简单的替代方案。不要为了照顾情绪而弱化发现——本评审的核心目的就是揭示礼貌所掩盖的问题。
但请注意：区分虚荣工程与学习行为。初级开发者过度抽象是在学习抽象概念，而资深开发者过度抽象则是自我放纵。需根据情况调整评判标准。
将发现表述为：“当前需求无法证明这种复杂度的合理性。以下是合理的实现方式。”我们的目标是打造更优秀的系统，而非羞辱工程师。