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 を読み、その後、プロジェクトに固有のバージョンを作成してください。

---

廃止基準の考え方

人間は物事をやめるのが苦手なため、廃止基準が必要です。私たちは始めたことを続け（サンクコスト）、取り除くより追加し（追加バイアス）、複雑さを価値として捉える（努力の正当化）ようにできています。廃止基準は、停止の判断を自動化し、事前に決定しておき、自我に左右されないものにすることで、この 3 つすべてに対処します。

ティア 1 — 即時廃止（自動、交渉不可）

これらに該当した場合、議論なしで直ちに停止します。継続によって損害が拡大する状況に備えるためのものです。人間の承認は不要です。条件を満たした時点で、対象は停止されます。

例：

• コンポーネントに起因すると判明したセキュリティ侵害
• 重要度 >= P1 の本番環境インシデントがコンポーネントによって発生
• 3 日連続でコストが予算上限を超過
• コンポーネントの利用が 30 日間ゼロ（API 呼び出し、ページビューなどが一切ない）
• 唯一の保守担当者が離任し、2 週間以内に担当を引き受ける人がいない

Tier 2 — レビューのトリガー（自動フラグ、人間が判断）

これらは自動的に廃止されるわけではありませんが、廃止を既定とする方針での必須レビューを促します。 立証責任は停止する側ではなく、継続する側にあります。

例：

• 成功指標が14日連続でしきい値を下回る
• 保守コストが提供価値を上回る（ユーザーへの影響に対するエンジニア工数／月）
• コンポーネントに関する予定外の作業が3スプリント連続で発生する
• 導入した依存関係のいずれかに、CVSS >= 7.0 のCVEがある
• 導入後、チームのベロシティが測定可能なほど低下する

Tier 3 — 継続のための基準（継続には実績が必要）

これらは「成功」がどのような状態かを定義します。定められた期間内に達成できなければ、廃止が既定となります。 これは、機能が既定で存続する通常の流れを逆転させます。

30日間の評価期間の例：

1. 主要な成功指標が7日連続で目標値以上
2. P95レイテンシが7日連続で定義済みのSLA以下
3. コンポーネントに起因するセキュリティインシデントがゼロ
4. 運用コストが7日連続で予算上限以内
5. 少なくとも2人のチームメンバーが、それぞれ独立して変更・デプロイできる
6. ドキュメントが存在し、コードを書いていない人によって検証されている

---

自己満足を見抜く診断の視点

1. 削除テスト

「これを削除したら、誰がいつ気づくでしょうか？」 答えが「誰も」または「作った本人だけ」なら、それは自己満足です。

2. 置き換えテスト

「この仕事の90%をこなす、もっとシンプルなものに置き換えられるでしょうか？」 置き換えられるなら、残りの10%で追加の複雑さを正当化する必要があります。正当化できることはほとんどありません。

3. 新入社員テスト

「このコードベースに加わった有能なエンジニアが、1時間以内に理解できるでしょうか？」 できないなら、その抽象化が役立てているのはチームではなく、作者の頭の中のモデルです。

4. スケールテスト

「この複雑さは現在の規模に見合っていますか。それとも想像上の将来の規模に見合っていますか？」 ユーザーが500人なのに1,000万人向けに構築するのは、慎重なエンジニアリングではありません。幻想です。

5. 履歴書テスト

「この技術をスタックから取り除くと、面接でこのプロジェクトについて話す面白さが減るでしょうか？」 そうなら、それが採用されている理由かもしれません。

6. 依存関係テスト

「この依存関係は、その存在に見合う価値を提供していますか？」 すべての依存関係は負債です。200行を節約する一方で、バンドルに50KBを追加し、アップグレードを繰り返さなければならないライブラリは、その存在に見合う価値を提供していません。

7. 抽象化テスト

「この抽象化には、具体的な実装がいくつありますか？」 インターフェースの背後に実装が1つあるだけなら、抽象化ではありません。間接化です。 2つなら疑わしく、3つでようやく抽象化の効果が現れ始めます。

---

Negentropy Lensとの統合

自己満足のためのエンジニアリングは、エントロピーの具体的な現れです。negentropy-lensスキルが利用可能な場合は、調査結果を相互参照してください。

• 自己満足のパターンは、能力の向上を伴わない複雑さの増加であり、定義上エントロピーを生みます
• negentropy-lensの「暗黙知のギャップ」は、自己満足を明らかにすることがよくあります。作者しか理解できないなら、その複雑さが役立てているのはシステムではなく作者です
• negentropyの「価値の複利」テストを適用してください。このエンジニアリング上の判断は、隣接する判断を容易にしますか、それとも困難にしますか？

---

出力のトーン

率直にしてください。具体的に述べ、パターンを名指しし、根拠を示し、よりシンプルな代替案を提案してください。面子を守るために指摘を和らげないでください。このレビューの目的は、礼儀正しさが覆い隠すものを明らかにすることです。

ただし、自己満足と学習は区別してください。若手開発者が過度に抽象化しているなら、抽象化を学んでいるのです。シニア開発者が過度に抽象化しているなら、自己満足に浸っています。それぞれに応じて判断してください。

指摘は次のように伝えてください。「この複雑さは現在の要件では正当化できません。正当化できるのは次のような場合です。」目標はより良いシステムであり、エンジニアに恥をかかせることではありません。