From 8b6f51b719031d3b39607e4fa4acc9ef95d42ddc Mon Sep 17 00:00:00 2001 From: Antigravity Agent Date: Sat, 25 Apr 2026 22:54:21 +0900 Subject: [PATCH] chore: complete wiki-fication of remaining 00_Raw files --- 00_Raw/.gitkeep | 0 ..._Processed_Count_and_Stalled_Loop_Guard.md | 56 +++++++++++++++++++ .../Performance Optimization.md | 27 +++++++++ 10_Wiki/Topics/Frontend_Mastery/React 18.md | 24 ++++++++ .../UI_UX_Assets/Performance Optimization.md | 27 +++++++++ 5 files changed, 134 insertions(+) create mode 100644 00_Raw/.gitkeep create mode 100644 10_Wiki/Topics/Datacollector/2026-04-25-Datacollector_Engine_Processed_Count_and_Stalled_Loop_Guard.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Performance Optimization.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/React 18.md create mode 100644 10_Wiki/Topics_Art/UI_UX_Assets/Performance Optimization.md diff --git a/00_Raw/.gitkeep b/00_Raw/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/10_Wiki/Topics/Datacollector/2026-04-25-Datacollector_Engine_Processed_Count_and_Stalled_Loop_Guard.md b/10_Wiki/Topics/Datacollector/2026-04-25-Datacollector_Engine_Processed_Count_and_Stalled_Loop_Guard.md new file mode 100644 index 00000000..349786e9 --- /dev/null +++ b/10_Wiki/Topics/Datacollector/2026-04-25-Datacollector_Engine_Processed_Count_and_Stalled_Loop_Guard.md @@ -0,0 +1,56 @@ +# Datacollector - processed 카운터 정체 및 엔진 루프 정지 감시 보강 + +- 작성 시각: 2026-04-25 22:52:25 KST +- 프로젝트: `/Volumes/Data/project/Antigravity/Datacollector` +- 관련 파일: `src/lib/engine.ts`, `src/components/AgentDashboard.tsx` + +## 상황 + +사용자는 작업이 되는 것처럼 보이지만 `processed` 수치가 계속 오르지 않고, 서버를 재시작하면 1개가 추가된 뒤 다시 멈춘 것처럼 보인다고 보고했다. + +## 확인한 내용 + +브리지 서버 상태는 정상이고 `/api/health` 기준 `pendingRequests`도 0이었다. 따라서 서버 요청이 계속 물려 있는 문제보다는 프론트엔드 엔진 루프가 한 번 처리한 뒤 다음 반복으로 자연스럽게 이어지지 않는 가능성이 높았다. + +코드상 `processedCount`는 `executeTask()`가 마크다운 생성까지 끝낸 뒤 `store.incrementProcessed()`를 호출할 때만 오른다. 즉 카운터가 오르지 않는다는 것은 다음 중 하나일 가능성이 있다. + +- 다음 작업 합성이 아직 완료되지 않았다. +- 프론트엔드 엔진 루프 타이머가 끊겼다. +- UI 상태는 `running`인데 엔진 내부 싱글톤의 루프가 실제로는 잠든 상태가 되었다. + +## 조치 + +`src/lib/engine.ts`: + +- `isLoopActive`, `lastActivityAt`, `loopTimer`를 추가했다. +- `runLoop()` 중복 실행을 막으면서도, 루프가 잠든 경우 다시 깨울 수 있게 했다. +- `kickIfStalled()`를 추가해 `running` 상태인데 45초 이상 루프 활동이 없으면 자동으로 다음 루프를 시작한다. +- 다음 루프 예약을 `scheduleNextLoop()`로 통합해 타이머를 추적할 수 있게 했다. +- 작업 완료 후 `processedCount`가 반영된 값을 로그로 남기도록 했다. + +`src/components/AgentDashboard.tsx`: + +- 상태가 `running`일 때 15초마다 엔진 heartbeat를 실행한다. +- 엔진 루프가 잠든 것으로 판단되면 `kickIfStalled()`가 자동으로 다시 깨운다. + +## 검증 + +다음 검증을 완료했다. + +```bash +npm run lint +``` + +결과: + +- TypeScript 검사 통과 + +## 운영 메모 + +이제 작업 하나가 완료될 때 Mission Telemetry에 다음 형태의 로그가 추가된다. + +```text +[ENGINE] '토픽명' 처리 카운트 반영 완료: N +``` + +이 로그가 보이면 `processed` 값도 함께 올라가는 것이 정상이다. 만약 이 로그가 보이지 않고 `최종 데이터 합성 중...` 이후 오래 멈춘다면, 그때는 카운터 문제가 아니라 NotebookLM 합성 요청이 오래 걸리거나 실패 응답을 기다리는 상태로 봐야 한다. diff --git a/10_Wiki/Topics/Frontend_Mastery/Performance Optimization.md b/10_Wiki/Topics/Frontend_Mastery/Performance Optimization.md new file mode 100644 index 00000000..0932d324 --- /dev/null +++ b/10_Wiki/Topics/Frontend_Mastery/Performance Optimization.md @@ -0,0 +1,27 @@ +# [[Performance Optimization]] + +## 📌 Brief Summary +성능 최적화(Performance Optimization)는 웹 애플리케이션의 로딩 속도를 단축시키고 사용자 상호작용을 매끄럽게 만들기 위해 브라우저 렌더링 과정과 리소스 처리 방식을 개선하는 일련의 기술적 과정입니다 [1-3]. 주로 초기 렌더링 시간(Fast First Paint)을 앞당기고, 프레임 드롭(Jank)을 방지하며, 최대 콘텐츠풀 페인트(LCP)와 같은 핵심 웹 바이탈(Core Web Vitals) 지표를 향상하는 것을 목표로 합니다 [2-6]. 모던 프론트엔드에서는 중요 렌더링 경로(CRP)의 최소화, React와 같은 프레임워크 수준에서의 불필요한 렌더링 방지, 그리고 적절한 서버/클라이언트 렌더링 전략(SSR, SSG 등)의 선택을 통해 이루어집니다 [1, 7-9]. + +## 📖 Core Content +* **중요 렌더링 경로(CRP) 최적화 및 브라우저 렌더링 제어** + * 브라우저가 HTML, CSS, JavaScript를 화면의 픽셀로 변환하는 '중요 렌더링 경로(Critical Rendering Path)'를 최적화하는 것이 가장 기본입니다 [1, 10]. 초기 렌더링 속도를 높이기 위해 렌더링을 차단하는 리소스를 지연시키거나 제거하며, 불필요한 DOM 노드의 깊이를 최소화해야 합니다 [8, 11, 12]. + * 특히 계산 비용이 큰 레이아웃 재계산인 **리플로우(Reflow)**를 유발하는 속성(예: width, height, margin 조작) 사용을 최소화하고, 시각적 속성만 변경하는 리페인트(Repaint)나 GPU 가속 기반의 컴포지팅(Compositing) 기법을 활용하여 성능 저하를 방지해야 합니다 [6, 12-20]. + +* **React 프레임워크 레벨의 최적화 기법** + * **리렌더링 폭포수(Re-render Cascade) 방지:** 부모 컴포넌트의 상태 변화가 무관한 자식 컴포넌트들의 렌더링까지 유발하는 것을 막기 위해 `React.memo`, `useMemo`, `useCallback`을 사용하여 얕은 비교를 통한 메모이제이션을 수행합니다 [21-25]. + * **자동 일괄 처리 (Automatic Batching):** React 18부터 도입된 기능으로, 네이티브 이벤트 핸들러뿐만 아니라 비동기 작업(Promise, setTimeout 등) 내에서 발생하는 여러 상태 업데이트들을 하나로 묶어(Batching) 단 한 번의 리렌더링만 발생하도록 하여 렌더링 성능을 극대화합니다 [26-33]. + * **동시성 렌더링 (Concurrent Rendering):** `useTransition` 및 `useDeferredValue` 훅을 사용하여 무거운 연산을 후순위로 미루고(Non-urgent), 사용자의 타이핑이나 클릭 같은 긴급한 상호작용(Urgent)을 우선적으로 처리함으로써 UI가 멈추는 현상을 방지합니다 [34-38]. + * **가상화 및 코드 분할:** 수백 개 이상의 긴 목록은 화면에 보이는 항목만 DOM 노드로 생성하는 가상화(Virtualization)를 적용하며 [39, 40], `React.lazy()`를 활용한 라우트 수준의 코드 분할(Code Splitting)로 초기 자바스크립트 번들 크기를 줄여 LCP 점수를 개선합니다 [41]. + +* **아키텍처 및 렌더링 전략 최적화** + * 애플리케이션 특성에 맞춰 **CSR(클라이언트 사이드 렌더링)**, **SSR(서버 사이드 렌더링)**, **SSG(정적 사이트 생성)**, **ISR(점진적 정적 재생성)** 등을 적절히 선택하거나 혼합(Hybrid)하여 사용합니다 [42-60]. + * 최근 도입된 **[[React Server Components]] (RSC)**는 브라우저로 전송되는 자바스크립트 번들 크기를 '0 바이트'로 줄이고 서버 측 자원(DB 등)에 직접 접근하여 렌더링 된 HTML만을 스트리밍 형태로 클라이언트에 전달하므로, 클라이언트 측의 렌더링 및 하이드레이션(Hydration) 부하를 혁신적으로 제거합니다 [61-66]. + +## 🔗 Knowledge Connections +- **Related Topics:** [[Critical Rendering Path]], [[Reflow and Repaint]], [[Automatic Batching]], [[React Compiler]], [[Virtual DOM]], [[Server-Side Rendering (SSR)]], [[React Server Components]] +- **Projects/Contexts:** [[React 18 Concurrent Features]], [[Next.js App Router]] +- **Contradictions/Notes:** 과거에는 개발자가 수동으로 `useMemo`나 `useCallback`, `React.memo`를 삽입하여 불필요한 리렌더링을 최적화해야 했으나, 최근 안정화된 **React Compiler**는 빌드 타임에 코드와 데이터 흐름을 분석하여 이러한 메모이제이션 경계를 자동으로 삽입해 줍니다. 따라서 이제 수동 메모이제이션은 컴파일러의 자동 처리에 의존하게 되어 대부분 제거될 수 있으나, 효과적인 의존성 제어나 서드파티 라이브러리 통합 등 특수한 예외 상황의 '비상 탈출구(Escape Hatch)' 용도로만 제한적으로 남게 됩니다 [25, 67-72]. + +--- +*Last updated: 2026-04-25* \ No newline at end of file diff --git a/10_Wiki/Topics/Frontend_Mastery/React 18.md b/10_Wiki/Topics/Frontend_Mastery/React 18.md new file mode 100644 index 00000000..38fb3d77 --- /dev/null +++ b/10_Wiki/Topics/Frontend_Mastery/React 18.md @@ -0,0 +1,24 @@ +# [[React 18]] + +## 📌 Brief Summary +React 18은 렌더링 과정을 최적화하여 프론트엔드 성능을 크게 향상시키는 기능을 도입한 주요 버전입니다 [1-3]. 이 버전의 가장 핵심적인 특징은 '자동 일괄 처리(Automatic Batching)'가 기본적으로 활성화되어, 다양한 비동기 작업의 상태 업데이트를 하나로 묶어 처리한다는 점입니다 [3-5]. 이를 통해 불필요한 리렌더링을 방지하고 애플리케이션의 반응성과 전체적인 프레임 속도를 매끄럽게 개선합니다 [2, 6, 7]. + +## 📖 Core Content +* **자동 일괄 처리(Automatic Batching)의 전면 적용** + React 18 이전에는 `onClick`이나 `onChange` 같은 React의 네이티브 이벤트 핸들러 내부의 업데이트만 일괄 처리되었습니다 [2, 8, 9]. 하지만 React 18부터는 프로미스(Promises), `setTimeout`, `async/await` 함수와 같은 비동기 작업 내에서 발생하는 상태 업데이트까지 출처에 상관없이 자동으로 일괄 처리합니다 [2, 5, 8, 9]. 즉, 빠른 시간 내에 여러 상태 업데이트가 발생해도 DOM을 한 번만 업데이트하여 성능 병목 현상을 방지합니다 [4, 6, 10, 11]. + +* **가상 DOM(Virtual DOM) Diffing 프로세스 경량화** + 여러 상태 변화를 한 번의 리렌더링으로 결합함으로써 가상 DOM의 Diffing 작업 횟수 자체가 줄어듭니다 [12]. 또한 `React.memo`나 `useMemo` 등을 통해 메모이제이션된 값에 대한 검사 횟수도 줄어들어, 렌더링 주기 당 CPU 작업량이 대폭 감소합니다 [12]. 실제 데이터 집약적인 대시보드를 대상으로 한 벤치마크에 따르면, 자동 일괄 처리를 통해 전체 렌더링 횟수가 약 40% 감소하고 최대 부하 시 프레임 속도가 25% 향상되었습니다 [1, 13]. + +* **업데이트 우선순위 제어 기능 (startTransition & flushSync)** + React 18은 렌더링 우선순위를 개발자가 직접 제어할 수 있는 API를 제공합니다 [13]. + * **`startTransition`**: 목록 필터링과 같이 무겁고 긴급하지 않은 상태 업데이트를 표시하여, 사용자의 타이핑이나 클릭 같은 긴급한 인터랙션을 차단하지 않도록 양보(yield)합니다 [13, 14]. + * **`flushSync`**: 즉각적인 UI 업데이트가 필수적인 경우(예: 상태 변경 직후의 입력 포커스 지정 등), React가 업데이트를 강제로 동기식으로 반영하게 만들어 자동 일괄 처리에서 예외로 둘 수 있습니다 [7, 13-15]. + +## 🔗 Knowledge Connections +- **Related Topics:** [[Automatic Batching]], [[Virtual DOM]], [[startTransition]], [[flushSync]] +- **Projects/Contexts:** [[React Performance Optimization]] +- **Contradictions/Notes:** 소스에 따르면 `flushSync`를 사용해 자동 일괄 처리를 막을 수 있지만, 이를 남용하면 일괄 처리로 얻을 수 있는 성능 이점이 무효화될 수 있으므로 꼭 필요한 경우에만 제한적으로 사용해야 합니다 [7, 16]. + +--- +*Last updated: 2026-04-25* \ No newline at end of file diff --git a/10_Wiki/Topics_Art/UI_UX_Assets/Performance Optimization.md b/10_Wiki/Topics_Art/UI_UX_Assets/Performance Optimization.md new file mode 100644 index 00000000..0932d324 --- /dev/null +++ b/10_Wiki/Topics_Art/UI_UX_Assets/Performance Optimization.md @@ -0,0 +1,27 @@ +# [[Performance Optimization]] + +## 📌 Brief Summary +성능 최적화(Performance Optimization)는 웹 애플리케이션의 로딩 속도를 단축시키고 사용자 상호작용을 매끄럽게 만들기 위해 브라우저 렌더링 과정과 리소스 처리 방식을 개선하는 일련의 기술적 과정입니다 [1-3]. 주로 초기 렌더링 시간(Fast First Paint)을 앞당기고, 프레임 드롭(Jank)을 방지하며, 최대 콘텐츠풀 페인트(LCP)와 같은 핵심 웹 바이탈(Core Web Vitals) 지표를 향상하는 것을 목표로 합니다 [2-6]. 모던 프론트엔드에서는 중요 렌더링 경로(CRP)의 최소화, React와 같은 프레임워크 수준에서의 불필요한 렌더링 방지, 그리고 적절한 서버/클라이언트 렌더링 전략(SSR, SSG 등)의 선택을 통해 이루어집니다 [1, 7-9]. + +## 📖 Core Content +* **중요 렌더링 경로(CRP) 최적화 및 브라우저 렌더링 제어** + * 브라우저가 HTML, CSS, JavaScript를 화면의 픽셀로 변환하는 '중요 렌더링 경로(Critical Rendering Path)'를 최적화하는 것이 가장 기본입니다 [1, 10]. 초기 렌더링 속도를 높이기 위해 렌더링을 차단하는 리소스를 지연시키거나 제거하며, 불필요한 DOM 노드의 깊이를 최소화해야 합니다 [8, 11, 12]. + * 특히 계산 비용이 큰 레이아웃 재계산인 **리플로우(Reflow)**를 유발하는 속성(예: width, height, margin 조작) 사용을 최소화하고, 시각적 속성만 변경하는 리페인트(Repaint)나 GPU 가속 기반의 컴포지팅(Compositing) 기법을 활용하여 성능 저하를 방지해야 합니다 [6, 12-20]. + +* **React 프레임워크 레벨의 최적화 기법** + * **리렌더링 폭포수(Re-render Cascade) 방지:** 부모 컴포넌트의 상태 변화가 무관한 자식 컴포넌트들의 렌더링까지 유발하는 것을 막기 위해 `React.memo`, `useMemo`, `useCallback`을 사용하여 얕은 비교를 통한 메모이제이션을 수행합니다 [21-25]. + * **자동 일괄 처리 (Automatic Batching):** React 18부터 도입된 기능으로, 네이티브 이벤트 핸들러뿐만 아니라 비동기 작업(Promise, setTimeout 등) 내에서 발생하는 여러 상태 업데이트들을 하나로 묶어(Batching) 단 한 번의 리렌더링만 발생하도록 하여 렌더링 성능을 극대화합니다 [26-33]. + * **동시성 렌더링 (Concurrent Rendering):** `useTransition` 및 `useDeferredValue` 훅을 사용하여 무거운 연산을 후순위로 미루고(Non-urgent), 사용자의 타이핑이나 클릭 같은 긴급한 상호작용(Urgent)을 우선적으로 처리함으로써 UI가 멈추는 현상을 방지합니다 [34-38]. + * **가상화 및 코드 분할:** 수백 개 이상의 긴 목록은 화면에 보이는 항목만 DOM 노드로 생성하는 가상화(Virtualization)를 적용하며 [39, 40], `React.lazy()`를 활용한 라우트 수준의 코드 분할(Code Splitting)로 초기 자바스크립트 번들 크기를 줄여 LCP 점수를 개선합니다 [41]. + +* **아키텍처 및 렌더링 전략 최적화** + * 애플리케이션 특성에 맞춰 **CSR(클라이언트 사이드 렌더링)**, **SSR(서버 사이드 렌더링)**, **SSG(정적 사이트 생성)**, **ISR(점진적 정적 재생성)** 등을 적절히 선택하거나 혼합(Hybrid)하여 사용합니다 [42-60]. + * 최근 도입된 **[[React Server Components]] (RSC)**는 브라우저로 전송되는 자바스크립트 번들 크기를 '0 바이트'로 줄이고 서버 측 자원(DB 등)에 직접 접근하여 렌더링 된 HTML만을 스트리밍 형태로 클라이언트에 전달하므로, 클라이언트 측의 렌더링 및 하이드레이션(Hydration) 부하를 혁신적으로 제거합니다 [61-66]. + +## 🔗 Knowledge Connections +- **Related Topics:** [[Critical Rendering Path]], [[Reflow and Repaint]], [[Automatic Batching]], [[React Compiler]], [[Virtual DOM]], [[Server-Side Rendering (SSR)]], [[React Server Components]] +- **Projects/Contexts:** [[React 18 Concurrent Features]], [[Next.js App Router]] +- **Contradictions/Notes:** 과거에는 개발자가 수동으로 `useMemo`나 `useCallback`, `React.memo`를 삽입하여 불필요한 리렌더링을 최적화해야 했으나, 최근 안정화된 **React Compiler**는 빌드 타임에 코드와 데이터 흐름을 분석하여 이러한 메모이제이션 경계를 자동으로 삽입해 줍니다. 따라서 이제 수동 메모이제이션은 컴파일러의 자동 처리에 의존하게 되어 대부분 제거될 수 있으나, 효과적인 의존성 제어나 서드파티 라이브러리 통합 등 특수한 예외 상황의 '비상 탈출구(Escape Hatch)' 용도로만 제한적으로 남게 됩니다 [25, 67-72]. + +--- +*Last updated: 2026-04-25* \ No newline at end of file