Update: 2026-04-30 22:59

2026-04-30 23:01:12 +09:00
parent c36c0644a1
commit b845959200
31 changed files with 1268 additions and 42 deletions
@@ -0,0 +1,41 @@
+## 📌 Brief Summary
+현대 프론트엔드 디버깅은 런타임 에러 포착, 성능 병목 진단, 상태 불일치 해결을 아우르는 체계적인 분석 과정이다. 브라우저 개발자 도구(Chrome DevTools)를 통한 로컬 분석부터 Sentry, Datadog과 같은 관측성(Observability) 플랫폼을 활용한 프로덕션 모니터링까지 통합적인 접근을 통해 시스템의 신뢰성을 확보한다.
+
+## 📖 Core Content
+1. **프로덕션 관측성 (Observability Platforms)**
+   - Sentry, LogRocket 등을 통한 실시간 에러 그룹화 및 사용자 여정(Breadcrumbs) 추적.
+   - **세션 리플레이(Session Replay)**: 에러 발생 전의 사용자 조작과 상태 변화를 시각적으로 재현하여 재현 불가능한 버그 차단.
+   - **분산 트레이싱**: 프론트엔드 에러와 백엔드 트레이스 ID를 연결하여 엔드-투-엔드 문제 진단.
+2. **메모리 누수 진단 (Memory Profiling)**
+   - Chrome DevTools의 **Heap Snapshots**을 비교하여 분리된 DOM 노드(Detached DOM nodes)와 가비지 컬렉션(GC)되지 않는 객체 식별.
+   - **Allocation Timelines**: 메모리 할당 시점과 리테이너 경로(Retainer paths)를 분석하여 객체 보존 원인 파악.
+3. **상태 및 렌더링 디버깅**
+   - **Time-travel Debugging**: Redux DevTools 등을 통해 상태 변화를 기록하고 특정 시점으로 액션을 재생하여 비동기 버그 추적.
+   - **Error Boundaries**: React의 렌더링 에러를 선언적으로 포착하여 전체 앱 크래시를 방지하고 에러 스택 정보를 확보.
+
+## ⚖️ Trade-offs & Caveats
+- **로깅 오버헤드**: 과도한 로깅 및 관측성 도구 도입은 번들 사이즈 증가와 런타임 성능 저하를 유발할 수 있으므로 샘플링 전략이 필요하다.
+- **데이터 프라이버시**: 세션 리플레이 및 클라우드 로깅 시 사용자 민감 정보(비밀번호, PII)가 노출되지 않도록 엄격한 마스킹 처리가 선행되어야 한다.
+- **디버깅 도구의 제약**: React Context 등 특정 상태 관리 모델은 전용 디버깅 툴의 부재로 인해 문제 추적이 상대적으로 어렵다.
+
+## 🔗 Knowledge Connections
+### Related Concepts
+- **Heap Snapshots**: 자바스크립트 메모리 구조의 정적 분석 도구 (관계: 메모리 진단 핵심)
+- **Error Boundaries**: 런타임 에러 전파를 차단하는 선언적 격리 장치 (관계: 안정성 확보)
+- **Time-Travel Debugging**: 상태 불일치 원인을 규명하는 시계열 분석 기법 (관계: 비동기 로직 검증)
+
+### Deeper Research Questions
+1. OpenTelemetry를 활용하여 프론트엔드와 마이크로서비스 백엔드 간의 트레이스 컨텍스트를 어떻게 안전하게 전파하는가?
+2. Heap Snapshot 분석 시 'Shallow Size'와 'Retained Size'의 차이가 의미하는 가비지 컬렉션의 실제 작동 원리는?
+3. 세션 리플레이 도구가 캔버스(Canvas)나 WebGL 기반 렌더링의 상호작용을 어떻게 기록하고 재현하는가?
+4. 프로덕션 환경에서 소스 맵(Source Map) 노출 없이 에러 스택을 정확히 복구하는 보안 가이드라인은?
+5. 메모리 리테이너 경로 분석을 통해 발견된 '클로저(Closure)에 의한 메모리 누수'를 해결하는 코드 패턴은?
+
+### Practical Application Contexts
+- **이슈 재현성 확보**: 고객사에서 보고된 불분명한 오류를 LogRocket 리플레이로 확인하여 재현 단계 생략.
+- **성능 튜닝**: 장시간 실행되는 대시보드 앱의 메모리 누수를 Allocation Timeline으로 추적하여 수정.
+
+### Adjacent Topics
+- **Performance Profiling (Lighthouse / Core Web Vitals)**
+- **Static Application Security Testing (SAST)**
+- **Unit & Integration Testing Strategies**
@@ -0,0 +1,46 @@
+## 📌 Brief Summary
+Naming Conventions(명명 규칙)은 코드의 가독성, 유지보수성, 그리고 협업 효율성을 높이기 위해 파일, 컴포넌트, 변수 등의 이름을 짓는 합의된 표준이다. 명확한 규칙을 통해 코드의 역할을 직관적으로 파악하게 하며, 특히 운영체제 간의 대소문자 구분 차이로 인한 빌드 오류를 방지하는 실질적인 엔지니어링 목적을 갖는다.
+
+## 📖 Core Content
+1. **파일 및 폴더 (kebab-case)**
+   - 대소문자 구분이 없는 OS(Windows, macOS)와 엄격한 OS(Linux) 간의 CI/CD 빌드 충돌을 막기 위해 소문자와 하이픈을 사용하는 `kebab-case`를 권장한다.
+   - Next.js의 예약어(`page.js`, `layout.js`)나 라우트 그룹(`(folder)`) 등의 규칙을 준수한다.
+2. **React 컴포넌트 및 타입 (PascalCase)**
+   - 컴포넌트명과 TypeScript의 Type/Interface, Enum 등은 첫 글자를 대문자로 하는 `PascalCase`를 사용하여 일반 변수와 구별한다.
+3. **변수, 함수, 프로퍼티 (camelCase)**
+   - JavaScript 표준에 따라 첫 단어는 소문자로 시작하는 `camelCase`를 사용한다.
+   - Boolean 값은 `is`, `has`, `should` 접두사를, 이벤트 핸들러는 `handle`, `on` 접두사를 붙여 의미를 명확히 한다.
+4. **커스텀 훅 (use 접두사)**
+   - React의 Rules of Hooks를 준수하기 위해 반드시 `use` 접두사로 시작하는 `camelCase`를 사용한다.
+5. **상수 (UPPER_SNAKE_CASE)**
+   - 변경되지 않는 고정 값은 대문자와 밑줄을 사용하는 `UPPER_SNAKE_CASE`로 작성하여 식별력을 높인다.
+6. **Git 및 워크플로우**
+   - 브랜치명: `{type}/{ticket-id}-{description}` 형식의 소문자 kebab-case 사용.
+   - 커밋 메시지: Conventional Commits(`feat:`, `fix:` 등) 형식을 준수하여 추적성을 확보한다.
+
+## ⚖️ Trade-offs & Caveats
+- **엄격함 vs 유연성**: 너무 복잡한 네이밍 규칙은 개발자의 인지 부하를 늘리고 생산성을 저하시킬 수 있으므로, 팀 규모에 맞는 적절한 수준의 합의가 필요하다.
+- **자동화 도구의 한계**: ESLint 등으로 많은 네이밍 규칙을 강제할 수 있으나, '의미론적(Semantic) 적절성'까지는 도구가 판단할 수 없으므로 여전히 코드 리뷰가 중요하다.
+- **프레임워크 제약**: 사용 중인 프레임워크(예: Next.js)의 예약어 규칙이 팀의 컨벤션과 충돌할 경우, 프레임워크의 규칙을 우선시해야 시스템 오류를 방지할 수 있다.
+
+## 🔗 Knowledge Connections
+### Related Concepts
+- **kebab-case**: 파일 시스템 호환성을 위한 소문자-하이픈 조합 (관계: 물리적 저장 표준)
+- **Conventional Commits**: 변경 이력 가독성을 위한 표준 (관계: 협업 워크플로우 규칙)
+- **PascalCase**: 컴포넌트 및 타입 식별을 위한 대문자 시작 조합 (관계: 논리적 식별 표준)
+
+### Deeper Research Questions
+1. OS별 대소문자 인식 차이가 실제 프로덕션 빌드 환경에서 유발하는 'Silent failure' 사례와 그 디버깅 방법은?
+2. 네이밍 규칙 준수가 TypeScript의 타입 추론 성능이나 트리 쉐이킹(Tree Shaking) 효율에 간접적인 영향을 미치는가?
+3. 대규모 리팩토링 시, 기존의 네이밍 컨벤션을 일괄 변경하기 위한 AST(Abstract Syntax Tree) 기반 자동화 도구 활용 방안은?
+4. `isVisible` vs `showComponent`와 같이 상태 중심 네이밍과 명령 중심 네이밍 중 어떤 것이 유지보수에 더 유리한가?
+5. 다국어 지원(i18n) 프로젝트에서 키값(Key) 네이밍을 도메인 중심으로 짓는 것과 페이지 중심으로 짓는 것의 트레이드오프는?
+
+### Practical Application Contexts
+- **협업 환경 구축**: ESLint 및 Prettier 설정을 통해 팀원 전체가 동일한 네이밍 케이스를 사용하도록 자동 강제.
+- **이슈 추적**: 브랜치명에 티켓 ID를 포함하여 Jira/GitHub Issues와 코드를 유기적으로 연결.
+
+### Adjacent Topics
+- **Clean Code & Meaningful Names**
+- **Feature-Sliced Design (FSD)**
+- **Git Branching Strategies**
@@ -0,0 +1,41 @@
+## 📌 Brief Summary
+리팩토링(Refactoring)은 소프트웨어의 외부 동작을 변경하지 않으면서 내부 구조, 가독성, 모듈성을 개선하는 정교한 공학적 작업이다. React 환경에서는 비대한 컴포넌트 분할, 커스텀 훅을 통한 로직 추출, 그리고 기술 부채 상환을 위한 점진적 마이그레이션을 통해 시스템의 확장성과 유지보수성을 극대화하는 것을 목표로 한다.
+
+## 📖 Core Content
+1. **점진적 마이그레이션 (Refactor, Do Not Rewrite)**
+   - 전체 시스템을 한 번에 재작성하는 위험을 피하고, 기능 단위나 도메인 단위로 하나씩 새로운 아키텍처로 옮긴다.
+2. **커스텀 훅을 통한 로직 추출**
+   - 비대한 컴포넌트 내의 데이터 패칭, 폼 처리, 복잡한 계산 로직을 커스텀 훅으로 추출하여 UI와 비즈니스 로직을 분리한다.
+   - 이를 통해 독립적이고 빠른 단위 테스트(Unit Testing) 환경을 확보한다.
+3. **안전망으로서의 테스트 구축**
+   - 리팩토링 전 기존 기능의 동작을 보장하는 테스트 수트를 먼저 작성하여, 변경으로 인한 기능 파손을 즉각 탐지한다.
+4. **구조적 표준화 및 거버넌스**
+   - 클래스형 컴포넌트를 함수형으로 전환하고, TypeScript를 도입하여 정적 안정성을 강화한다.
+   - ESLint 및 Prettier 등 자동화 도구를 통해 팀의 코드 컨벤션과 아키텍처 규칙을 강제한다.
+
+## ⚖️ Trade-offs & Caveats
+- **단기 생산성 저하**: 리팩토링은 당장의 비즈니스 기능 추가보다 많은 시간을 소요할 수 있으므로, 적절한 일정 조율과 경영진의 합의가 필요하다.
+- **과도한 추상화의 위험**: 리팩토링 과정에서 DRY 원칙에만 집착하여 만든 지나치게 복잡한 추상화는 오히려 코드 가독성을 해칠 수 있다(KISS 원칙과의 충돌).
+- **마이그레이션 중단의 위험**: 부분적인 리팩토링이 완료되지 않고 중단될 경우, 시스템 내에 두 가지 이상의 서로 다른 패턴이 혼재되어 유지보수 난이도가 상승할 수 있다.
+
+## 🔗 Knowledge Connections
+### Related Concepts
+- **Custom Hooks**: 로직 분리의 물리적 단위 (관계: 실천 도구)
+- **Incremental Migration**: 안전한 아키텍처 전환 전략 (관계: 핵심 방법론)
+- **Unit Testing**: 리팩토링의 안전을 보장하는 장치 (관계: 필수 선행 조건)
+
+### Deeper Research Questions
+1. 리팩토링 과정에서 기존의 통합 테스트(E2E)를 유지하면서 내부 로직을 단위 테스트로 분리해 나가는 최적의 프로세스는?
+2. 300줄 이상의 거대 컴포넌트를 분할할 때, 상태(State) 전달을 위해 Prop Drilling을 감수할 것인가, 아니면 전역 상태로 승격할 것인가에 대한 판단 기준은?
+3. 리팩토링 중 발견된 레거시 코드의 '잠재적 버그'를 즉시 수정할 것인가, 아니면 리팩토링 완료 후 별도 작업으로 처리할 것인가?
+4. 아키텍처 캡슐화(FSD 등)가 리팩토링 시 사이드 이펙트를 물리적으로 차단하는 구체적인 메커니즘은?
+5. 성능 리팩토링 시, 가독성 좋은 코드와 고성능(메모이제이션 남발 등) 코드 사이의 적절한 타협점은 어디인가?
+
+### Practical Application Contexts
+- **레거시 코드 현대화**: 오래된 React 프로젝트의 기술 스택(Redux -> Zustand 등) 및 컴포넌트 스타일 개선.
+- **지속적 품질 관리**: 기능 추가 전후로 관련 모듈을 SRP 원칙에 맞게 정돈하여 기술 부채 누적 방지.
+
+### Adjacent Topics
+- **Software Engineering Principles (SOLID)**
+- **Technical Debt Management**
+- **Automated Governance & Linting**
@@ -0,0 +1,45 @@
+## 📌 Brief Summary
+리팩토링(Refactoring)은 소프트웨어의 외부 동작을 유지하면서 내부 구조를 개선하여 코드베이스의 건강함과 유지보수성을 확보하는 전문적인 개발 과정이다. 낡은 패러다임을 현대화하고 책임을 분리하며, 강력한 테스트 안전망을 구축함으로써 기술 부채를 상환하고 시스템의 복잡도를 제어하는 것을 목표로 한다.
+
+## 📖 Core Content
+1. **리팩토링 철학: 점진적 마이그레이션**
+   - 위험이 큰 전면 재작성 대신, 기능 단위로 하나씩 새로운 아키텍처로 옮기는 점진적 방식을 취한다.
+   - 이를 통해 시스템 현대화 중에도 신규 기능 개발을 지속할 수 있다.
+2. **React 리팩토링의 핵심: 커스텀 훅**
+   - 비대한 UI 컴포넌트에서 비즈니스 로직을 추출하여 커스텀 훅으로 분리한다.
+   - UI와 로직의 분리를 통해 모듈성을 높이고, 독립적이고 빠른 단위 테스트(Unit Testing) 환경을 확보한다.
+3. **실무적 개선 기법**
+   - 클래스형 컴포넌트의 함수형 전환, JavaScript의 TypeScript 마이그레이션.
+   - 불필요한 `useEffect` 제거 및 서버 상태 관리(TanStack Query) 도입.
+   - DRY(중복 제거) 및 YAGNI(불필요 기능 제거) 원칙을 통한 코드 정리.
+4. **표준화 및 거버넌스**
+   - CSS 작성 방식 표준화, 폴더 구조(FSD 등) 재정렬, 직관적 네이밍 적용.
+   - ESLint 등 자동화 도구를 통해 팀의 모범 사례를 강제한다.
+
+## ⚖️ Trade-offs & Caveats
+- **마이그레이션 과도기 복잡성**: 구형과 신규 패턴이 공존하는 기간 동안 시스템의 일관성이 일시적으로 깨질 수 있으며, 개발자의 인지 부하가 증가한다.
+- **테스트 부재의 위험**: 충분한 테스트 안전망 없이 진행되는 리팩토링은 오히려 예기치 못한 회귀(Regression) 오류를 유발할 수 있다.
+- **과도한 추상화**: 중복 제거(DRY)에 너무 집착할 경우, 오히려 코드가 복잡해져 이해하기 어려워지는 'KISS 원칙 위반' 사례가 발생할 수 있다.
+
+## 🔗 Knowledge Connections
+### Related Concepts
+- **Incremental Migration**: 안전한 아키텍처 전환 전략 (관계: 핵심 방법론)
+- **Custom Hooks**: 로직 분리의 기본 단위 (관계: 실천 도구)
+- **Unit Testing**: 리팩토링의 안정성 보장 (관계: 필수 전제 조건)
+- **Feature-Sliced Design (FSD)**: 캡슐화를 통한 부작용 차단 (관계: 구조적 목표)
+
+### Deeper Research Questions
+1. 대규모 리팩토링 시 구/신규 아키텍처 공존 기간을 최소화하기 위한 'Feature Toggle' 활용 방안은?
+2. 테스트 코드가 전혀 없는 레거시 시스템에서 '안전한 리팩토링'을 시작하기 위한 최소한의 테스트 전략은?
+3. 순환 복잡도를 줄이기 위한 조건문 리팩토링(Guard Clauses 등)이 React JSX 내부 구조에 미치는 영향은?
+4. 리팩토링 중 발견된 '기존의 의도된 버그(Legacy Bug)'를 처리하는 아키텍처적 의사결정 기준은?
+5. AI 도구(LLM)를 활용한 대규모 코드 리팩토링 시, 로직 변질 여부를 자동으로 검증하는 파이프라인 구축 방법은?
+
+### Practical Application Contexts
+- **기술 부채 상환**: 스파게티 코드로 변한 레거시 프로젝트의 구조 개선 및 현대화.
+- **시스템 안정성 강화**: 잦은 에러가 발생하는 모듈을 SRP 원칙에 따라 분해하고 테스트 코드를 보강.
+
+### Adjacent Topics
+- **Technical Debt Management**
+- **Clean Code & Code Smells**
+- **SOLID Principles**