P2-10.3 노트북을 재실행 가능한 기록으로 정리하기¶

Section ID: P2-10.3 Version: v2026.07.23

P2-10.1에서는 노트북(notebook)을 코드, 설명, 출력이 함께 있는 계산 문서로 봤습니다. P2-10.2에서는 Jupyter, Colab, 로컬 실행의 차이를 실행 위치와 파일 접근 관점에서 구분했습니다.

이제 한 단계 더 들어갑니다. 노트북은 학습 기록으로 유용하지만, 셀을 여러 번 실행하다 보면 문서에 보이는 순서와 실제 실행 상태가 달라질 수 있습니다. 그래서 노트북은 “읽기 좋은 문서”이면서 동시에 “다시 실행 가능한 기록(reproducible record)”으로 정리해야 합니다.

여기서는 재실행 가능한 기록(reproducible record), 실행 순서(execution order), 숨은 상태(hidden state), 런타임 상태(runtime state)의 기본 구분을 설명합니다. 노트북(notebook)과 셀 구조의 대표 설명은 P2-10.1에, 실행 위치 차이는 P2-10.2에, 재현성(reproducibility)의 대표 설명은 P2-7.5와 개념사전에 두고, 여기서는 그 기록을 다시 믿을 수 있게 정리하는 기준에 집중합니다.

Part 2 흐름에서 보면 Chapter 7은 어디서 실행하나, Chapter 8~9는 무엇을 어떤 문장으로 적나, Chapter 10은 그 실행과 출력을 어떻게 다시 읽을 수 있게 남기나를 다룹니다. 이 기준이 서야 바로 뒤 Chapter 11~14도 새 도구 이름 목록이 아니라 노트북 안에서 배열을 계산하고, 표를 읽고, 그래프로 확인하고, Git으로 기록을 남기는 준비 흐름으로 읽힙니다.

이 절은 노트북 꾸미기 팁보다, 실행 결과를 다시 믿을 수 있는 기록으로 정리하는 기준에 초점을 둡니다. 앞 절에서 노트북이 무엇이고 어디서 실행되는지 봤다면, 여기서는 그 노트북이 나중에도 다시 실행되고 다시 설명될 수 있으려면 무엇을 남겨야 하는지를 봅니다. 이렇게 읽으면 Chapter 11~14의 도구들도 새 기능보다 계산과 해석을 다시 확인하는 기록 흐름 안에서 읽기 쉬워집니다.

핵심 기준: 노트북을 재실행 가능한 기록으로 정리하기¶

• 노트북을 다시 실행 가능한 학습 기록으로 정리해야 하는 이유를 설명할 수 있습니다.
• 실행 순서(execution order)와 숨은 상태(hidden state)가 노트북 결과를 헷갈리게 만들 수 있음을 설명할 수 있습니다.
• 노트북 앞부분에 환경, 패키지, 데이터 준비 셀을 두는 이유를 설명할 수 있습니다.
• Colab 공유에서 노트북 내용과 런타임 상태가 다를 수 있음을 설명할 수 있습니다.
• 노트북에서 검증한 코드를 함수와 스크립트(script)로 분리해야 하는 시점을 설명할 수 있습니다.

먼저 붙잡을 기준¶

이 절에서 가장 먼저 붙잡아야 할 기준은 좋은 노트북은 읽기 좋은 문서이면서 다시 실행 가능한 기록이라는 점입니다.

즉 노트북은 코드가 있다보다 다시 실행해도 같은 흐름이 남는가를 기준으로 읽어야 합니다.

세 가지 기준¶

노트북은 문서이면서 실행 기록이다¶

Jupyter Notebook 파일은 .ipynb 확장자를 가진 JSON 기반 문서입니다. nbformat 문서는 노트북이 셀(cell) 목록과 메타데이터(metadata)를 포함하고, 각 셀이 입력과 출력을 가질 수 있다고 설명합니다. Jupyter 아키텍처 문서도 노트북을 코드, 출력, 마크다운 노트가 함께 저장되는 문서로 설명합니다.

