松尾研究所テックブログ
🗒️

AI-FriendlyなNotebookを作ろう。次世代のNotebook環境について

508shuto
に公開
Python
VS Code
jupyter
marimo
tech

はじめに

株式会社松尾研究所のごうやです。

CursorやClaude CodeなどのAIコーディングツールでJupyter Notebookを編集しようとして、こんな経験はありませんか？

  • 「セルを追加して」と指示したのに、JSONの構造がおかしくなる
  • コードの一部を修正しただけなのに、大量の差分が発生する
  • AIが提案したコードを適用すると、なぜかNotebookが壊れる

Jupyter Notebook（.ipynbファイル）は内部的にJSON形式で保存されるため、AIツールとの相性が良くありません。本記事では、この問題を解決する.pyベースのNotebook環境「marimo」を紹介します。

なぜ.ipynbはAIツールと相性が悪いのか？

Jupyter Notebookは、見た目はシンプルなセルの集まりですが、内部的にはJSON形式で保存されています。

// 実際のファイル（.ipynb）の中身
{
  "cells": [{
    "cell_type": "code",
    "source": ["print(\"hello world!\")"],
    "outputs": [{"text": ["hello world!\n"]}],
    "execution_count": 1,
    "metadata": {}
  }],
  "metadata": { /* カーネル情報、バージョンなど */ }
}

この構造が、AIツールでの編集を難しくしています。

主な問題点

  1. JSON構造による差分の複雑さ
    コードを1行変更しただけでも、JSON全体が変更されたように見えます。AIが「この行を修正して」と指示されても、セル配列のインデックスやネストした構造を正確に操作する必要があり、エラーが発生しやすくなります。

  2. 実行結果の混在
    セルの出力（画像、テーブル、エラーメッセージなど）がファイルに埋め込まれるため、コード本体とは無関係なノイズが大量に含まれます。AIがファイルを解析する際、本質的なコード変更と出力の違いを区別しにくくなります。

  3. 行単位編集の困難さ
    通常の.pyファイルなら「15行目を修正」で済むところ、.ipynbでは「cells[2].source[3]を修正」のような複雑な参照が必要です。AIツールは行ベースの編集を前提としているため、この構造との相性が良くありません。

解決策: marimo

marimoは、.pyファイルとして扱えるNotebook環境です。Jupyter Notebookと同様のインタラクティブな開発体験を提供しながら、内部的には純粋なPythonファイルとして保存されます。

pip install marimo
marimo tutorial intro

上記コマンドでチュートリアルを開始でき、ブラウザ上でmarimoのUIが立ち上がります。

実際に使ってみた

チュートリアルを試してみたところ、リアクティブな実行とインタラクティブなUIが印象的でした。セルを変更すると依存するセルが自動で再実行され、それでいて.pyファイルとして扱える点が非常に良いと感じました。

以下、marimoの主な特徴を紹介します。

主な特徴

1. AIツールで編集しやすい

marimoは.pyファイルなので、通常のPythonコードと同じようにAIツールで編集できます。

import marimo

__generated_with = "0.17.3"
app = marimo.App()

@app.cell
def _():
    import numpy as np
    import matplotlib.pyplot as plt
    return np, plt

@app.cell
def _(np, plt):
    x = np.linspace(0, 2*np.pi, 100)
    plt.plot(x, np.sin(x))
    return x,

このように、セルは@app.cellデコレータで定義された関数として表現されます。CursorやClaude Codeで「セルを追加して」「この関数を修正して」と指示すれば、JSON操作なしで直接編集できます。

実際にCursorで試したところ、通常のPythonファイルと同じ感覚でコード補完や修正提案が受けられました。

2. リアクティブ実行

セルを変更すると、依存するセルが自動的に再実行されます。Excelのような挙動で、「上から順に実行し直す」操作が不要です。

Jupyterでありがちな「削除したセルの変数がまだ残ってる」問題も解消されます。セルを削除すれば、その変数も自動的に削除され、依存セルも更新されます。

また、同じnotebook上で同じ変数名を再定義しようとするとエラーが表示されるため、意図しない値の上書きを防げるのも良い点です。


UIでスライダーを変化させるとインタラクティブに🍃の数が変化


FalseからTrueに変数を変えて実行したと同時に実行済みのセルの表示が変化

3. Git-friendly & 複数の実行形態

純粋な.pyファイルなので、通常のdiffやマージコンフリクトの解決が可能です。チーム開発での扱いやすさが向上します。

さらに、同じファイルを複数の形態で実行できます：

  • Notebookとして: marimo edit notebook.pyで対話的に開発
  • スクリプトとして: python notebook.pyで一括実行
  • Webアプリとして: marimo run notebook.pyでブラウザ上でデプロイ

スライダーやドロップダウンなどのインタラクティブな要素も標準搭載されており、Jupyter Widgetと異なり自動で同期されます。

既存NotebookからMarimoへの移行

既存の.ipynbファイルをmarimoに移行する手順を紹介します。

1. ipynb → py変換

marimo convertコマンドで簡単に変換できます：

# 既存のNotebookを変換
marimo convert notebook.ipynb -o notebook.py

# 変換されたファイルを開く
marimo edit notebook.py

変換後のファイルは以下のような構造になります：

import marimo

__generated_with = "0.17.3"
app = marimo.App()

@app.cell
def _():
    print("hello")
    print("world!")
    return

if __name__ == "__main__":
    app.run()

各セルが@app.cellデコレータ付きの関数として表現されるため、CursorやClaude Codeで通常のPythonファイルと同じように編集可能です。

2. VSCodeでの利用

VSCodeで開発する場合は、marimoの拡張機能が利用できます：

  1. marimo extensionをインストール
  2. .pyファイルを開く
  3. コマンドパレット（Cmd+Shift+P）からmarimo: Open as marimo notebookを実行

Jupyter Notebookと同様、VSCode上でインタラクティブに動作確認できます。

Python Interactive Window (VSCode)

VSCode限定ですが、もう一つ.ipynbファイルをAIフレンドリーに使う方法を紹介します。

Python Interactive WindowはVSCodeの機能で、.pyファイルに# %%を追加するだけでコードセルを定義でき、notebookのように実行できるようになります。

利用するには以下の拡張機能が必要です：

  • Python拡張機能（ms-python.python）
  • Jupyter拡張機能（ms-toolsai.jupyter）

VSCodeを使っている方は、こちらでも簡単に.pyファイルでnotebookのようにグラフ表示などをすることができるのでおすすめです。
marimoもモダンで開発しやすそうですが、個人的には、拡張機能を追加するだけで、ささっとグラフを生成してHTMLで共有するなどができるこちらでも手軽で十分な気がしました。

まとめ

今回、AIフレンドリーにNotebookを作成するために、marimoとPython Interactive Windowを紹介しました。

.ipynbも少しずつAIコーディングツールで編集可能になってきてはいますが、動作が不安定なところもあります。Notebookで試行錯誤をする利点をAIで最大限に活かすために、紹介したツールが役立つことを期待しています。

松尾研究所テックブログ
松尾研究所テックブログ

株式会社松尾研究所のテックブログです。

Discussion