Claude Code Jupyter 노트북 완전정리: AI와 함께하는 데이터 분석

Claude Code Jupyter 노트북 완전정리: AI와 함께하는 데이터 분석

데이터 분석을 하다가 "이 데이터프레임에서 이상치를 찾아줘", "이 차트를 개선해줘"라고 말하면 Claude가 직접 노트북 셀을 수정하고, 결과를 해석하고, 다음 분석 단계를 제안해줍니다. Claude Code의 Jupyter 노트북 통합 기능은 데이터 과학 워크플로우를 혁신합니다. 이 글에서는 NotebookEdit 도구부터 실전 데이터 분석까지 완전 정리합니다.

 

Claude Code Jupyter 노트북 완전정리

---

1. Jupyter 통합이란?

Claude가 노트북을 읽고 쓰고 해석

Claude Code는 Jupyter 노트북(.ipynb)을 네이티브로 지원합니다. 노트북의 JSON 구조를 직접 파싱해서 셀을 읽고, 수정하고, 출력(차트/테이블/에러)을 해석합니다.

[Claude Code] ←→ [Jupyter 노트북 .ipynb]
    │                 ├── 코드 셀 읽기/수정
    │                 ├── 마크다운 셀 읽기/수정
    │                 ├── 출력 해석 (차트, 테이블, 에러)
    │                 └── 새 셀 삽입/삭제
    │
    └── [VS Code / Jupyter Lab]
         └── 셀 실행 → 결과 확인

권장 워크플로우

Claude Code + VS Code 노트북을 나란히 열어두고 작업하는 것이 가장 효과적입니다.

1. Claude가 셀 수정 (NotebookEdit)
   ↓
2. 사용자가 VS Code에서 셀 실행
   ↓
3. Claude가 출력 결과 해석
   ↓
4. Claude가 다음 분석 단계 제안
   ↓
5. 반복

Claude가 이해하는 출력 유형

출력 유형	설명	예시
텍스트	print, DataFrame 요약	.head(), .describe()
차트	시각화 이미지	Matplotlib, Seaborn, Plotly
테이블	HTML 렌더링 테이블	pandas DataFrame
이미지	생성된 플롯/히트맵	상관관계, 분포도
에러	트레이스백, 예외	ImportError, KeyError

Claude는 차트 이미지를 비전 능력으로 직접 분석합니다. "이 차트에서 이상한 점이 있어?"라고 물어볼 수 있습니다.

Jupyter 통합이란?

---

2. NotebookEdit 도구

노트북 셀을 수정하는 핵심 도구

NotebookEdit는 Claude가 Jupyter 노트북의 셀을 수정하는 전용 도구입니다.

파라미터

파라미터	타입	필수	설명
notebook_path	문자열	✅	노트북의 절대 경로
cell_number	정수	✅	셀 인덱스 (0부터 시작)
new_source	문자열	조건부	셀의 새 내용
cell_type	문자열	조건부	code 또는 markdown
edit_mode	문자열	-	replace, insert, delete

3가지 편집 모드

1) Replace (교체) - 기본값

기존 셀의 내용을 새 내용으로 교체합니다.

NotebookEdit(
  notebook_path="/home/user/analysis.ipynb",
  cell_number=2,
  new_source="df.groupby('category')['revenue'].sum().plot(kind='bar')"
)

2) Insert (삽입)

지정한 위치에 새 셀을 삽입합니다. cell_type 필수입니다.

NotebookEdit(
  notebook_path="/home/user/analysis.ipynb",
  cell_number=3,
  edit_mode="insert",
  cell_type="markdown",
  new_source="## 카테고리별 매출 분석\n\n아래는 카테고리별 총 매출을 보여줍니다."
)

3) Delete (삭제)

지정한 셀을 삭제합니다. new_source가 필요 없습니다.

NotebookEdit(
  notebook_path="/home/user/analysis.ipynb",
  cell_number=5,
  edit_mode="delete"
)

주의사항

주의	설명
절대 경로 필수	상대 경로 사용 불가
0부터 인덱싱	첫 번째 셀은 cell_number=0
출력 초기화	코드 셀 교체 시 출력과 실행 카운트 자동 초기화
타입 변환	셀 타입 변경 시 타입별 필드 자동 처리

NotebookEdit 도구