여기서는 이 구조를 이렇게 이해합니다.

flowchart TB
  A["노트북 파일<br/>.ipynb 문서"]
  B["마크다운 셀<br/>질문과 설명"]
  C["코드 셀<br/>Python 코드"]
  D["출력<br/>값, 표, 차트, 오류"]
  E["런타임 상태<br/>변수와 import된 패키지"]

  A --> B
  A --> C
  C --> D
  C -. "실행 중에 만들어짐" .-> E

여기서 중요한 점은 파일에 저장된 내용과 실행 중인 상태가 같지 않다는 것입니다.

노트북 파일에는 코드와 일부 출력이 남을 수 있습니다. 하지만 변수(variable), import된 패키지, 임시 파일, 메모리 상태는 실행 중인 런타임(runtime)에 있습니다. 런타임을 다시 시작하면 그 상태는 사라질 수 있습니다.

그래서 노트북은 저장만 해서는 충분하지 않습니다. 저장된 노트북이 나중에 다시 실행되는지도 확인해야 합니다.

위에서 아래로 실행되는 흐름을 만든다¶

좋은 학습용 노트북은 위에서 아래로 읽고 실행할 수 있어야 합니다.

다음 흐름을 기본으로 삼을 수 있습니다.

flowchart TB
  A["1. 목적<br/>무엇을 확인할 노트북인가"]
  B["2. 설정<br/>import와 옵션"]
  C["3. 데이터 준비<br/>작은 예제나 파일 불러오기"]
  D["4. 계산<br/>한 번에 한 아이디어씩 실행"]
  E["5. 출력<br/>값, 표, 차트 확인"]
  F["6. 해석<br/>무엇이 어떻게 바뀌었는가"]
  G["7. 다음 단계<br/>이후에 무엇을 더 볼 것인가"]

  A --> B --> C --> D --> E --> F --> G

이 구조는 형식이 아니라 사고 순서입니다.

먼저 무엇을 확인하려는지 적습니다. 그다음 필요한 패키지를 불러오고, 데이터를 준비하고, 계산을 실행합니다. 결과를 본 뒤에는 해석을 적습니다.

이 순서가 무너지면 나중에 노트북을 다시 열었을 때 “왜 이 계산을 했는지”, “어떤 데이터로 실행했는지”, “결과가 어떤 의미인지”를 잃기 쉽습니다.

첫 셀에는 목적을 적는다¶

노트북의 첫 부분에는 코드보다 목적을 먼저 둡니다.

예를 들어 이 노트북은 작은 점수 데이터에서 평균(mean)과 분산(variance)을 계산해 보고, 데이터의 중심과 퍼짐이 어떻게 다른지 확인한다처럼 시작할 수 있습니다.

이 한 문장은 나중에 매우 중요합니다. 노트북은 셀을 추가하다 보면 금방 길어집니다. 목적이 없으면 실험이 흩어지고, 결과가 무엇을 설명하는지 흐려집니다.

목적 셀에는 다음 내용을 짧게 적습니다.

노트북도 Section과 비슷합니다. 하나의 노트북은 가능하면 하나의 중심 질문을 가져야 합니다.

패키지와 설정은 앞쪽에 모은다¶

노트북 중간중간에 import가 흩어져 있으면 나중에 다시 실행할 때 어떤 패키지가 필요한지 찾기 어렵습니다.

좋은 습관은 앞부분에 setup 셀을 두는 것입니다.

문제 상황: 노트북 앞부분에서 어떤 패키지를 쓰는지 한 번에 드러내고 싶습니다. 입력(input): numpy, pandas, matplotlib import 코드입니다. 기대 출력(output): 출력은 없지만 뒤 셀에서 필요한 패키지 이름들이 준비됩니다. 확인할 개념: import를 앞쪽에 모아 두면 노트북 재실행과 의존성 파악이 쉬워집니다.

