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

기준: Claude Code v2.1.154 (2026.05)