[Claude Code 스킬] 주피터 노트북 편집(NotebookEdit) — .ipynb를 셀 단위로 수술하기 | DAKER 커뮤니티

무엇

NotebookEdit는 주피터 노트북(.ipynb)을 셀 하나 단위로 고치는 Claude Code 내장 도구입니다. 일반 파일용 Edit이 문자열을 찾아 바꾸는 것과 달리, cell_id로 칸을 지목해 그 셀만 교체·삽입·삭제합니다.

노트북은 겉보기엔 코드지만 실제로는 셀·출력·메타데이터가 층층이 든 JSON 서랍장입니다. 서랍장을 통째로 문자열 치환하면 따옴표 이스케이프와 출력이 함께 망가져 파일이 열리지 않습니다. 칸을 지목하는 방식은 그 사고를 구조적으로 막습니다.

언제 쓰나

분석 노트북의 특정 셀만 리팩터링할 때, 설명용 마크다운 셀을 끼워 넣을 때, 죽은 실험 셀을 지울 때, 에러 난 셀을 고칠 때입니다. Read가 .ipynb를 모든 셀 + 그 출력(코드·마크다운·시각화)까지 함께 돌려주기 때문에, 그래프가 이상한 셀을 그림째로 보고 곧바로 그 칸만 손보는 흐름이 특히 강합니다.

사용법

$ claude
> notebooks/eda.ipynb 읽고, 결측치 채우는 셀만 median으로 바꿔줘

# 실제 도구 호출 모양
Read(file_path="notebooks/eda.ipynb")          # cell_id 확인
NotebookEdit(notebook_path="notebooks/eda.ipynb",
             cell_id="b2",
             new_source="df = df.fillna(df.median())")

# 셀 추가(지목한 셀 다음) / 셀 삭제
NotebookEdit(..., cell_id="b2", edit_mode="insert",
             cell_type="markdown", new_source="## 결측치 처리")
NotebookEdit(..., cell_id="c3", edit_mode="delete")

# 권한: Edit 경로 규칙 한 줄이 NotebookEdit까지 덮는다
"allow": ["Edit(notebooks/**)"]

팁

1) 모드는 세 가지. replace(기본)·insert·delete. insert는 지목한 셀 다음에 들어가고 cell_type(code 또는 markdown)이 필수이며, cell_id를 비우면 노트북 맨 앞에 꽂힙니다.

2) 편집과 실행은 다른 손이다. NotebookEdit은 셀 내용만 바꾸므로 결과를 다시 보려면 Bash(jupyter nbconvert --execute)나 커널을 다루는 MCP 서버가 필요합니다. 계획(plan) 모드에서는 편집 도구가 잠겨 있으니 셀 수정은 모드를 빠져나온 뒤에.

출처

Tools reference — code.claude.com/docs/en/tools

Permissions — code.claude.com/docs/en/permissions

MCP 연결 — code.claude.com/docs/en/mcp