1
2
3
4

# 재실행 가능한 노트북을 위해 설정, 데이터, 결과, 실험값을 분리해 기록하는 예제입니다.
import numpy as np
import pandas as pd
import matplotlib.pyplot as plt

이 셀은 “이 노트북이 어떤 도구를 쓰는가”를 보여 줍니다.

Colab에서는 패키지를 설치하는 셀도 앞쪽에 둡니다.

문제 상황: 공유받은 Colab 노트북에서 필요한 패키지를 먼저 설치하게 하고 싶습니다. 입력(input): numpy, pandas, matplotlib 설치를 위한 %pip 명령입니다. 기대 출력(output): 현재 커널에 필요한 패키지가 설치됩니다. 확인할 개념: 패키지 설치 셀을 앞에 두면 다른 사람이 같은 런타임 준비를 더 쉽게 따라갈 수 있습니다.

1
2

# 재실행 가능한 노트북을 위해 설정, 데이터, 결과, 실험값을 분리해 기록하는 예제입니다.
%pip install numpy pandas matplotlib

Colab이나 Jupyter에서 !pip install ...을 보는 경우도 많습니다. !는 노트북 셀에서 셸(shell) 명령을 실행하겠다는 뜻으로 쓰입니다. 다만 Python 패키지 설치에는 %pip 같은 IPython 매직 명령(magic command)이 현재 실행 중인 커널(kernel)과 더 잘 맞는 경우가 있어, 여기서는 가능한 한 %pip 형태를 우선 소개합니다.

이 대목은 설치법 자체보다, 패키지 설치와 import가 노트북 앞쪽에 있어야 다른 사람이 다시 실행할 때 필요한 준비를 알 수 있다는 점이 중요합니다.

데이터 준비 셀을 분명히 둔다¶

노트북 실습이 실패하는 흔한 이유 중 하나는 파일 경로(path)입니다.

로컬 PC에서는 다음 경로가 있을 수 있습니다.

문제 상황: 같은 노트북이라도 실행 환경에 따라 파일 경로가 달라질 수 있음을 가장 단순한 문자열 예시로 보고 싶습니다. 입력(input): 로컬 프로젝트 기준의 CSV 파일 경로 문자열입니다. 기대 출력(output): 출력은 없지만 코드가 어떤 파일 위치를 기대하는지 드러납니다. 확인할 개념: 재실행 가능한 노트북은 파일 경로와 데이터 위치를 코드 안에 분명히 남겨야 한다는 점을 봅니다.

1
2

# 재실행 가능한 노트북을 위해 설정, 데이터, 결과, 실험값을 분리해 기록하는 예제입니다.
data_path = "data/scores.csv"

하지만 Colab에서는 같은 파일이 없을 수 있습니다. 파일을 업로드했는지, Google Drive에 연결했는지, GitHub에서 내려받았는지에 따라 경로가 달라집니다.

그래서 데이터 준비 셀에는 다음 중 하나가 분명히 보여야 합니다.

여기서는 가능하면 작은 예제 데이터를 코드 안에 직접 두는 편이 좋습니다.

문제 상황: 파일 경로 문제 없이 개념 자체에 집중하려고 작은 예제 데이터를 코드에 직접 적습니다. 입력(input): 다섯 개 점수를 담은 리스트입니다. 기대 출력(output): 출력은 없지만 이후 셀에서 바로 사용할 데이터가 준비됩니다. 확인할 개념: 학습 초기에는 파일보다 코드 안의 작은 데이터가 재실행과 이해에 유리하다는 점을 봅니다.

1
2

# 재실행 가능한 노트북을 위해 설정, 데이터, 결과, 실험값을 분리해 기록하는 예제입니다.
scores = [82, 75, 45, 90, 61]

