Claude CodeでJupyterノートブックを編集する仕組み

NotebookEditが編集するものと、編集しないもの

Claude Codeは、Jupyterノートブック(.ipynbファイル)の書き換えにNotebookEditという専用ツールを使います。通常のファイルを直すEditツールは文字列の完全一致で置換します。NotebookEditはそうではなく、セルをcell_idで指定して1回に1セルずつ変更します。ノートブックはセルの集合なので、文字列ではなく構造を直接操作する設計です。

動作モードは3つです。

読み込みはReadツールが担当します。.ipynbを開くと、コード・Markdown・グラフなどの出力を含む全セルが返るので、Claudeは実行結果を見ながら次の編集を決められます。100MBを超えるノートブックは読み込みが拒否され、セルの一部をシェルコマンドで読む方法がエラー文で案内されます。既存のノートブックを丸ごと書き換えるWriteツールは、新しめのモデルでも事前の読み込みが必須です。未読のまま書こうとすると、通常のファイルと違って失敗します。

ここで押さえておきたいのは、NotebookEditが書き換えるのはファイルの中身だけという点です。セルを実行するツールではありません。VS Codeの拡張を使っている場合に限り、mcp__ide__executeCodeというツールが、開いているノートブックのPythonカーネルでコードを実行します。このツールは毎回、実行前にVS Code側のQuick Pickで「Execute」か「Cancel」を選ばせます。Escで閉じたりCancelを選んだりすると、エラーがClaudeに返り、何も実行されません。開いているノートブックが無いとき、Jupyter拡張(ms-toolsai.jupyter)が入っていないとき、カーネルがPythonでないときは、そもそも実行を断ります。

つまり「セルを直す」と「セルを動かす」は別のツールで、承認の流れも別です。この承認はフックや許可リストとも別です。許可リストにmcp__ide__executeCodeを入れても、Claudeが実行を提案できるだけで、実際に走らせるかどうかはVS CodeのQuick Pickが決めます。フックからはこのツールがmcp__ide__executeCodeという名前で見えます。IDE連携が無い環境では、直したセルの結果を確かめるために、ノートブックを自分で実行し直すことになります。

セル単位で頼むときの指示の出し方

NotebookEditはClaudeが状況に応じて自分で呼ぶツールで、ユーザーがコマンドとして打つものではありません。位置と内容を自然な言葉で伝えれば、Claudeがcell_idを特定します。

notebooks/eda.ipynbの3番目のセルを、dropnaで欠損値を除去する処理に書き換えて

この依頼ならreplaceで書き換わります。セルを足したいときは「前処理のセルの後に可視化用のセルを追加して」と挿入位置の基準を、消したいときは「実験用に残っている2番目のセルを消して」と対象を1つに絞って伝えます。

cell_idを取り違えると別のセルの中身を上書きします。書き換える前にセルの番号か先頭行を示しておくと、取り違えを防げます。deleteは複数セルをまとめて頼むより、1つずつ指示したほうが対象を取り違えにくくなります。

Editツールは空白やインデントが1文字違うだけで失敗することがあります。タブインデントの編集が失敗する現象はその典型です。NotebookEditはcell_idで対象を決めるので、この種の不一致は起きません。通常ファイルを含む日常的な編集の工夫はClaude Codeの生産性を上げる小技12選にまとめています。

権限ルールを書いたのに効かないとき

ノートブックの編集を制御するルールは、見た目の直感と実際の判定がずれる箇所です。

無視されるルールを書くと、起動時に次の形の警告が出ます。以下は公式のエラーページに載っている文面で、Writeの例です。

