notebook-cli

Notebook CLI

すべての .ipynb 操作には nb を使用してください。nb で実行できる場合は、ノートブックの JSON を直接読み取ったり、書き込んだり、パッチを適用したり、編集したりしないでください。

基本ルール

• 編集前に確認してください。出力が関係する場合を除き、nb read <notebook> --no-output を実行します。
• nb read のデフォルトである AI に最適化された Markdown 出力を優先してください。--json は nbformat JSON が必要な場合に限って使用します。
• ノートブックを確認した後、永続的な編集にはセル ID（--cell / -c）を優先してください。位置を指定した簡単な作業にはインデックス（--cell-index / -i）を使用します。負のインデックスも使用できます。
• 構造やソースを要約する場合は --no-output を使用してください。結果、失敗、プロット、または表示値を調べる場合に限り、出力を含めます。
• 複数行の内容や引用符を含む内容には stdin（--source -）を使用し、シェルのエスケープミスを防いでください。
• ユーザーが uv を指定した場合、またはワークスペースが明らかに uv プロジェクトの場合は、タスク全体を通じてノートブックの実行環境として uv を使用します。nb create や nb execute など、対応する nb コマンドでは --uv を使用してください。
• 複数のセクションがあるノートブックを作成する場合は、論理的なセクションごとにおよそ 3～5 個のセルをまとめて追加し、複数セルのセンチネル（@@markdown、@@code）を使用してください。次のセルを追加する前に、各バッチを実行して検証します。ノートブック全体を一度の呼び出しで追加しないでください。遅延が増え、エラーを見つけにくくなります。
• すべての Markdown セルには見出しと、それに続くコードの動作や重要性を説明する文章を少なくとも 1 文含めてください。見出しだけでは不十分です。best-practices.md を参照してください。
• ノートブックのコードがサードパーティー製パッケージに依存し、パッケージが利用可能か不明な場合は、インポートの前に依存関係をインストールするセルをノートブックの先頭に追加してください。
• uv 環境がある場合、依存関係セルでは !uv pip install ... を使用してください。
• uv 環境がない場合、依存関係セルでは %pip install ... を使用してください。
• コマンドの構文が不明な場合は、nb <command> --help または nb cell <subcommand> --help を実行してください。
• 接続モードでは、nb に nb connect で保存した接続を使用させてください。秘密のトークンをコマンド、プロンプト、ログ、または例に記述しないでください。自動検出できない場合は、ユーザーに手動で接続を確立するよう依頼してください。
• アクティブなノートブック環境と一致させる必要がある、ノートブック以外の Python コマンドを実行する前に、nb status --python を使用し、返されたプレフィックスを使ってコマンドを実行してください。

信頼境界

nb は、ノートブックの内容を読み取ることができ、接続モードでは保存された Jupyter 接続状態を利用できる外部実行ファイルです。ワークスペースで初めて使用する前に、実行するコマンドを確認してください。

command -v nb
nb --version

リポジトリでビルドされた、またはドキュメントに記載された nb-cli バイナリを使用してください。nb が見つからない場合、予期しないパスに解決される場合、または予期しないバージョン名を報告する場合は、処理を中止し、信頼できる nb-cli バイナリをインストールするか選択するようユーザーに依頼してください。未検証の実行ファイルにノートブックの内容、出力、サーバー URL、または接続状態を渡さないでください。

一般的なワークフロー

ノートブックを作成する

nb create analysis.ipynb
nb create analysis.ipynb --kernel python3
nb create notes.ipynb --markdown

新しいノートブックの作成、カーネルの選択、または既存のノートブックの上書きについては、references/create.md を参照してください。

ノートブックを確認する

nb read analysis.ipynb --no-output
nb read analysis.ipynb --cell-index 3
nb search analysis.ipynb "fit_model"

フィルター、出力の扱い、AI Markdown 形式の解析については、references/read.md を参照してください。

セルを編集する

nb cell update analysis.ipynb --cell "cell-id" --source -
nb cell add analysis.ipynb --type markdown --source "# Results"
nb cell delete analysis.ipynb --cell-index -1

複数セルの編集、メタデータの保持、セル ID を基準にした挿入、または範囲の削除を行う前に、references/edit-cells.md を参照してください。

実行とデバッグ

nb execute analysis.ipynb --cell-index 4
nb execute analysis.ipynb --start 0 --end 5 --allow-errors
nb read analysis.ipynb --cell-index 4

カーネルの選択、タイムアウト、環境フラグ、失敗時のワークフローについては、references/execute.md を参照してください。

JupyterLab を使用する

nb connect
nb status
nb cell update analysis.ipynb --cell "cell-id" --source -
nb disconnect

ノートブックが JupyterLab で開いている場合や、実行中のサーバーを通じて変更を同期する必要がある場合は、references/connect-mode.md を参照してください。

出力を管理する

nb read analysis.ipynb --limit 8000 --output-dir ./notebook-outputs
nb output clear analysis.ipynb
nb output clean

センチネルの解析、外部化された出力ファイル、出力のクリア、コミット時の注意点については、references/output-format.md を参照してください。

品質の高いノートブックを作成する

ノートブックを作成またはレビューする際の、物語構成、コードの整理、再現性、命名規則に関する研究に基づくガイドラインについては、references/best-practices.md を参照してください。

権限に関する注意

サンドボックスポリシーによってエージェントが nb または接続モードのコマンドを実行できない場合は、必要なコマンドの実行をユーザーに許可してもらってください。継続的に使用する場合は、プロジェクトまたはユーザーのルールで nb コマンドのプレフィックスを許可してください。

検証用プロンプト

このスキルが引き続き、エージェントを意図した nb ワークフローへと導いているか確認する際は、references/validation-prompts.md を使用してください。