이 방식은 실제 프로젝트에는 부족할 수 있지만, 개념 학습에는 좋습니다. 파일 문제 없이 평균, 분산, 표본, 오차 같은 개념에 집중할 수 있기 때문입니다.

출력은 남기되, 해석도 함께 남긴다¶

노트북은 출력(output)을 저장할 수 있습니다. 하지만 출력만 남기면 학습 기록으로 충분하지 않습니다.

예를 들어 다음 출력이 있다고 가정합니다.

문제 상황: 숫자 하나만 저장된 출력이 나중에 왜 해석하기 어려운지 보고 싶습니다. 입력(input): 셀 출력으로 남은 단일 숫자 67.3입니다. 기대 출력(output): 평균인지 손실인지 맥락 없는 숫자만 보입니다. 확인할 개념: 출력은 값만 남기지 말고 바로 아래 해석과 함께 남겨야 한다는 점을 봅니다.

1
2

# 재실행 가능한 노트북을 위해 설정, 데이터, 결과, 실험값을 분리해 기록하는 예제입니다.
67.3

나중에 보면 이 숫자가 평균인지, 정확도인지, 손실인지 알기 어렵습니다.

그래서 출력 바로 아래에는 평균은 67.3이다. 하지만 45처럼 낮은 값이 포함되어 있으므로 평균만으로 전체 분포를 설명하기 어렵다처럼 짧은 해석을 둡니다.

이 한 문장이 학습 기록의 품질을 바꿉니다. 노트북은 코드를 모아 둔 파일이 아니라, 계산 결과를 해석한 기록이어야 합니다.

셀 실행 순서가 결과를 바꿀 수 있다¶

노트북은 셀을 자유롭게 실행할 수 있습니다. 이 장점은 동시에 위험입니다.

다음 상황을 생각해 봅니다. 한 셀에서 하이퍼파라미터 값을 먼저 정하고, 나중에 아래 셀에서 같은 이름을 다시 바꾸면 런타임의 현재 값은 마지막으로 실행한 셀에 따라 달라집니다.

문제 상황: 같은 변수 이름이 여러 셀에서 다시 정의될 때 현재 런타임 값이 어떻게 바뀌는지 확인하고 싶습니다. 입력(input): learning_rate = 0.1과 learning_rate = 0.01. 기대 출력(output): 처음 값과 나중 값이 순서대로 출력됩니다. 확인할 개념: 노트북의 변수 상태는 문서에 보이는 코드보다 실제 실행 순서에 더 직접적으로 영향을 받습니다.

1
2
3
4
5
6

# 재실행 가능한 노트북을 위해 설정, 데이터, 결과, 실험값을 분리해 기록하는 예제입니다.
learning_rate = 0.1
print("first value:", learning_rate)

learning_rate = 0.01
print("later value:", learning_rate)

문서에는 위에서 아래로 두 값이 보이지만, 실제 런타임에서는 마지막으로 실행한 셀의 값이 남습니다. 만약 아래쪽 변경 셀을 먼저 실행하고 위쪽 설정 셀을 나중에 실행했다면 결과는 다시 달라질 수 있습니다.

따라서 중요한 노트북은 다음처럼 확인합니다.

1. 런타임을 다시 시작한다.
2. 첫 셀부터 마지막 셀까지 순서대로 실행한다.
3. 오류가 나는 셀이 없는지 확인한다.
4. 출력이 설명과 맞는지 확인한다.
5. 불필요한 임시 셀을 정리한다.

이 과정을 거치면 노트북이 “내 컴퓨터에서 우연히 돌아간 기록”이 아니라 “다시 실행할 수 있는 기록”에 가까워집니다.

이 점검 순서를 더 짧게 다시 적으면:

랜덤성은 고정하거나 설명한다¶

AI와 통계 실습에서는 랜덤(random) 요소가 자주 등장합니다. 표본을 뽑거나, 데이터를 섞거나, 모델의 초기값을 정할 때 결과가 달라질 수 있습니다.

