2nd/10_Wiki/Topics/Architecture/Over-engineering (오버엔지니어링).md

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, verification_status, tags, raw_sources, last_reinforced, github_commit, tech_stack

id	title	category	status	canonical_id	aliases	duplicate_of	source_trust_level	confidence_score	verification_status	tags	raw_sources	last_reinforced	github_commit	tech_stack
wiki-2026-0508-over-engineering-오버엔지니어링	Over-engineering (오버엔지니어링)	10_Wiki/Topics	verified	self	Over-engineering Overengineering Gold Plating 오버엔지니어링	none	A	0.9	applied	anti-pattern design yagni complexity code-smell		2026-05-10	pending	language framework typescript multi

Over-engineering (오버엔지니어링)

매 한 줄

"매 현재 요구사항을 넘어선 generality · abstraction · flexibility를 도입해 비용은 즉시 발생하나 benefit은 영원히 도래하지 않는 anti-pattern.". YAGNI (XP, Beck 1999) · KISS · Rule of Three의 모든 위반. 2026 현재 LLM-aided 코드의 흔한 실패 모드 — 매 AI가 "future-proof"한 코드를 과잉 생성.

매 핵심

매 증상

• 매 single-impl interface (premature abstraction).
• 매 사용 안 되는 config option · feature flag.
• 매 deep inheritance · 5-layer 아키텍처 for 1k LOC 앱.
• 매 generic을 위한 generic (<T extends BaseEntity<TId>>).
• 매 사용 안 되는 plugin/extension point.

매 진짜 cost

• 읽기 비용: 매 indirection 따라가야 의도 파악.
• 변경 비용: 매 abstraction 두께만큼 변경 surface 증가.
• 버그 surface: 매 unused path도 maintain.
• 인지 부하: 매 reviewer · 신규 입사자 onboard 비용.
• lock-in: 매 잘못된 abstraction에 매몰.

매 응용 (피하기)

1. YAGNI: 매 actual demand 시점까지 미루기.
2. Rule of Three: 매 3번째 use case에서 abstract.
3. Fowler's Designed Decision Deferral: 매 결정 지연이 valid 전략.

💻 패턴

Anti: premature interface

// BAD: 단 하나의 impl, 매 single call site
interface UserRepository {
  findById(id: string): Promise<User>;
}
class PostgresUserRepository implements UserRepository { /* ... */ }
function getUser(repo: UserRepository, id: string) { return repo.findById(id); }

// GOOD: concrete, refactor when 2nd impl 등장
class UserRepository {
  async findById(id: string): Promise<User> { /* postgres */ }
}

Anti: factory of factories

// BAD
class UserServiceFactoryFactory {
  createFactory(env: Env) { return new UserServiceFactory(env); }
}

// GOOD
function createUserService(db: Db) { return new UserService(db); }

Anti: config-driven generality (config astronauts)

// BAD: 매 hypothetical flexibility
type Pipeline = {
  stages: Array<{
    type: 'transform' | 'filter' | 'aggregate';
    config: Record<string, unknown>;
    next?: string;
  }>;
};

// GOOD: explicit, refactor when actual variants exist
async function processOrder(o: Order): Promise<Result> {
  const validated = validate(o);
  const priced = price(validated);
  return persist(priced);
}

Anti: unnecessary abstraction layer

// BAD: 5 layers for CRUD
// Controller → Service → Manager → RepositoryFacade → Repository → ORM

// GOOD: thin, until pain
// Route handler → query function (sql-tagged template)

Anti: future-proof generics

// BAD
class Cache<K, V, E extends CacheEvent<K, V>, S extends Storage<K, V>> {}

// GOOD
class UserCache {
  private map = new Map<string, User>();
  get(id: string) { return this.map.get(id); }
}

Tracking signal — if(false) / dead branch

// 매 over-engineered 흔적: 사용 안 된 code path
if (config.experimentalFastPath) {  // never set
  return fastCompute(input);
}
return slowCompute(input);
// 1년 째 fastPath은 비활성 → 매 즉시 삭제 (YAGNI)

매 결정 기준

상황	Approach
1번 사용	inline / concrete
2번 사용	duplicate (acceptable)
3번 사용	abstract (Rule of Three)
미래 요구 가능성	YAGNI — 미루기
외부 API · 장기 contract	매 abstraction 정당화
명확한 plugin 요구	early extension point OK

기본값: concrete · simple · explicit — 매 abstraction은 actual pain에서 추출.

🔗 Graph

• 변형: Gold_Plating · Premature_Optimization
• 응용: YAGNI (You Aren't Gonna Need It) · Rule of Three (3의 법칙) · KISS
• Adjacent: Refactoring (리팩토링) · Technical Debt (기술 부채) · Boilerplate · God-Object-Antipattern

🤖 LLM 활용

언제: code review, design proposal 평가, AI-generated 코드 정리, refactor backlog 우선순위. 언제 X: 명확한 long-term contract (public API, protocol) — 매 abstraction이 정당함.

❌ 안티패턴

• Speculative generality: 매 "혹시 모르니" — 매 그 혹시는 안 옴.
• Architecture astronaut: 매 N-layer enterprise pattern을 todo 앱에.
• Premature DSL: 매 internal DSL 만들어 본문보다 길어짐.
• Excessive config: 매 설정 가능한 모든 것 → 매 testable surface 폭발.
• AI vibe-engineering: 매 LLM이 제안한 generic을 무비판 수용.

🧪 검증 / 중복

• Verified (Beck XP 1999 / Tidy First? 2024, Fowler "YAGNI" article, Hunt/Thomas Pragmatic Programmer 2nd ed.).
• 신뢰도 A.

🕓 Changelog

날짜	변경
2026-05-08	Phase 1
2026-05-10	Manual cleanup — Over-engineering anti-pattern + concrete examples