Claude CodeでJupyterノートブックを編集する仕組み
Claude CodeはNotebookEditツールでJupyterノートブックをセル単位に編集します。replace/insert/deleteの使い分けと権限ルールの注意点を扱います。
Claude CodeがJupyterノートブックを編集する仕組み
Claude CodeはJupyterノートブック(.ipynbファイル)専用の編集ツールとしてNotebookEditを持ちます。通常のファイルを書き換えるEditツールはold_stringとnew_stringの完全一致置換です。一方でNotebookEditはセルをcell_idで指定して操作する点が根本的に違います。ノートブックはセルという単位の集合体なので、文字列一致ではなく構造そのものを操作する設計になっています。
動作モードは3つです。
replace: 対象セルのソースを上書きします。モードを指定しない場合の既定です。insert: 対象セルの直後に新しいセルを追加します。cell_idを省略すると先頭に挿入され、追加するセルの種類をcodeかmarkdownで必ず指定します。delete: 対象セルをまるごと削除します。
読み込み側にも専用の挙動があります。Readツールでノートブックを開くと、コード・Markdown・グラフなどの出力を含むすべてのセルがまとめて返ります。グラフや画像を含む実行結果もそのまま見えるため、Claudeは出力を確認しながら次の編集判断ができます。ただし100MBを超えるノートブックは拒否され、セルの一部だけをシェルコマンドで読む方法がエラーメッセージ内で案内されます。数百セル規模の大きなノートブックを扱うときは、あらかじめ対象範囲を絞って伝えると、この制限に引っかかりにくくなります。
NotebookEditは公式のツール一覧でも承認が必要(Permission required: Yes)に分類されています。手動モードでは、作業ディレクトリ内のノートブックであっても書き換えのたびに承認を求められます。Pro・Max・Teamプランのauto modeでは、この可否判断を分類器が代わりに行うため、通常はプロンプトなしで進みます。
NotebookEditはセルを1回の呼び出しにつき1つずつ処理する仕組みです。ノートブック全体にまたがる大規模な一括変更を頼むと、対象セルの数と同じ回数だけツール呼び出しが発生します。数十セル規模のノートブックを丸ごと書き換えたいときは、対象セルの範囲をあらかじめ絞って伝えると、余計な呼び出しを減らせます。
セル単位の編集を指示する実践例
NotebookEditはClaudeが状況に応じて自律的に呼び出すツールで、ユーザーが直接コマンドとして打つものではありません。編集したいセルの位置や内容を自然な言葉で伝えるだけで、Claudeが対象セルのcell_idを特定してNotebookEditを呼び出します。
notebooks/eda.ipynbの3番目のセルを、dropnaで欠損値を除去する処理に書き換えてこのように対象セルの位置や処理内容を具体的に伝えるとreplaceモードで書き換わります。セルを増やしたいときは「前処理のセルの後に可視化用のセルを追加して」のように挿入位置を、削除したいときは「実験用に残っている2番目のセルを消して」のように対象を1つに絞って伝えると意図どおりに動きます。手動モードでは書き換え前に承認ダイアログが表示され、対象セルの現在の内容と変更後の内容を見比べてから許可できます。ノートブックやセルが一時的に読み込めない状態でも、なぜ内容を確認できないかが表示されるため、理由がわからないまま承認することはありません。
使い分け早見表
| モード | 主な用途 | 指示のコツ |
|---|---|---|
| replace | 主な用途既存セルのコードやテキストを書き換える | 指示のコツ対象セルの位置と変更後の処理を具体的に伝える |
| insert | 主な用途新しいセルを追加する(cell_typeが必須) | 指示のコツ挿入位置の直前・直後のセルを明示する |
| delete | 主な用途不要になったセルを取り除く | 指示のコツ削除対象を1つに絞って伝える(複数指定は誤削除の原因になる) |
insertには制約があります。cell_typeをcodeかmarkdownのどちらかで明示しないとリクエストが通りません。既定はreplaceですが、対象のcell_idを誤って別のセルに向けると意図しない内容を上書きしてしまうため、書き換え前にセル番号や内容を確認してから指示するのが安全です。deleteは対象を1つに絞れないと別のセルまで巻き込んで消える恐れがあり、複数セルを消したいときは1つずつ指示するほうが確実です。
権限ルールと承認まわりの落とし穴
NotebookEditはEdit・Writeと並ぶファイル編集ツールですが、権限ルールの書き方には独自の落とし穴があります。
NotebookEdit(path)ルールは参照されない: Claude Codeが実際にチェックするのはEdit(path)とRead(path)ルールだけです。NotebookEdit(notebooks/**)のようなルールは書けてしまいますが黙って無視され、v2.1.210以降は起動時に警告が表示されるようになりました。ノートブックの編集を制御したいときはEdit(notebooks/**)と書きます。Readの拒否ルールだけでは編集を止められない: 通常のファイルはRead拒否ルールがEditとWriteの両方をブロックしますが、NotebookEditはこの対象外です。ノートブックへの書き込みそのものを禁じたいときは、Editの拒否ルールを別途追加する必要があります。Edit(...)の許可ルールは同じパスへの読み取り権限も自動的に含みます。ノートブック編集を許可するためにRead(...)ルールを別途書く必要はありません。- ノートブック全体の上書きは常に事前読み込みが必須: Writeツールでノートブックを上書きする場合、通常のファイルなら新しいモデルは未読でも書き込めることがあります。しかしノートブックと部分読み込みのファイルは、どのモデルでも事前の読み込みが必須です。
- 承認ダイアログはv2.1.235で改善されました。それ以前は、ノートブックやセルが読み込めない状態でセルの削除・置換を承認するダイアログが、既存のセル内容をエラーも出さずに省略していました。現在は省略された理由が表示されます。
- VS Codeなどの拡張が持つインライン差分表示は、ノートブックファイルでは無効になっています。タイムアウトエラーの対策として導入された挙動で、通常ファイルの編集と違い、変更後の内容は承認ダイアログ側で確認する形になります。エディタ上でセル単位の差分が見当たらなくても不具合ではありません。
CLAUDE_CODE_PERFORCE_MODEを設定すると、読み取り専用ファイルへのEdit・Write・NotebookEditは黙って上書きされません。p4 editを促すヒント付きで失敗するようになります。バージョン管理システムが読み取り専用属性を付けるチーム環境では、この挙動をあらかじめ把握しておくと安心です。
編集後の後戻りとほかのツールとの役割分担
Claude Codeはノートブック編集を含む、すべてのファイル編集ツールによる変更を自動的に追跡しています。プロンプトを送るたびにチェックポイントが作られ、/rewindで直前の状態に戻せます。チェックポイントはセッションごとに直近100件まで保持され、参照されなくなった古いスナップショットは順次削除されます。既定ではセッションが最後に保存されてからおよそ30日でファイルスナップショットも削除されます。長期間放置したセッションでは/rewindが失敗することがあり、保持期間を伸ばしたい場合はcleanupPeriodDaysを設定します。ただしBash経由の変更やサブエージェントによる編集の復元には制限があります。詳しくはClaude Code checkpointの制限にまとまっています。
NotebookEditが得意なのは、セル単位の機械的な書き換えや、複数セルにまたがる一括修正です。一方でJupyter本体は、ノートブック向けにnbformat(形式の検証・変更)やnbconvert(他形式への変換)、nbviewer(表示専用の閲覧)といった専門ツールも提供しています。NotebookEditが書き込む.ipynbファイルも、このnbformat仕様に沿った構造です。Gitでノートブックをバージョン管理していると、生の.ipynbはJSON形式のためdiffが読みにくくなりがちです。Jupyter本体はnbdimeというノートブック専用の比較・マージツールも提供しており、NotebookEditによる変更をレビューする場面の参考になります。グラフやウィジェットを操作しながら試行錯誤する段階はJupyterLabのようなエディタに向きます。決まった処理をノートブック全体へ機械的に適用する段階はClaude Codeに任せる、という役割分担が現実的です。
Editツールの文字列完全一致は、空白やインデントのわずかな違いだけで失敗することがあります。タブインデントの編集が失敗する現象も、この完全一致の制約に起因します。NotebookEditはcell_idで対象を指定するため、この種の文字列不一致には影響されません。ノートブック以外の通常ファイルも含めた日常的な編集の工夫は、Claude Codeの生産性を上げる小技12選にもまとまっています。
まとめ
Claude CodeはNotebookEditというJupyterノートブック専用ツールで、cell_id単位にセルを置き換え・追加・削除します。権限ルールはEdit(path)で書く必要があり、NotebookEdit(path)という直感的な書き方が実は無視される点が最大の注意点です。ノートブック全体の上書きにはモデルを問わず事前読み込みが必須で、100MBを超えるファイルはシェルコマンドで部分的に読む必要があります。データ分析やモデル検証のノートブックを日常的に触るなら、まずは権限設定をEdit(notebooks/**)のような形で見直しておくと、意図しない拒否や無効なルールに悩まされずに済みます。セル単位の機械的な書き換えをClaude Codeに任せつつ、可視化を伴う試行錯誤はJupyterLabなどの専用エディタで行う、という使い分けが実務的です。