---

3. 노트북 읽기와 해석

셀과 출력을 통째로 이해

Claude는 노트북을 읽을 때 전체 구조를 파악합니다.

{
  "cells": [
    {
      "cell_type": "markdown",
      "source": ["# 매출 분석 리포트"]
    },
    {
      "cell_type": "code",
      "source": ["import pandas as pd\ndf = pd.read_csv('sales.csv')"],
      "outputs": [...],
      "execution_count": 1
    }
  ]
}

Claude가 파악하는 것들

항목	설명
셀 순서	실행 순서와 데이터 흐름 이해
실행 카운트	어떤 셀이 실행되었는지 확인
출력 내용	텍스트, 차트, 테이블, 에러 해석
셀 간 의존성	변수가 어디서 정의되고 어디서 사용되는지
메타데이터	노트북 커널, 버전 정보

출력 해석 예시

사용자: "이 노트북의 3번 셀 결과를 분석해줘"

Claude:
  [셀 3 출력 읽기]
  이 차트를 분석하면:
  - 전자제품 카테고리의 매출이 가장 높습니다 (전체의 42%)
  - 의류 카테고리가 두 번째 (28%)
  - Q4에 뚜렷한 매출 급증이 보입니다 (연말 시즌 효과)
  - 가구 카테고리는 성장이 정체되어 있습니다

  다음 단계로 제안:
  - Q4 매출 급증의 원인 분석
  - 카테고리별 이익률 비교
  - 전년 동기 대비 성장률 계산

노트북 읽기와 해석

---

4. 셀 타입별 활용

코드 셀 (Code Cell)

# 실행 가능한 Python 코드
import pandas as pd
import matplotlib.pyplot as plt

df = pd.read_csv('sales.csv')
df.groupby('category')['revenue'].sum().plot(kind='bar')
plt.title('카테고리별 매출')
plt.show()

코드 셀을 수정하면 출력과 실행 카운트가 자동 초기화됩니다. 다시 실행해야 결과를 볼 수 있습니다.

마크다운 셀 (Markdown Cell)

## 2. 데이터 탐색

이 섹션에서는 데이터의 기본 구조를 살펴보고,
주요 통계량을 확인합니다.

- **데이터 기간**: 2024-01 ~ 2025-12
- **총 레코드**: 1,234,567건
- **카테고리**: 전자제품, 의류, 가구, 식품

마크다운 셀은 분석 과정을 문서화하는 데 필수적입니다. Claude가 분석 단계마다 자동으로 설명을 추가할 수 있습니다.

셀 타입별 특성

특성	코드 셀	마크다운 셀	Raw 셀
실행	가능	렌더링만	불가
출력	있음	없음	없음
실행 카운트	있음	없음	없음
수정 시	출력 초기화	즉시 반영	즉시 반영
용도	분석 로직	문서화	내보내기

 

셀 타입별 활용

---

5. 데이터 분석 워크플로우

5단계 분석 프로세스

1단계: 데이터 로딩

import pandas as pd

df = pd.read_csv('ecommerce_data.csv')
print(f"데이터 크기: {df.shape}")
df.head()

Claude가 데이터 구조를 파악하고 적절한 로딩 코드를 작성합니다.

2단계: 탐색적 분석 (EDA)

# 기본 통계
df.describe()

# 결측치 확인
df.isnull().sum()

# 카테고리 분포
df['category'].value_counts()

Claude가 결과를 해석하고 이상치나 패턴을 발견합니다.

3단계: 데이터 처리

# 결측치 처리
df['price'].fillna(df['price'].median(), inplace=True)

# 파생 변수 생성
df['revenue'] = df['quantity'] * df['price']
df['month'] = pd.to_datetime(df['date']).dt.month

4단계: 시각화

import matplotlib.pyplot as plt
import seaborn as sns

fig, axes = plt.subplots(1, 2, figsize=(14, 5))
df.groupby('category')['revenue'].sum().plot(kind='bar', ax=axes[0])
axes[0].set_title('카테고리별 매출')

df.groupby('month')['revenue'].sum().plot(ax=axes[1])
axes[1].set_title('월별 매출 추이')
plt.tight_layout()

Claude가 차트를 보고 인사이트를 도출합니다.

5단계: 인사이트 문서화

