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.
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.
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):
Who uses this? (End users, internal team, API consumers, nobody yet)
What must it do? (Core user stories / jobs-to-be-done — max 5)
What scale does it actually operate at? (Not projected. Actual.)
What are the real constraints? (Regulatory, latency SLAs, integration requirements)
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.
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?"]
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.
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.
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
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:
Primary success metric >= target for 7 consecutive days
P95 latency <= defined SLA for 7 consecutive days
Zero security incidents attributable to the component
Operational cost under budget cap for 7 consecutive days
At least 2 team members can independently modify and deploy it
Documentation exists and was validated by someone who did not write the code
"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.
"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.
"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.
"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.
"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.
"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.
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?
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.