2026-08-19 기준 공식 문서를 바탕으로 작성되었으며, 2026-11-19 기준 공식 문서(costs / commands)를 통해 재확인했습니다. 확인 과정에서 변경된 사항은 본문에 명시하였습니다. Claude Code의 사양은 앞으로도 업데이트될 수 있습니다. 리포트 레이아웃이나 문구 역시 버전 및 실행 환경에 따라 달라질 수 있습니다.
claude --version
로 자신의 환경 버전을 확인하고, 최신 정보는 공식 문서를 통해 확인해 주십시오.
Claude Code의 /insights
은 토큰 양이 아니라 **어떻게 사용했는지(how you work)**를 리포트로 만드는 명령어입니다. 공식 문서에서 말하는 '사용된 토큰 수(how many tokens you've used)'가 아닌, '작업 방식(how you work)'에 대한 보고서입니다.
본문에서는 /insights가 무엇을 하는지, 무엇을 출력하는지, 어디에 저장되는지, 그리고 어떤 것이 대상에서 제외되는지를 공식 문서의 내용에 따라 정리합니다.
Claude Code 입력창에서:
- 인자나 플래그는 없습니다. 이 장치에 남아있는 직전 세션 기록을 분석하여 HTML 리포트를 작성합니다.
- 소비량보다는 작업 방식(프로젝트 분포, 사용 경향, 원활하지 않은 부분, 시도해 볼 기능)을 확인합니다.
- 한 번의 실행으로 미분석된 최대 200개의 세션을 처리할 수 있습니다. 극단적으로 짧은 세션은 건너뜁니다.
- 출력물은
~/.claude/usage-data/report.html입니다. 실행별 타임스탬프가 포함된 사본도 남으며, cleanupPeriodDays(기본값 30일)에 따라 삭제됩니다. - 다른 장치, claude.ai, 클라우드 세션은 대상에서 제외됩니다. 분석 자체도 토큰을 소비합니다.
- 이 장치에서 실행한 Claude Code의 세션 기록을 읽습니다.
- 일반적인 세션과 동일한 프로바이더와 계정으로 Claude가 분석을 수행합니다.
- HTML 리포트 형태로 작성하여 출력합니다.
'사용량 관련' 명령어는 여러 개가 있습니다. 역할은 다음과 같이 구분됩니다.
| 명령어 | 확인하는 내용 | 시간 축 |
|---|
/context | 현재 컨텍스트 창에 무엇이 로드되어 있는지 컬러 그리드로 시각화합니다. 컨텍스트를 차지하는 도구나 메모리 과부하 최적화 제안도 나옵니다. | 현재 |
/usage | 토큰 수, 모델별 비용, 지출 경향. Pro/Max/Ultra/Team/Enterprise의 경우, 플랜 사용량 바 외에 스킬(skill), 서브 에이전트(sub-agent), 플러그인(plugin), MCP 서버별 내역과 개선 제안도 표시됩니다(d / w로 직전 24시간 및 7일간 전환 가능). | 현재 세션 + 전체 세션 |
/cost | /usage의 별칭입니다. 내용은 동일합니다 (/stats 역시 별칭이며, 여기서는 Stats 탭에서 열립니다). | 위와 동일 |
/insights | 어떤 프로젝트에서 작업했는지, Claude Code를 어떻게 사용하고 있는지, 어디서 원활하지 않은지, 시도해 볼 기능 등을 확인합니다. | 직전 세션들 |
/context와 /usage가 '얼마나 사용했는가'에 답한다면, /insights는 '어떻게 사용했는가'에 답합니다.
공식 문서에 따르면, 리포트는 다음 4가지 포인트를 다룹니다.
| 항목 | 내용 |
|---|
| 어떤 프로젝트에서 작업하고 있는가 | 작업 대상의 분포 |
| ... | |
행동을 변화시킬 수 있는 재료는 세 번째 마찰점입니다. 요청이 오해되면 다시 해야 하는 과정(재작업)이 발생하며, 재작업은 추가적인 토큰과 시간을 소모합니다. 마찰점을 줄일수록 그만큼의 재작업이 줄어듭니다.
(이 인과관계는 공식적으로 명시된 것이 아니며, 필자가 정리한 내용입니다.)
- 한 번의 실행으로,
아직 분석하지 않은 최대 200개의 세션까지 처리합니다. -
극단적으로 짧은 세션은 건너뜁니다. - 세션이 제외된 경우, 리포트 헤더에 분석 개수와 총 개수가 함께 기재됩니다. 문서의 표시 예시는 다음과 같습니다.
기록이 대량으로 쌓인 상태에서 처음 실행할 경우, 한 번에 모두 처리하지 못할 수 있습니다. 괄호 안의 총 개수와 분석 개수를 비교하면 누락된 부분이 있는지 알 수 있습니다.
항목 | 사양
|---|---|
| 최신 보고서 | ~/.claude/usage-data/report.html |
...|
복사본이 남아 있기 때문에, 이전 보고서와 이번 보고서를 나란히 놓고 마찰점이 줄었는지 비교할 수 있습니다. 다만 30일 후에는 사라지므로, 장기간 추적하려면 보고서를 다른 곳에 보관해야 합니다.
/insights
은 로컬 세션 기록을 읽습니다. 다음 내용은 분석에 포함되지 않습니다.
| 제외 대상 | 참고 |
|---|
| 다른 기기의 세션 | 회사 Mac과 집의 Mac에서 번갈아 사용했다면, 각각 별도의 보고서가 생성됩니다. |
| ... | |
| 보고서는 **기기별(Machine-specific)**입니다. 여러 기기에서 작업하는 경우, 각 기기에서 실행하여 비교해야 합니다. | |
- 어떤 플랜이든, 어떤 제공업체(Provider)를 사용하든 실행할 수 있습니다.
- 분석은 일반 세션과 동일한 제공업체와 같은 계정을 통해 진행됩니다.
- 따라서 분석에 사용된 토큰은 플랜 할당량 또는 API 사용량에 계산됩니다.
대상은 '아직 분석하지 않은 세션'이므로, 두 번째 실행부터는 처리 건수가 줄어듭니다. 그럼에도 불구하고 토큰은 소모되므로, 생각날 때마다 실행하기보다는 중요한 지점(節目)에서 한 번씩 돌리는 것이 안전합니다 (필자의 정리입니다).
사양을 바탕으로 구성한 운영 가이드입니다 (필자의 정리입니다).
- 월말이나 스프린트 마감 시점에 매일 실행하는 것은 아닙니다. 어느 정도 세션이 쌓인 후에 추세를 파악할 수 있는
/insights를 실행하는 것이 의미가 있습니다.
- '어디서 잘 안 되는지'부터 읽습니다. 행동을 바꿀 수 있는 것은 마찰점(friction point)의 지적입니다.
- 지적된 내용을 CLAUDE.md나 Skill에 반영합니다. 같은 오해가 반복되고 있다면, 매번 설명하고 있다는 증거입니다. 프로젝트 공통 전제는 CLAUDE.md에, 특정 작업 절차는 Skill에 기록하세요.
- 다음 달 보고서로 효과를 확인합니다. 타임스탬프가 찍힌 복사본과 비교하여 지적된 마찰점이 줄어들었다면 개선이 효과를 보고 있는 것입니다.
CLAUDE.md는 매 세션마다 상시 로드됩니다. 공식 문서에서는 CLAUDE.md의 내용을 200줄 미만으로 유지하고, 특정 워크플로우에 필요한 상세 절차는 호출될 때만 로드되는 Skill 측으로 옮기는 것을 권장합니다. 모든 것을 CLAUDE.md에 추가하면, 그것 자체가 용량을 차지하기 시작합니다.
| 알고 싶은 것 | 사용할 명령어 |
|---|
| 무엇이 용량을 차지하는지 | /usage (또는 /cost) |
| 현재 컨텍스트에 무엇이 담겨 있는지 | /context |
| 왜 이런 방식으로 사용되는지 | /insights |
용량이 부족하다고 느낀다면, 먼저 /usage로 무엇이 차지하고 있는지 확인한 후, 그 위에 /insights로 사용 방식을 검토하는 것이 좋습니다. 이 두 단계를 거쳐 보는 것이 효율적이라고 생각합니다 (필자의 정리입니다).
※ 공식 문서에 기재된 내용(2026-08-19 시점)을 기반으로 구성했으며, 2026-11-19 시점의 동일 문서를 통해 교차 확인했습니다. 분석 건수(최대 200건)・표시 예시・저장 위치・cleanupPeriodDays (기본값 30일)・클라우드 세션 미지원・/cost가 /usage의 별칭인 것・CLAUDE.md를 200줄 미만으로 유지하는 권장 사항은, 교차 확인 시점에서도 동일한 기재였습니다. 실제 보고서 출력 예시는 포함되어 있지 않습니다.