Claude가 마크다운 셀로 분석 결과를 자동 정리합니다.

## 주요 발견사항

1. **전자제품**이 전체 매출의 42%를 차지
2. **Q4 시즌 효과**로 10~12월 매출 35% 증가
3. **가구 카테고리**의 성장 정체 → 프로모션 필요
4. **평균 주문 금액** 45,000원 → 전년 대비 8% 증가

데이터 분석 워크플로우

---

6. 노트북 실행 방법

셀 실행의 3가지 방식

Claude는 직접 셀을 실행하지 않습니다. 다음 방법을 사용합니다.

방법 1: VS Code에서 수동 실행 (권장)

1. Claude가 NotebookEdit로 셀 수정
2. VS Code 노트북 에디터에서 Shift+Enter로 실행
3. Claude가 노트북 파일을 다시 읽어서 출력 확인
4. 결과 해석 후 다음 단계 제안

가장 자연스럽고 안전한 방식입니다.

방법 2: nbconvert로 일괄 실행

jupyter nbconvert --to notebook --execute analysis.ipynb --output result.ipynb

전체 노트북을 한 번에 실행합니다. CI/CD나 자동화에 적합합니다.

방법 3: Jupyter MCP 서버 연결

MCP 서버를 통해 Claude가 셀을 직접 실행하고 결과를 받을 수 있습니다.

// settings.json
{
  "mcpServers": {
    "jupyter": {
      "command": "jupyter-mcp-server",
      "args": ["--port", "8888"]
    }
  }
}

실행 후 Claude의 역할

셀 실행 완료
   ↓
Claude가 .ipynb 파일 다시 읽기
   ↓
출력 해석:
- 텍스트 출력 분석
- 차트 이미지 시각 분석 (Vision)
- 에러 메시지 디버깅
- 데이터 패턴 발견
   ↓
다음 분석 단계 제안

노트북 실행 방법

---

7. 실전 활용 시나리오

시나리오 1: 이커머스 데이터 분석

"ecommerce_data.csv를 분석하는 노트북을 만들어줘.
카테고리별 매출, 월별 추이, 고객 세그먼트를 분석해."

Claude가 완전한 분석 노트북을 생성합니다:

• 데이터 로딩 + 기본 탐색 셀
• 카테고리별 매출 시각화 셀
• 시계열 분석 셀
• 고객 세그먼트 분석 셀
• 마크다운 인사이트 문서화

시나리오 2: 머신러닝 실험

"여러 모델을 비교하는 ML 실험 노트북을 만들어줘.
Random Forest, XGBoost, LightGBM을 비교해."

• 데이터 전처리 셀
• 피처 엔지니어링 셀
• 모델 학습 + 교차 검증 셀
• 성능 비교 테이블 셀
• 최적 모델 선택 근거 문서화

시나리오 3: 노트북을 대시보드로 리팩토링

"이 분석 노트북을 Streamlit 대시보드로 변환해줘."

Claude가:

1. 노트북의 분석 로직 파악
2. 재사용 가능한 함수를 data.py, viz.py로 추출
3. Streamlit 앱 (app.py) 생성
4. 필터, 인터랙션 추가

시나리오 4: 리포트 노트북 자동 생성

"매월 실행하는 KPI 리포트 노트북을 만들어줘.
매출, DAU, 전환율, 이탈률을 포함해."

파라미터 셀(날짜 범위)만 바꾸면 자동으로 리포트가 생성되는 템플릿 노트북을 만듭니다.

시나리오 5: 기존 노트북 디버깅

"이 노트북의 5번 셀에서 에러가 나. 원인을 찾아서 수정해줘."

Claude가 에러 트레이스백을 읽고, 셀 간 의존성을 추적해서 근본 원인을 찾습니다.

실전 활용 시나리오

---

8. VS Code 연동

최적의 작업 환경 구성

┌──────────────────────┬──────────────────────┐
│   Claude Code 패널    │   VS Code 노트북      │
│                      │                      │
│  > "매출 차트를       │   [셀 1] import...   │
│    개선해줘"         │   [셀 2] df = ...    │
│                      │   [셀 3] ▶ 차트      │
│  Claude:             │   [출력] 📊 차트      │
│  셀 3을 수정했습니다  │                      │
│  Shift+Enter로       │                      │
│  실행해보세요        │                      │
└──────────────────────┴──────────────────────┘