여기서는 랜덤성이 있는지 먼저 설명하는 것만으로도 출발점이 됩니다.

문제 상황: 같은 무작위 추출을 다시 확인할 수 있도록 seed를 고정한 예제를 보고 싶습니다. 입력(input): seed가 42인 난수 생성기와 다섯 값 중 세 개를 뽑는 코드입니다. 기대 출력(output): 선택된 표본 리스트가 재현 가능한 방식으로 출력됩니다. 확인할 개념: 랜덤 실습에서는 seed를 남기면 같은 결과 흐름을 다시 확인하기 쉬워집니다.

1
2
3
4

# 재실행 가능한 노트북을 위해 설정, 데이터, 결과, 실험값을 분리해 기록하는 예제입니다.
rng = np.random.default_rng(seed=42)
sample = rng.choice([10, 20, 30, 40, 50], size=3, replace=False)
sample

여기서 seed는 같은 난수 흐름을 다시 만들기 위한 시작값으로 볼 수 있습니다. 모든 실습에서 seed를 반드시 고정해야 하는 것은 아니지만, 같은 결과를 다시 보고 싶다면 seed를 남기는 것이 좋습니다.

주의할 점은 seed가 모든 재현성 문제를 해결하지는 않는다는 것입니다. 패키지 버전, 실행 환경, 하드웨어, 병렬 처리 방식에 따라 결과가 달라질 수도 있습니다. 이 절에서는 그 세부까지 깊게 들어가지 않습니다.

Colab 공유는 노트북 공유와 런타임 공유가 다르다¶

Colab FAQ는 노트북을 공유하면 텍스트, 코드, 출력, 댓글 같은 노트북 내용은 공유될 수 있지만, 가상 머신(virtual machine), 런타임 파일, 설치한 라이브러리는 공유되지 않는다고 설명합니다.

따라서 Colab 노트북을 공유할 때는 다음을 확인해야 합니다.

이 점은 책의 예제 노트북을 만들 때도 중요합니다. 독자가 링크를 열었을 때 코드만 보이는 것이 아니라, 무엇을 먼저 실행해야 하는지 알 수 있어야 합니다.

노트북에서 스크립트로 옮기는 기준¶

노트북에서 시작한 코드는 시간이 지나면 길어집니다. 어느 순간에는 .py 스크립트로 옮기는 편이 낫습니다.

다음 신호가 보이면 분리를 검토합니다.

흐름은 다음처럼 잡을 수 있습니다.

flowchart TD
  A["Notebook exploration<br/>try small ideas"]
  B["Function<br/>name repeated logic"]
  C["Script file<br/>run the same steps"]
  D["Module<br/>reuse from notebooks"]

  A --> B --> C --> D

여기서는 처음부터 패키지 구조를 만들라고 요구하지 않습니다. 먼저 노트북에서 이해하고, 반복되는 코드가 보이면 함수로 묶고, 재사용이 필요해지면 파일로 분리합니다.

학습용 노트북의 최소 템플릿¶

학습용 노트북을 만들 때 다음 흐름을 기본 템플릿으로 사용할 수 있습니다.

이 템플릿은 형식이 아니라 점검표입니다. 노트북이 길어질수록 “목적, 환경, 데이터, 계산, 출력, 해석”이 모두 남아 있는지 확인합니다.

Part 2의 다음 장으로 넘어가기 전에는 세 가지만 점검합니다. 노트북이 위에서 아래로 다시 실행될 수 있는지, 패키지와 데이터와 출력 해석이 앞쪽 셀 근처에 남아 있는지, 반복되는 코드를 나중에 함수와 .py 파일로 옮길 준비가 되었는지입니다. 이 기준이 서면 바로 뒤 Chapter 11~14는 새 도구 이름을 더 배우는 구간이 아니라, 정리된 노트북 안에서 배열을 계산하고, 표를 읽고, 그래프로 확인하고, Git으로 기록을 남기는 흐름으로 이어집니다.

