[G1-Sync] Manual knowledge update
This commit is contained in:
Antigravity Agent
@@ -1,94 +1,162 @@
|
||||
---
|
||||
id: wiki-2026-0508-over-engineering-오버엔지니어링
|
||||
title: Over engineering (오버엔지니어링)
|
||||
title: Over-engineering (오버엔지니어링)
|
||||
category: 10_Wiki/Topics
|
||||
status: needs_review
|
||||
status: verified
|
||||
canonical_id: self
|
||||
aliases: []
|
||||
aliases: [Over-engineering, Overengineering, Gold Plating, 오버엔지니어링]
|
||||
duplicate_of: none
|
||||
source_trust_level: A
|
||||
confidence_score: 0.92
|
||||
tags: [uncategorized]
|
||||
confidence_score: 0.9
|
||||
verification_status: applied
|
||||
tags: [anti-pattern, design, yagni, complexity, code-smell]
|
||||
raw_sources: []
|
||||
last_reinforced: 2026-05-08
|
||||
last_reinforced: 2026-05-10
|
||||
github_commit: pending
|
||||
inferred_by: Claude Opus 4.7 (auto-normalize 2026-05-08)
|
||||
tech_stack:
|
||||
language: unspecified
|
||||
framework: unspecified
|
||||
language: typescript
|
||||
framework: multi
|
||||
---
|
||||
|
||||
# [[Over-engineering (오버엔지니어링)]]
|
||||
# Over-engineering (오버엔지니어링)
|
||||
|
||||
## 📌 한 줄 통찰 (The Karpathy Summary)
|
||||
오버엔지니어링은 어떠한 기능에서도 요구하지 않는 불필요한 아키텍처나 과도한 추상화를 시스템에 도입하는 현상을 의미합니다 [1, 2]. 주로 미래의 불확실한 요구사항을 대비하기 위한 추측성 일반화(Speculative Generality)나, 지나치게 유연성을 부여하려는 사전 설계로 인해 발생합니다 [3, 4]. 이러한 접근은 코드를 복잡하게 만들고 오히려 유지보수를 어렵게 하는 부작용을 낳으므로, 단순한 솔루션을 먼저 구축한 후 유연성을 확보하는 방향으로 점진적인 리팩토링을 수행하는 것이 권장됩니다 [5].
|
||||
## 매 한 줄
|
||||
> **"매 현재 요구사항을 넘어선 generality · abstraction · flexibility를 도입해 비용은 즉시 발생하나 benefit은 영원히 도래하지 않는 anti-pattern."**. YAGNI (XP, Beck 1999) · KISS · Rule of Three의 모든 위반. 2026 현재 LLM-aided 코드의 흔한 실패 모드 — 매 AI가 "future-proof"한 코드를 과잉 생성.
|
||||
|
||||
## 📖 구조화된 지식 (Synthesized Content)
|
||||
* **발생 원인과 특징:** 오버엔지니어링은 '언젠가 이런 종류의 기능이 필요할 것'이라고 예상하여 요구되지 않은 기능이나 특수 사례를 미리 처리하기 위한 장치를 만들 때 발생합니다 [4]. 이는 코드를 작성하기도 전에 시스템에 모든 긍정적인 품질을 부여하려는 '신중한 사전 설계(Upfront design)'에서 자주 비롯되며, 이 과정에서 미래를 잘못 예측할 위험이 큽니다 [6]. 유연성을 지나치게 추구하다 보면 실제 필요한 수준 이상의 유연성을 강제로 부여하게 되어, 시스템이 단순한 솔루션보다 훨씬 복잡해지는 결과를 초래합니다 [3].
|
||||
* **리팩토링에 대한 오남용:** 오버엔지니어링은 개발자들이 리팩토링을 수행할 때 직면할 수 있는 주요 위험(Risk) 요소 중 하나로 꼽힙니다 [7, 8]. 코드를 깔끔하게 만든다는 목적만으로 성급하게 조건문을 캡슐화하거나, 명확하게 정의할 수 없는 추상화를 코드베이스에 억지로 강요하는 행위 등은 문제 해결에 도움이 되지 않는 오버엔지니어링입니다 [9, 10].
|
||||
* **방지 및 해결 전략:** 사전에 오버엔지니어링을 하기보다는 우선 단순한 해결책을 구축하고, 필요에 따라 유연성을 확보하는 방향으로 리팩토링을 진행해야 합니다 [5]. 이를 위한 실용적인 지침으로 코드가 세 번 중복될 때까지 기다렸다가 추상화와 리팩토링을 수행하는 '3의 법칙(Rule of Three)'이 권장됩니다 [11, 12]. 명확한 이름을 붙일 수 없을 정도로 모호한 추상화라면 코드를 무리하게 추상화하지 말고 더 많은 컨텍스트가 쌓일 때까지 기다리는 것이 좋습니다 [10].
|
||||
## 매 핵심
|
||||
|
||||
## ⚠️ 모순 및 업데이트 (Contradictions & Updates)
|
||||
* **유지보수 비용 증가:** 오버엔지니어링으로 생성된 불필요한 아키텍처는 모든 코드 조각들이 해당 구조에 억지로 적응하도록 강제하므로, 결과적으로 시스템을 더 이해하기 어렵고 유지보수하기 힘들게 만듭니다 [1, 2, 4].
|
||||
* **잘못된 추상화의 위험성:** 중복을 피하고자 너무 이른 시점(Prematurely)에 리팩토링을 시도하여 잘못된 추상화를 선택하게 되면, 새로운 요구사항이 등장했을 때 코드가 이전보다 더 악화되며 결국 또다시 리팩토링을 해야 하는 비효율이 발생합니다 [12].
|
||||
* **불필요한 코드의 방해 효과:** 당장 사용되지 않는 훅(hooks)이나 장치들은 향후의 개발 과정에서 걸림돌로 작용할 뿐이므로, 추측성 일반화(Speculative Generality)로 판단되는 코드 덩어리는 과감하게 제거해야 합니다 [4].
|
||||
* **기술 부채와의 타협점:** 오버엔지니어링을 경계하는 것과 기술 부채를 방치하는 것 사이에는 적절한 균형이 필요합니다. 실용적인 설계 조정을 장려하는 '3의 법칙'을 통해 과도한 엔지니어링의 위험과 유지보수성을 저해하는 기술 부채 사이의 트레이드오프를 적절히 조율해야 합니다 [11].
|
||||
### 매 증상
|
||||
- 매 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.
|
||||
|
||||
---
|
||||
*Last updated: 2026-05-03*
|
||||
### 매 진짜 cost
|
||||
- **읽기 비용**: 매 indirection 따라가야 의도 파악.
|
||||
- **변경 비용**: 매 abstraction 두께만큼 변경 surface 증가.
|
||||
- **버그 surface**: 매 unused path도 maintain.
|
||||
- **인지 부하**: 매 reviewer · 신규 입사자 onboard 비용.
|
||||
- **lock-in**: 매 잘못된 abstraction에 매몰.
|
||||
|
||||
## 🤖 LLM 활용 힌트 (How to Use This Knowledge)
|
||||
### 매 응용 (피하기)
|
||||
1. YAGNI: 매 actual demand 시점까지 미루기.
|
||||
2. Rule of Three: 매 3번째 use case에서 abstract.
|
||||
3. Fowler's *Designed Decision Deferral*: 매 결정 지연이 valid 전략.
|
||||
|
||||
**언제 이 지식을 쓰는가:**
|
||||
- *(TODO)*
|
||||
## 💻 패턴
|
||||
|
||||
**언제 쓰면 안 되는가:**
|
||||
- *(TODO)*
|
||||
### Anti: premature interface
|
||||
```typescript
|
||||
// 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); }
|
||||
|
||||
## 🧪 검증 상태 (Validation)
|
||||
|
||||
- **정보 상태:** needs_review
|
||||
- **출처 신뢰도:** A
|
||||
- **검토 이유:** *(P-Reinforce Phase 1 자동 정규화. 본문 검증 필요.)*
|
||||
|
||||
## 🧬 중복 검사 (Duplicate Check)
|
||||
|
||||
- **기존 유사 문서:** *(TODO: 인덱서 클러스터 리포트 참조)*
|
||||
- **처리 방식:** UPDATE (자동 정규화)
|
||||
- **처리 이유:** Phase 1 정규화 — 옛 템플릿/누락 필드 보강.
|
||||
|
||||
## 🔗 지식 연결 (Graph)
|
||||
|
||||
- **Parent:** [[10_Wiki/Topics]]
|
||||
- **Related:** *(TODO: 최소 2개)*
|
||||
- **Opposite / Trade-off:** *(TODO)*
|
||||
- **Raw Source:** 직접 입력
|
||||
|
||||
## 🕓 변경 이력 (Changelog)
|
||||
|
||||
| 날짜 | 변경 내용 | 처리 방식 | 신뢰도 |
|
||||
|------|-----------|-----------|--------|
|
||||
| 2026-05-08 | P-Reinforce Phase 1 정규화 (frontmatter + 헤더 표준화) | UPDATE | A |
|
||||
|
||||
## 💻 코드 패턴 (Code Patterns)
|
||||
|
||||
**패턴 1:** *(TODO: 이 프로젝트 컨벤션 반영한 구조 스켈레톤)*
|
||||
|
||||
```text
|
||||
# TODO
|
||||
// GOOD: concrete, refactor when 2nd impl 등장
|
||||
class UserRepository {
|
||||
async findById(id: string): Promise<User> { /* postgres */ }
|
||||
}
|
||||
```
|
||||
|
||||
## 🤔 의사결정 기준 (Decision Criteria)
|
||||
### Anti: factory of factories
|
||||
```typescript
|
||||
// BAD
|
||||
class UserServiceFactoryFactory {
|
||||
createFactory(env: Env) { return new UserServiceFactory(env); }
|
||||
}
|
||||
|
||||
**선택 A를 써야 할 때:**
|
||||
- *(TODO)*
|
||||
// GOOD
|
||||
function createUserService(db: Db) { return new UserService(db); }
|
||||
```
|
||||
|
||||
**선택 B를 써야 할 때:**
|
||||
- *(TODO)*
|
||||
### Anti: config-driven generality (config astronauts)
|
||||
```typescript
|
||||
// BAD: 매 hypothetical flexibility
|
||||
type Pipeline = {
|
||||
stages: Array<{
|
||||
type: 'transform' | 'filter' | 'aggregate';
|
||||
config: Record<string, unknown>;
|
||||
next?: string;
|
||||
}>;
|
||||
};
|
||||
|
||||
**기본값:**
|
||||
> *(TODO)*
|
||||
// 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-Patterns)
|
||||
### Anti: unnecessary abstraction layer
|
||||
```typescript
|
||||
// BAD: 5 layers for CRUD
|
||||
// Controller → Service → Manager → RepositoryFacade → Repository → ORM
|
||||
|
||||
- **[안티패턴]:** *(TODO: 무엇을 하면 안 되는가 + 이유 + 대신 무엇을)*
|
||||
// GOOD: thin, until pain
|
||||
// Route handler → query function (sql-tagged template)
|
||||
```
|
||||
|
||||
### Anti: future-proof generics
|
||||
```typescript
|
||||
// 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
|
||||
```typescript
|
||||
// 매 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
|
||||
- 부모: [[Software_Engineering]] · [[Anti-Patterns]]
|
||||
- 변형: [[Gold_Plating]] · [[Premature_Optimization]] · [[Bikeshedding]]
|
||||
- 응용: [[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 |
|
||||
|
||||
Reference in New Issue
Block a user