VS Code 노트북의 장점

기능	설명
즉시 실행	Shift+Enter로 셀 즉시 실행
변수 탐색	변수 익스플로러로 데이터 확인
리치 렌더링	차트, DataFrame을 예쁘게 표시
디버거	코드 단계별 디버깅
IntelliSense	코드 자동 완성

Claude Code VS Code 확장에서의 사용

> 이 노트북의 시각화를 개선해줘. 색상을 통일하고 한글 폰트를 적용해.

VS Code 확장에서 바로 노트북 관련 작업을 요청할 수 있습니다.

VS Code 연동

---

9. 제한사항과 베스트 프랙티스

현재 제한사항

제한	설명
직접 실행 불가	Claude가 셀을 직접 실행할 수 없음
커널 제어 불가	Python 커널 상태 관리 불가
메타데이터 제한	셀 레벨 메타데이터(태그 등) 수정 불가
변수 상태	실행 중인 커널의 변수를 직접 조회 불가
대용량 출력	매우 큰 DataFrame이나 플롯은 잘릴 수 있음
실시간 업데이트	실행 후 파일을 다시 읽어야 결과 확인 가능
파일 형식	.ipynb만 지원 (.py, .Rmd 등 변환 필요)

베스트 프랙티스

원칙	설명
절대 경로	노트북 경로는 항상 절대 경로 사용
나란히 작업	Claude Code + VS Code 노트북 동시 열기
셀 단위 집중	각 셀은 하나의 작업만 수행
마크다운 문서화	분석 단계마다 마크다운 셀로 설명
Plan 모드 먼저	복잡한 분석은 Plan 모드로 계획 수립
출력 확인 후 진행	셀 실행 결과를 Claude에게 보여준 뒤 다음 단계
버전 관리	노트북을 git에 커밋해서 변경 이력 추적
모듈 분리	재사용 코드는 .py 파일로 추출

복잡한 분석을 위한 팁

복잡한 프로젝트:
  1. 단계별 노트북 분리 (01_loading, 02_eda, 03_modeling)
  2. 공통 함수는 Python 모듈로 추출
  3. 설정 셀에 파라미터 모으기
  4. 마크다운으로 가정과 제한 사항 기록

제한사항과 베스트 프랙티스

---

10. 자주 묻는 질문 (FAQ)

Q: Claude가 셀을 직접 실행할 수 있나요?
A: 기본적으로는 불가합니다. VS Code에서 수동 실행하거나, nbconvert로 일괄 실행하거나, Jupyter MCP 서버를 연결하면 가능합니다.

Q: 노트북 경로를 상대 경로로 지정할 수 있나요?
A: 아닙니다. NotebookEdit는 절대 경로만 받습니다. /home/user/project/analysis.ipynb처럼 전체 경로를 사용하세요.

Q: Claude가 차트를 이해할 수 있나요?
A: 네. Claude의 비전 능력으로 차트 이미지를 분석합니다. 트렌드, 이상치, 분포 패턴 등을 읽을 수 있습니다.

Q: R 노트북도 지원되나요?
A: .ipynb 형식이면 R 커널 노트북도 읽고 수정할 수 있습니다. 단, Claude는 Python에 가장 능숙합니다.

Q: 노트북을 새로 만들 수 있나요?
A: 네. Write 도구로 .ipynb JSON 구조를 생성하거나, NotebookEdit의 insert 모드로 빈 노트북에 셀을 추가할 수 있습니다.

Q: 대용량 데이터를 다룰 때 주의할 점은?
A: 대용량 DataFrame의 전체 출력은 컨텍스트를 소비합니다. .head(), .sample(), .describe() 등으로 요약해서 확인하세요.

Q: 기존 노트북의 분석을 이어갈 수 있나요?
A: 네. 기존 노트북을 읽어서 분석 맥락을 이해한 뒤, 새로운 셀을 추가하거나 기존 셀을 수정할 수 있습니다.

---

 

면책 조항: 이 글은 정보 제공 목적으로 작성되었습니다. Claude Code의 기능과 요금은 Anthropic의 정책에 따라 변경될 수 있으며, 최신 정보는 공식 문서를 확인해 주세요.