node-perf

name	node-perf
description	Node.js 성능 프로파일링 및 분석. --prof 플래그로 CPU 프로파일을 생성하고 병목 지점을 찾아 최적화를 제안합니다.
argument-hint	["URL"]
allowed-tools	Bash(yarn rolldown *), Bash(time yarn node --prof *), Bash(node --prof-process *), Bash(ls -t isolate-*.log *), Bash(rm isolate-*.log), Read, Glob, Task

Node.js Performance Profiling Skill

이 스킬은 Node.js --prof 플래그를 사용하여 성능을 측정하고 분석합니다.

실행 단계

Step 0: 사전 빌드

tsx 런타임 트랜스파일링 오버헤드를 제거하기 위해 rolldown으로 사전 빌드합니다:

yarn rolldown --dir dist --platform node scripts/cli.ts

• --dir dist: 출력 디렉토리
• --platform node: Node.js 환경 타겟
• 빌드 결과물은 dist/cli.js에 생성됩니다.

Step 1: 프로파일 데이터 생성

사전 빌드된 JS 파일로 프로파일링을 실행합니다:

time yarn node --prof dist/cli.js $0

• time: 전체 실행 시간 측정
• --prof: V8 프로파일링 활성화
• $0: 사용자가 제공한 URL 인자

Step 2: 프로파일 파일 찾기

가장 최근 생성된 isolate 로그 파일을 찾습니다:

ls -t isolate-*.log | head -1

Step 3: 프로파일 처리

프로파일을 사람이 읽을 수 있는 형태로 변환합니다:

node --prof-process <isolate-file> > /path/to/scratchpad/profile-result.txt

결과 파일은 scratchpad 디렉토리에 저장하여 프로젝트를 오염시키지 않습니다.

Step 4: Subagent로 분석 (중요)

반드시 Task 도구를 사용하여 subagent에게 분석을 위임합니다.

Task 도구 호출 시:

• subagent_type: "general-purpose"
• 프로파일 결과 파일 경로를 전달
• 다음 분석 항목을 요청:

Subagent 분석 요청 내용

1. 상위 시간 소비 함수 (>5% tick)
2. GC(Garbage Collection) 오버헤드
3. 라이브러리 vs 애플리케이션 코드 비율
4. 최적화 가능한 핫스팟
5. 구체적인 개선 제안

Step 5: 정리

분석이 완료되면 생성된 isolate 로그 파일을 삭제합니다:

rm isolate-*.log

출력 형식

Subagent의 분석 결과를 사용자에게 다음 형식으로 요약하여 전달합니다:

## 프로파일 분석 결과

### 주요 병목 지점
- ...

### GC 오버헤드
- ...

### 최적화 제안
1. ...
2. ...

에러 처리

• isolate 파일이 생성되지 않은 경우: 프로파일링 실행 실패 메시지 출력
• timeout 발생 시: 적절한 안내 메시지 출력
• node --prof-process 실패 시: 원본 로그 파일 내용 확인 시도