즉, P2-10의 목표는 노트북 자체를 완전히 익히는 것이 아니라, Part 3 이전의 계산 기록을 다시 실행 가능한 형태로 남기는 기준을 세우는 데 있습니다.

사례 및 예시¶

사례 1. 오늘은 되는데 내일은 안 되는 노트북¶

한 학습자가 Colab에서 데이터 전처리 실습을 하며 셀을 이리저리 실행했다고 해 보겠습니다. 중간에 파일 업로드 셀을 실행했고, 다른 셀에서 변수 이름을 바꿨으며, 마지막에는 차트까지 잘 나왔습니다. 그날은 문서가 완성된 것처럼 보입니다.

하지만 다음 날 런타임을 다시 열고 위에서 아래로 실행해 보니 파일이 없고, 앞쪽 셀에는 없는 변수를 뒤쪽 셀이 참조하며, 저장된 출력은 현재 코드와 맞지 않을 수 있습니다. 사람은 어제는 됐는데 왜 지금은 안 되지라고 느끼지만, 실제로는 노트북이 읽기 좋은 문서로만 남고 재실행 가능한 기록으로는 정리되지 않은 상태입니다.

이 문제를 줄이려면 앞부분에 목적, 패키지 설치, import, 데이터 준비를 모아 두고, 계산과 해석을 순서대로 배치한 뒤, 마지막에 런타임을 다시 시작해서 처음부터 끝까지 실행해 봐야 합니다. 같은 결과가 다시 나오면 그제야 노트북이 우연히 돌아간 실험이 아니라 재현 가능한 기록에 가까워집니다.

이 사례는 노트북 정리의 핵심을 보여 줍니다. 재현성은 예쁜 문서를 만드는 일이 아니라, 숨은 상태를 줄이고 다른 날에도 같은 흐름으로 다시 확인할 수 있게 만드는 일입니다.

체크리스트¶

• 좋은 노트북을 다시 실행 가능한 기록으로 설명할 수 있는가?
• 숨은 상태(hidden state)가 왜 문제인지 말할 수 있는가?
• 노트북 앞쪽에 setup 셀과 데이터 준비 셀을 두는 이유를 설명할 수 있는가?
• 런타임 재시작 후 위에서 아래로 다시 실행해야 하는 이유를 말할 수 있는가?
• 노트북의 첫 부분에 목적과 범위가 있는가?
• 필요한 import와 패키지 설치 셀이 앞쪽에 있는가?
• 데이터 파일을 어디에서 가져오는지 설명되어 있는가?
• 셀을 위에서 아래로 다시 실행해도 오류가 없는가?
• 출력 아래에 해석이 남아 있는가?
• 랜덤성이 있는 경우 seed나 변동 가능성을 설명했는가?
• Colab 공유 시 파일, 패키지, 권한 문제가 생기지 않는지 확인했는가?
• 반복되는 코드를 함수나 .py 파일로 분리할 필요가 있는가?
• 노트북을 문서이면서 실행 기록으로 읽고, 같은 파일보다 같은 준비 흐름이 중요하다는 점을 설명할 수 있는가?

출처와 참고 자료¶

• Project Jupyter, Architecture, Jupyter Documentation 4.1.1 alpha, 확인 날짜: 2026-07-20. 노트북 문서가 코드, 출력, markdown notes를 함께 저장한다는 설명 확인에 사용했다.
• Project Jupyter, The Jupyter Notebook Format, nbformat 5.10 documentation, 확인 날짜: 2026-07-20. .ipynb 파일이 셀 목록과 메타데이터, 셀 입력·출력을 담는 JSON 기반 형식이라는 설명 확인에 사용했다.
• Google, Google Colab FAQ, Google Colab, 확인 날짜: 2026-07-20. Colab 공유에서 노트북 내용과 런타임 상태가 분리된다는 주의점을 확인하는 근거로 사용했다.