Files

T

Antigravity Agent 504fd5fb42 [G1-Sync] Manual knowledge update

2026-05-10 22:08:15 +09:00

4.8 KiB

Raw Blame History

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

title

Cognitive Load

매 한 줄

"매 working memory 에 동시에 매 잡고 있어야 하는 정보의 양". Sweller 의 cognitive load theory (1988) 에 기반 — intrinsic, extraneous, germane 의 3-tier. 매 modern software design 의 first-principle metric — 작은 cognitive load 가 매 maintainable code 를 결정.

매 핵심

매 3 종류

Intrinsic: 문제 자체의 본질적 복잡도 (e.g., distributed consensus).
Extraneous: 표현/도구 가 만드는 인위적 복잡도 (bad naming, deep nesting).
Germane: schema 형성 과정 (learning) — useful load.

매 7±2 rule

Working memory 는 약 4-7 chunk 만 동시 처리 (Miller 1956, refined Cowan 2001).
Code 가 이 한계 넘으면 → bug, slow review, onboarding 지연.

매 응용

Function 의 line / parameter 제한 (small functions).
Module boundary 설계 — high cohesion, low coupling.
PR size 제한 (200-400 line max).
Naming convention — domain language 사용.

💻 패턴

Guard clause 로 nesting 줄임

# BAD: deep nesting (high extraneous load)
def process(user):
    if user is not None:
        if user.is_active:
            if user.has_permission('write'):
                return do_work(user)
    return None

# GOOD: early return
def process(user):
    if user is None: return None
    if not user.is_active: return None
    if not user.has_permission('write'): return None
    return do_work(user)

Extract domain primitive

// BAD: primitive obsession — caller must remember semantics
function transfer(from: string, to: string, amount: number, currency: string) {}

// GOOD: types carry semantics
type AccountId = string & { __brand: 'AccountId' };
type Money = { amount: bigint; currency: Currency };
function transfer(from: AccountId, to: AccountId, money: Money) {}

매 colocation

// BAD: scattered — must context-switch
// styles.css, validation.ts, component.tsx, types.ts

// GOOD: single-file feature unit (Astro/Svelte/RSC era)
export function Form() {
  const validate = (v: string) => v.length > 0;
  return <input onBlur={e => validate(e.target.value)} />;
}

Boundary objects

# Each layer translates — caller doesn't need to know inner schema
class UserDTO:  # external API shape
    ...
class User:  # domain entity
    ...
class UserRow:  # DB schema
    ...
def to_domain(dto: UserDTO) -> User: ...
def to_row(user: User) -> UserRow: ...

Team Topologies pattern

# Stream-aligned team owns a single bounded context
# Platform team provides self-service infra
# Goal: each team's cognitive load fits one team's working memory
team: payments
owns: [PaymentService, RefundService, payment-db]
depends_on:
  platform: [k8s-cluster, observability]
  enabling: []

매 결정 기준

상황	Approach
Function > 50 lines	Extract sub-functions or strategy
Class > 7 public methods	Split by responsibility
Team owns > 1 product area	Reorg per Team Topologies
Domain logic mixed w/ infra	Hexagonal / Clean Architecture
Onboarding > 2 weeks	Reduce coupling, write decision records

기본값: Optimize for reader, not writer — 매 reduce extraneous, accept intrinsic.

🔗 Graph

부모: Software Design · Cognitive Psychology
변형: Intrinsic Load · Extraneous Load · Germane Load
응용: Team Topologies · Hexagonal Architecture · Clean Code
Adjacent: Working Memory · Code Smell · Naming Things

🤖 LLM 활용

언제: Code review, refactoring decision, team structure 설계, PR size 판단. 언제 X: Pure performance optimization (different metric).

❌ 안티패턴

Cleverness 자랑: dense one-liner, clever bitwise — high extraneous.
God object: 30+ method class — exceeds chunking capacity.
Magic constants: if x > 86400 대신 SECONDS_PER_DAY.
Implicit context: global mutable state — reader 가 매 trace 해야 함.
Premature abstraction: framework-itis — abstraction 이 intrinsic 아닌데 추가됨.

🧪 검증 / 중복

Verified (Sweller 1988, Skelton & Pais 2019 Team Topologies).
신뢰도 A.

🕓 Changelog

날짜	변경
2026-05-08	Phase 1
2026-05-10	Manual cleanup — cognitive load theory + practical refactoring patterns

4.8 KiB Raw Blame History