Permission deny rule (.claude/settings.json): Write(docs/**) is not matched by file permission checks — only Edit(path) rules are. Use Edit(docs/**) instead (Edit rules cover all file-editing tools).

NotebookEdit(path)の場合も警告は同じ形で、ルール名の部分だけが変わります。警告はルールの出どころも括弧で示すので、どの設定ファイルを直せばよいかがわかります。--allowedToolsや--settingsの値、managed settingsに書いたルールも対象です。例外は、--allowedToolsで渡したGlobルールです。ただしパスを持たないNotebookEditだけの拒否ルールは警告の対象外で、ツール単位で効きます。

もう1つの落とし穴はRead拒否ルールです。通常のファイルでは、Readの拒否がEditとWriteの両方を止めます。NotebookEditはこの対象外です。ノートブックへの書き込みを一切禁じたいパスには、Editの拒否ルールを別に足します。この判定が効くのは、編集ではv2.1.208以降、書き込みではv2.1.228以降です。

Writeツールでノートブックを丸ごと上書きするときにも条件があります。新しいモデルは、通常のファイルなら未読でも上書きできる場合があります。ところがJupyterノートブックと、PARTIAL viewの通知が付いた部分読み込みのファイルは、どのモデルでも事前に読んでいなければ上書きできません。

ツールの利用可否を権限ルールではなく起動オプションで絞る方法もあります。手元のv2.1.287でclaude --helpを引くと、--toolsは次のように説明されます。

  --tools <tools...>                    Specify the list of available tools from
                                        the built-in set. Use "" to disable all
                                        tools, "default" to use all tools, or
                                        specify tool names (e.g.
                                        "Bash,Edit,Read").

組み込みツールのうち名前を挙げたものだけを使わせる指定なので、ノートブックを触らせたくないセッションではNotebookEditを含めない一覧を渡せます。

承認とモードの扱い、そしてバージョンごとの違い

NotebookEditは公式のツール一覧で、承認が必要なツール(Permission required: Yes)に分類されています。Manualモードでは書き換えのたびに確認が入ります。auto modeでは、確認の代わりに分類器が各操作を審査します。auto modeは、v2.1.283以降なら対話型のターミナルとVS Codeセッションの標準の開始モードです。それより前のバージョンではPro・Max・Teamプランに限られていました。どちらの場合も、対応モデルであることが条件です。

ノートブック編集まわりの挙動は、バージョンごとに少しずつ変わってきました。

CLAUDE_CODE_PERFORCE_MODEを1にした環境では、対象ファイルにオーナーの書き込みビットが無いと、Edit・Write・NotebookEditが失敗します。失敗時にはp4 edit <file>を促すヒントが付きます。Perforceは同期したファイルの書き込みビットを、p4 editで開くまで外しておくため、黙って上書きするのを防げます。ノートブックも例外ではなく、書き込めなかったときはまずファイルの属性を疑います。設定場所とClaudeに自分で開かせる運用はCLAUDE_CODE_PERFORCE_MODEの使い方にあります。

編集後に戻す、差分を確かめる

ノートブック編集も、ほかのファイル編集ツールと同じく自動で追跡されます。ターンを始めるプロンプトを送るたびにチェックポイントが作られ、/rewindで戻せます。スナップショットはセッションごとに直近100チェックポイント分が保持されます。古いチェックポイントを捨てると、どのチェックポイントからも参照されないスナップショットファイルが消えます。

セッションが最後にスナップショットを保存してからおよそ30日で、ファイルスナップショットは削除されます。それより古いチェックポイントに戻そうとすると、No files were restoredで失敗することがあります。保持期間はcleanupPeriodDaysで延ばせます。Bash経由の変更やサブエージェントの編集は復元に制限があり、詳しくはClaude Codeのチェックポイントの制限にあります。

差分を人が読むとき、生の.ipynbはJSONなので行単位のdiffが読みにくくなります。Jupyterのプロジェクトは、ノートブック専用の比較・マージツールとしてnbdimeを、形式の検証・変更にnbformatを、他形式への変換にnbconvertを提供しています。NotebookEditによる変更をGitで確認するとき、こうした専用ツールが助けになります。

まとめ

承認の設定を見直すときは、先にIDE連携の有無を確かめます。VS Codeを使っていなければmcp__ide__executeCodeは関わらず、対象はNotebookEditのEdit(path)ルールだけになります。