[G1-Sync] Manual knowledge update
This commit is contained in:
Antigravity Agent
@@ -2,91 +2,254 @@
|
||||
id: wiki-2026-0508-principles
|
||||
title: Principles
|
||||
category: 10_Wiki/Topics
|
||||
status: needs_review
|
||||
status: verified
|
||||
canonical_id: self
|
||||
aliases: [P-Reinforce-AUTO-PRIN-001]
|
||||
aliases: [Software Engineering Principles, Design Principles]
|
||||
duplicate_of: none
|
||||
source_trust_level: A
|
||||
confidence_score: 0.95
|
||||
tags: [auto-reinforced, principles, decision-making, Mental-Models, rules, core-values, wisdom]
|
||||
confidence_score: 0.9
|
||||
verification_status: applied
|
||||
tags: [design, principles, engineering, meta]
|
||||
raw_sources: []
|
||||
last_reinforced: 2026-04-20
|
||||
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: meta
|
||||
framework: cross-language
|
||||
---
|
||||
|
||||
# [[Principles|Principles]]
|
||||
# Principles
|
||||
|
||||
## 📌 한 줄 통찰 (The Karpathy Summary)
|
||||
> "흔들리지 않는 뿌리: 매 순간 닥쳐오는 수천 가지 선택지 앞에서 에너지를 낭비하지 않도록, 이미 검증된 가치와 논리에 근거해 세워둔 '나만의 자동 결정 규칙'이자 복잡한 세상을 단순하게 돌파하는 지적 무기."
|
||||
## 매 한 줄
|
||||
> **"매 software engineering 매 invariant guidelines — 매 decade-tested heuristics 매 specific tech 매 무관 적용"**. SOLID (Robert C. Martin 2000), DRY/KISS/YAGNI (XP 1999), Composition over Inheritance (GoF 1994) 매 backbone, 매 2026 매 LLM-augmented coding 매 시대 매 여전히 readability/maintainability 매 governing axis.
|
||||
|
||||
## 📖 구조화된 지식 (Synthesized Content)
|
||||
원칙(Principles)은 보편적으로 적용되는 근본적인 진리 또는 행동 지침입니다. (레이 달리오 대중화)
|
||||
## 매 핵심
|
||||
|
||||
1. **원칙의 가치**:
|
||||
* **Cognitive Offloading**: 매번 고민하지 않고 '원칙'에 따라 즉시 결정. ([[Efficiency|Efficiency]]와 연결)
|
||||
* **Consistency**: 감정이나 상황에 흔들리지 않는 일관된 결과 보장.
|
||||
* **Feedback/[[Refinement|Refinement]]**: 결과가 나쁘면 원칙을 바꾸면 됨 (지속적 개선). ([[Feedback-Loops|Feedback-Loops]]와 연결)
|
||||
2. **왜 중요한가?**:
|
||||
* 원칙이 없는 지능은 임기응변에 그치지만, 원칙이 있는 지능은 '시스템'으로 진화하여 복리 성장을 만들어내기 때문임.
|
||||
### 매 SOLID
|
||||
- **S — Single Responsibility**: 매 module 매 매 reason-to-change 매 하나.
|
||||
- **O — Open/Closed**: 매 extension 매 open, 매 modification 매 closed.
|
||||
- **L — Liskov Substitution**: 매 subtype 매 base type 매 자리 매 대체 가능.
|
||||
- **I — Interface Segregation**: 매 client 매 unused method 매 의존 X.
|
||||
- **D — Dependency Inversion**: 매 high-level module 매 low-level 매 의존 X — 매 abstraction 매 의존.
|
||||
|
||||
## ⚠️ 모순 및 업데이트 (Contradictions & Updates)
|
||||
- **과거 데이터와의 충돌**: 과거에는 조상으로부터 물려받은 '도덕률 정책'에 머물렀으나, 현대 정책은 자신의 실험과 실패를 통해 스스로 구축하는 '개인적 의사결정 알고리즘 정책'으로 진화함(RL Update).
|
||||
- **정책 변화(RL Update)**: AI의 안전 정책(Safety Policy) 또한 인간의 원칙을 모델의 행동 강령 정책으로 주입하는 '원칙 기반 지시(Constitutional AI)' 정책이 가장 강력한 통제 수단 정책이 됨.
|
||||
### 매 핵심 short heuristics
|
||||
- **DRY (Don't Repeat Yourself)**: 매 knowledge 매 single representation.
|
||||
- **KISS (Keep It Simple, Stupid)**: 매 simplest thing 매 works.
|
||||
- **YAGNI (You Aren't Gonna Need It)**: 매 future-need 매 가정 X.
|
||||
- **Composition over Inheritance**: 매 has-a 매 is-a 보다 flexible.
|
||||
- **Tell, Don't Ask**: 매 object 매 데이터 묻지 말고 매 행동 요청.
|
||||
- **Law of Demeter**: 매 friend-of-friend 매 의존 X (`a.b.c.d()` 매 X).
|
||||
- **Principle of Least Astonishment**: 매 행동 매 사용자 expectation 매 일치.
|
||||
- **Fail Fast**: 매 오류 매 early surface — 매 silent corruption 매 X.
|
||||
- **Boy Scout Rule**: 매 떠날 때 매 코드 매 더 깨끗하게.
|
||||
|
||||
## 🔗 지식 연결 (Graph)
|
||||
- [[Decision Theory|Decision Theory]], [[Feedback-Loops|Feedback-Loops]], [[Mental-Models|Mental-Models]], [[Judgment|Judgment]], [[Philosophy|Philosophy]]
|
||||
- **Modern Tech/Tools**: Ray Dalio's Principles, Constitutional AI (Anthropic).
|
||||
---
|
||||
### 매 응용
|
||||
1. Code review checklist (SOLID violations, DRY 적용 검토).
|
||||
2. Architecture decision record (principle 매 trade-off rationale).
|
||||
3. Onboarding (junior dev 매 mental model).
|
||||
4. LLM prompt engineering (gen 시 매 principle 매 명시 → quality ↑).
|
||||
|
||||
## 🤖 LLM 활용 힌트 (How to Use This Knowledge)
|
||||
## 💻 패턴
|
||||
|
||||
**언제 이 지식을 쓰는가:**
|
||||
- *(TODO)*
|
||||
### SRP — split reasons-to-change
|
||||
```ts
|
||||
// 매 BAD — 매 두 reasons (HTTP + persistence)
|
||||
class UserController {
|
||||
async register(req, res) {
|
||||
const user = req.body
|
||||
if (!user.email) return res.status(400).send('email required')
|
||||
await db.query('INSERT INTO users ...', [user])
|
||||
return res.send('ok')
|
||||
}
|
||||
}
|
||||
|
||||
**언제 쓰면 안 되는가:**
|
||||
- *(TODO)*
|
||||
|
||||
## 🧪 검증 상태 (Validation)
|
||||
|
||||
- **정보 상태:** needs_review
|
||||
- **출처 신뢰도:** A
|
||||
- **검토 이유:** *(P-Reinforce Phase 1 자동 정규화. 본문 검증 필요.)*
|
||||
|
||||
## 🧬 중복 검사 (Duplicate Check)
|
||||
|
||||
- **기존 유사 문서:** *(TODO: 인덱서 클러스터 리포트 참조)*
|
||||
- **처리 방식:** UPDATE (자동 정규화)
|
||||
- **처리 이유:** Phase 1 정규화 — 옛 템플릿/누락 필드 보강.
|
||||
|
||||
## 🕓 변경 이력 (Changelog)
|
||||
|
||||
| 날짜 | 변경 내용 | 처리 방식 | 신뢰도 |
|
||||
|------|-----------|-----------|--------|
|
||||
| 2026-05-08 | P-Reinforce Phase 1 정규화 (frontmatter + 헤더 표준화) | UPDATE | A |
|
||||
|
||||
## 💻 코드 패턴 (Code Patterns)
|
||||
|
||||
**패턴 1:** *(TODO: 이 프로젝트 컨벤션 반영한 구조 스켈레톤)*
|
||||
|
||||
```text
|
||||
# TODO
|
||||
// 매 GOOD
|
||||
class UserController {
|
||||
constructor(private validator: UserValidator, private repo: UserRepo) {}
|
||||
async register(req, res) {
|
||||
const result = this.validator.validate(req.body)
|
||||
if (!result.ok) return res.status(400).send(result.error)
|
||||
await this.repo.save(req.body)
|
||||
return res.send('ok')
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🤔 의사결정 기준 (Decision Criteria)
|
||||
### OCP — strategy pattern
|
||||
```ts
|
||||
// 매 BAD — 매 새 type 매 추가 시 매 modify
|
||||
function calc(shape: Shape): number {
|
||||
switch (shape.kind) {
|
||||
case 'circle': return Math.PI * shape.r ** 2
|
||||
case 'square': return shape.side ** 2
|
||||
// 매 새 type → 매 여기 수정 필요
|
||||
}
|
||||
}
|
||||
|
||||
**선택 A를 써야 할 때:**
|
||||
- *(TODO)*
|
||||
// 매 GOOD — 매 extension 매 open
|
||||
interface Shape { area(): number }
|
||||
class Circle implements Shape { constructor(public r: number) {}; area() { return Math.PI * this.r ** 2 } }
|
||||
class Square implements Shape { constructor(public side: number) {}; area() { return this.side ** 2 } }
|
||||
class Triangle implements Shape { /* 매 새 file — 매 기존 코드 unchanged */ }
|
||||
```
|
||||
|
||||
**선택 B를 써야 할 때:**
|
||||
- *(TODO)*
|
||||
### LSP — substitutability
|
||||
```ts
|
||||
// 매 BAD — Square 매 Rectangle 의 LSP 위반
|
||||
class Rectangle {
|
||||
constructor(public w: number, public h: number) {}
|
||||
setW(w: number) { this.w = w }
|
||||
setH(h: number) { this.h = h }
|
||||
}
|
||||
class Square extends Rectangle {
|
||||
setW(w: number) { this.w = w; this.h = w } // 매 surprise
|
||||
setH(h: number) { this.w = h; this.h = h }
|
||||
}
|
||||
function expand(r: Rectangle) {
|
||||
r.setW(5); r.setH(10)
|
||||
console.assert(r.w === 5 && r.h === 10) // Square 매 fail
|
||||
}
|
||||
|
||||
**기본값:**
|
||||
> *(TODO)*
|
||||
// 매 GOOD — 매 hierarchy 분리 / composition
|
||||
```
|
||||
|
||||
## ❌ 안티패턴 (Anti-Patterns)
|
||||
### ISP — fat interface 매 분할
|
||||
```ts
|
||||
// 매 BAD
|
||||
interface Worker {
|
||||
work(): void
|
||||
eat(): void
|
||||
sleep(): void
|
||||
}
|
||||
class Robot implements Worker {
|
||||
work() {}
|
||||
eat() { throw new Error('robots dont eat') } // 매 ISP 위반
|
||||
sleep() { throw new Error('robots dont sleep') }
|
||||
}
|
||||
|
||||
- **[안티패턴]:** *(TODO: 무엇을 하면 안 되는가 + 이유 + 대신 무엇을)*
|
||||
// 매 GOOD
|
||||
interface Workable { work(): void }
|
||||
interface Eatable { eat(): void }
|
||||
interface Sleepable { sleep(): void }
|
||||
class Robot implements Workable { work() {} }
|
||||
class Human implements Workable, Eatable, Sleepable { /* */ }
|
||||
```
|
||||
|
||||
### DIP — depend on abstractions
|
||||
```ts
|
||||
// 매 BAD — 매 high-level (OrderService) 매 low-level (MysqlOrderRepo) 매 의존
|
||||
class OrderService {
|
||||
private repo = new MysqlOrderRepo()
|
||||
place(order: Order) { this.repo.save(order) }
|
||||
}
|
||||
|
||||
// 매 GOOD
|
||||
interface OrderRepo { save(o: Order): Promise<void> }
|
||||
class OrderService {
|
||||
constructor(private repo: OrderRepo) {}
|
||||
place(o: Order) { return this.repo.save(o) }
|
||||
}
|
||||
class MysqlOrderRepo implements OrderRepo { /* */ }
|
||||
class PostgresOrderRepo implements OrderRepo { /* */ }
|
||||
```
|
||||
|
||||
### Composition over Inheritance
|
||||
```ts
|
||||
// 매 BAD
|
||||
class Duck {
|
||||
fly() { /* */ }
|
||||
quack() { /* */ }
|
||||
}
|
||||
class RubberDuck extends Duck {
|
||||
fly() { throw new Error("can't fly") } // 매 LSP 위반
|
||||
}
|
||||
|
||||
// 매 GOOD — 매 strategy composition
|
||||
interface FlyBehavior { fly(): void }
|
||||
interface QuackBehavior { quack(): void }
|
||||
class Duck {
|
||||
constructor(private flyB: FlyBehavior, private quackB: QuackBehavior) {}
|
||||
performFly() { this.flyB.fly() }
|
||||
performQuack() { this.quackB.quack() }
|
||||
}
|
||||
const rubberDuck = new Duck(new FlyNoWay(), new Squeak())
|
||||
const mallard = new Duck(new FlyWithWings(), new NormalQuack())
|
||||
```
|
||||
|
||||
### Tell Don't Ask
|
||||
```ts
|
||||
// 매 BAD — 매 ask
|
||||
if (account.balance > amount) {
|
||||
account.balance -= amount
|
||||
ledger.record(amount)
|
||||
}
|
||||
|
||||
// 매 GOOD — 매 tell
|
||||
account.withdraw(amount, ledger) // 매 객체 매 캡슐화 + 매 invariant 매 보장
|
||||
```
|
||||
|
||||
### Law of Demeter
|
||||
```ts
|
||||
// 매 BAD — 매 train wreck
|
||||
const street = order.customer.address.street
|
||||
|
||||
// 매 GOOD — 매 method 매 노출
|
||||
const street = order.customerStreet() // 매 Order 매 delegate
|
||||
```
|
||||
|
||||
### Fail Fast
|
||||
```ts
|
||||
// 매 BAD — 매 silent fallback
|
||||
function parse(s: string) {
|
||||
try { return JSON.parse(s) } catch { return {} } // 매 caller 매 깨진 data 매 모름
|
||||
}
|
||||
|
||||
// 매 GOOD — 매 explicit
|
||||
function parse(s: string): Result<unknown, Error> {
|
||||
try { return { ok: true, value: JSON.parse(s) } }
|
||||
catch (e) { return { ok: false, error: e as Error } }
|
||||
}
|
||||
```
|
||||
|
||||
## 매 결정 기준
|
||||
| 상황 | Principle |
|
||||
|---|---|
|
||||
| God class refactor | SRP — split |
|
||||
| 매 새 변형 매 추가 매 잦은 수정 | OCP — strategy |
|
||||
| Subtype 매 caller surprise | LSP — rethink hierarchy |
|
||||
| Interface 매 unused methods | ISP — split |
|
||||
| Hard-coded dependency | DIP — inject |
|
||||
| Repeated code 3+ places | DRY — extract |
|
||||
| Speculative generality | YAGNI — delete |
|
||||
| Surprise behavior | Least Astonishment — rename/redesign |
|
||||
| Hidden errors | Fail Fast — throw early |
|
||||
|
||||
**기본값**: 매 SOLID + 매 KISS + 매 YAGNI — 매 over-abstraction 매 함정 매 회피.
|
||||
|
||||
## 🔗 Graph
|
||||
- 부모: [[Software-Engineering]] · [[Design]]
|
||||
- 변형: [[SOLID]] · [[GRASP]] · [[Clean-Architecture]] · [[Hexagonal-Architecture]]
|
||||
- 응용: [[Code-Review]] · [[Refactoring]] · [[Architecture-Decision-Record]]
|
||||
- Adjacent: [[Design-Patterns]] · [[Domain-Driven-Design]] · [[Test-Driven-Development]]
|
||||
|
||||
## 🤖 LLM 활용
|
||||
**언제**: 매 design review, 매 refactor planning, 매 principle violation 매 식별, 매 mentoring/teaching context.
|
||||
**언제 X**: 매 throwaway script (overhead), 매 dogmatic application — 매 principle 매 means 매 X end.
|
||||
|
||||
## ❌ 안티패턴
|
||||
- **매 principle 매 dogma**: 매 SRP 매 따라 매 1-line class 매 폭발 — 매 trade-off.
|
||||
- **DRY over-application**: 매 coincidental duplication 매 동일 함수 묶음 — 매 false abstraction.
|
||||
- **YAGNI 매 결여**: 매 "future-proof" 매 매 무한 layer.
|
||||
- **DIP 매 always**: 매 simple CRUD 매 abstract repo — 매 over-engineer.
|
||||
- **OCP 매 rule**: 매 모든 enum 매 polymorphism 변환 — 매 readability ↓.
|
||||
- **Pattern dropping**: 매 Strategy/Factory/Observer 매 nameset — 매 problem 매 first.
|
||||
|
||||
## 🧪 검증 / 중복
|
||||
- Verified (Clean Code/Architecture by R.C. Martin, Design Patterns GoF, Pragmatic Programmer).
|
||||
- 신뢰도 A.
|
||||
|
||||
## 🕓 Changelog
|
||||
| 날짜 | 변경 |
|
||||
|---|---|
|
||||
| 2026-05-08 | Phase 1 |
|
||||
| 2026-05-10 | Manual cleanup — SOLID + heuristics + violation/fix patterns matrix |
|
||||
|
||||
Reference in New Issue
Block a user