클로드코드 /heapdump: AI가 자꾸 느려질 때 메모리 진단하기

작업을 오래 하다 보면 클로드코드가 처음보다 굼떠지는 순간이 옵니다. 입력 반응이 느려지고, 팬이 돌고, 뭔가 막힌 느낌이 들죠. 이럴 때 "왜 느려졌지?"를 감으로 추측하지 말고, 실제 메모리 상태를 떠서 들여다볼 수 있는 명령이 /heapdump입니다.

정의 (뭐냐면)

/heapdump는 클로드코드가 지금 메모리를 어떻게 쓰고 있는지 그 순간의 상태를 파일로 저장하는 명령입니다.

여기서 힙(heap)이란 프로그램이 실행 중에 데이터를 쌓아두는 메모리 공간을 말합니다. 덤프(dump)는 그 공간의 내용을 통째로 떠서 파일로 내보내는 것을 뜻하고요. 그래서 힙덤프(heapdump)는 "지금 이 순간 메모리에 뭐가 얼마나 쌓여 있는지 찍은 스냅샷"이라고 보면 됩니다.

사진을 찍어두면 나중에 천천히 들여다볼 수 있듯이, 메모리 스냅샷을 떠두면 무엇이 메모리를 잡아먹고 있는지 분석할 수 있습니다.

어떻게 쓰나 (난이도별)

기초 — 스냅샷 한 번 뜨기

클로드코드가 무거워졌다 싶을 때 그냥 입력하면 됩니다.

/heapdump

이렇게 하면 현재 메모리 상태가 스냅샷 파일로 저장됩니다. 별다른 옵션 없이 한 줄이면 끝입니다.

응용 — 떠놓은 파일 분석하기

스냅샷을 저장하는 것 자체는 쉽지만, 그 파일을 읽는 건 별도 도구가 필요합니다. 힙 스냅샷은 보통 크롬 개발자 도구(Chrome DevTools)의 Memory 탭에서 열어볼 수 있는 형식으로 저장됩니다.

분석 흐름은 이렇습니다.

1. 느려진 시점에 /heapdump를 실행해 스냅샷을 저장합니다.
2. 저장된 파일 경로를 확인합니다(실행 후 화면에 경로가 표시됩니다).
3. 크롬 브라우저를 열고 개발자 도구(F12) → Memory 탭에서 그 파일을 불러옵니다.
4. 어떤 데이터가 메모리를 많이 차지하는지 목록으로 확인합니다.

심화 — 시점을 나눠서 비교하기

메모리 누수(memory leak, 안 쓰는 데이터가 계속 쌓여서 메모리가 새는 현상)를 의심한다면 스냅샷을 두 번 떠서 비교하는 게 효과적입니다.

/heapdump

작업을 시작한 직후에 한 번, 그리고 한참 작업해서 느려진 뒤에 또 한 번 떠둡니다. 두 스냅샷을 비교하면 시간이 지나면서 비정상적으로 불어난 데이터가 무엇인지 드러납니다. 정상이라면 일정 수준에서 유지되어야 하는데, 계속 커지는 항목이 있다면 그게 범인일 가능성이 높습니다.

흔한 함정

• 스냅샷 파일은 생각보다 큽니다. 수십 MB에서 수백 MB까지 나올 수 있으니, 분석이 끝나면 지워주는 게 좋습니다.
• /heapdump는 진단 도구일 뿐, 메모리를 줄여주거나 문제를 고쳐주지는 않습니다. 원인을 찾는 첫 단계라고 생각하세요.
• 스냅샷을 뜨는 순간 잠깐 멈칫할 수 있습니다. 메모리를 통째로 읽어 파일로 쓰는 작업이라 그렇습니다. 정상이니 당황하지 마세요.

실전 사례

한 입문 개발자가 큰 프로젝트에서 클로드코드를 몇 시간 돌리다 보니 입력이 눈에 띄게 느려졌습니다. 재시작하면 잠깐 괜찮아지지만 또 느려지는 패턴이 반복됐죠. 이때 작업 초반과 느려진 후 두 번 /heapdump를 떠서 비교했더니, 특정 데이터가 계속 쌓이고 있는 걸 발견했습니다. 무거운 작업을 잘게 나눠서 세션을 새로 시작하는 습관으로 바꾸니 문제가 사라졌습니다.

이렇게 더 씁니다

메모리 진단이 필요할 정도라면, 그 전후로 함께 쓰면 좋은 명령들이 있습니다. 환경 자체에 이상이 없는지 점검하려면 /doctor로 클로드코드 설치 상태를 확인하고, 디버깅 정보를 더 보고 싶다면 /debug 계열 명령을 함께 살펴보세요. /heapdump로 "메모리가 문제다"라는 걸 확인했다면, 그다음은 작업 방식을 어떻게 가볍게 바꿀지 고민하는 단계로 넘어가면 됩니다.

정리

/heapdump는 클로드코드가 무거워졌을 때 메모리 상태를 사진처럼 떠두는 진단 명령입니다. 한 번 뜨면 현재 상태를, 두 번 떠서 비교하면 메모리가 새는지를 알 수 있습니다. 감으로 추측하지 말고 실제 데이터를 보고 판단하고 싶을 때 꺼내 쓰세요.

FAQ · 자주 묻는 질문

/heapdump를 실행하면 작업 중인 내용이 날아가거나 문제가 생기지 않나요?

아니요, 현재 메모리 상태를 파일로 저장만 하는 진단 명령이라 작업 내용에는 영향이 없습니다. 다만 메모리를 통째로 읽어 파일로 쓰는 작업이라 실행 순간 잠깐 멈칫할 수 있는데, 이는 정상이니 당황하지 않아도 됩니다.

입문자인데 스냅샷 파일 분석은 어떻게 시작하나요?

크롬 브라우저에서 개발자 도구(F12)를 열고 Memory 탭에서 저장된 파일을 불러오면 됩니다. 실행 후 화면에 표시되는 파일 경로를 확인한 뒤, 어떤 데이터가 메모리를 많이 차지하는지 목록으로 살펴보세요. 작업 직후와 느려진 뒤 두 번 떠서 비교하면 더 정확합니다.

스냅샷을 떠봐도 여전히 느리면 어떻게 하나요?

/heapdump는 원인을 찾는 진단 도구일 뿐 문제를 직접 고쳐주지는 않습니다. 환경 자체 점검은 /doctor로 하고, 특정 데이터가 계속 쌓이는 게 확인됐다면 무거운 작업을 잘게 나눠 세션을 새로 시작하는 습관으로 바꿔보세요. 분석이 끝난 대용량 스냅샷 파일은 지워주는 게 좋습니다.

기준: Claude Code v2.1.154 (2026.05)