| name | jupyter-research |
| description | SAENMモデル (Sequential Append-Only Experiment Notebook Model) に基づくJupyter実験ノートの 作成・管理・振り返りワークフロー。「SAENM」「実験ノート」「実験記録」「ノートブック管理」 「研究ノート」等のキーワードで起動。新規実験の開始、既存実験の継続、実験系列の振り返りを支援する。 |
SAENM Jupyter実験ワークフロー
SAENMモデル (Sequential Append-Only Experiment Notebook Model) に基づく実験ノート管理スキル。
参考: CMScomLab/saenm-notebook-template
SAENMの3原則
- Sequential: 実験に単純な連番 (
01, 02, 03...) を付与する。枝番は使わず、微細な更新でも次の番号を割り当てる。親子関係は README.md で管理し、どの検討の続きかを常に追跡可能にする
- Append-Only: 過去のノートを改変・削除しない。修正は新ノートか Corrections セクションへの追記で行う。README.md が履歴の一貫性を担保する
- Experiment Notebook: コード・結果に加え、目的・考察・環境情報・AI利用記録・次の方針を含む包括的な実験記録
適用条件の確認
スキルトリガー後、最初に以下を確認する。
- 作業ディレクトリの確認 (新規 or 既存プロジェクト)
notebooks/ ディレクトリの有無notebooks/README.md の有無- Git管理の有無 (
.git/ の存在で判定)
確認結果に応じて後述のワークフローから適切なパスを選択する。
最小構成
SAENMの核は notebooks/ と README.md だけで、Git がなくても完全に機能する。
project-root/
├── notebooks/
│ ├── README.md # 実験索引 (必須・追記専用)
│ ├── 01_initial_exploration.ipynb
│ ├── 02_improved_method.ipynb
│ └── 03_parameter_tuning.ipynb
└── data/ # (推奨) 入力データ
└── raw/
以下は必要に応じて追加する。
src/ - 再利用コードモジュールresults/ - 出力結果docs/ - 運用ルールtests/ - テストコードpyproject.toml - Pythonプロジェクト設定
README.md (実験索引)
Append-Onlyを構造的に担保する中核ファイル。テーブル形式とMermaid図で管理する。
テーブル構造・Mermaid記法・運用ルールの詳細は references/readme-spec.md を参照。
ノート命名規則
形式: {ID}_{snake_case_title}.ipynb
- タイトルはsnake_caseとするが、複合語がある場合はkebab-caseを部分的に利用してもよい
- 常に単純連番 (
01, 02, 03...)。枝番 (02a 等) は使わない
- 微細な更新・パラメータ変更でも次の番号を割り当てる。試行の粒度は小さくてよい
- ID採番規則
- 基本的には
notebooks/ 内の既存最大番号+1
- 実験のフェーズが大きく変わる場合は十の位を増やす
- 親子関係はIDの連続性ではなく README.md の「親」列で管理する
例:
01_data_collection.ipynb # 親: なし
02_feature_extraction.ipynb # 親: 01
03_model_training.ipynb # 親: 02
04_hyperparameter_search.ipynb # 親: 03 パラメータ変更だけでも新番号
05_alternative_model.ipynb # 親: 03 同じ親から別方向の試行
06_scikit-learn_baseline.ipynb # 親: 04 複合語 (scikit-learn) のみ kebab-case
07_evaluation.ipynb # 親: 06
# ---- ここまで研究フェーズ / ここから本番データ適用フェーズ ----
10_production_dataset_prep.ipynb # 親: 07 フェーズ切替のため 08, 09 を飛ばして 10 から開始
11_production_inference.ipynb # 親: 10
12_monitoring_setup.ipynb # 親: 11
ノート内部構造テンプレート
ノート作成時は references/notebook-template.md のテンプレートに従う。
メタデータ・目的・手法・実行・結果・考察・AI利用記録・次のステップ・Corrections の各セクションを含める。
運用原則 (Append-Onlyルール)
Do
- 新しい試行は新しいノートとして追加する
- 失敗した実験もそのまま残す。判断の変遷自体が知見になる
- README.md に新しい行を追記する
- 過去ノートの誤りは Corrections セクションに追記で記録する
Don't
- 過去のノートのコード・結果を書き換えない
- 失敗したノートを削除しない
- README.md の既存行を削除しない
ワークフロー (エージェント実行手順)
ノート内容の確認方法
既存ノートの内容や出力を確認する際は、以下の順で利用する。
- Read ツールで
.ipynb を直接読み取る。セルの内容と出力が整形済みで得られるため、JSON パースは不要
- 特定セルの出力だけ確認したい場合や構造的に把握したい場合は
nbdime nbshow {ノートパス} を使う
python -m json.tool 等による JSON 整形は使わない。
新規プロジェクト開始
- 作業ディレクトリを確認する
notebooks/ ディレクトリを作成するnotebooks/README.md を空のテーブルヘッダーとMermaid図で作成する- ユーザーに最初の実験の目的をヒアリングする
01_{タイトル}.ipynb をテンプレートに基づいて作成する- README.md に最初の行とMermaidノードを追記する
- Git管理時はコミットを提案する
新規実験追加
notebooks/ 内の既存 .ipynb ファイルを走査する- README.md を読み取り、現在の系列関係を把握する
- 親実験を特定する (ユーザーに確認)
- 次のIDを決定: 既存最大番号+1。常に単純連番
- もし桁が増える場合は、先に既存ファイルの桁数を合わせること
- 新しいノートをテンプレートで作成する。メタデータに親IDを記入
- README.md に行とMermaidエッジを追記する
既存ノート修正の要求への応答
既存ノートの内容は原則として改変しない。要求の種類に応じて対応を分ける。
- typo/Markdown整形: 実験内容に影響しないため許容する
- 結果の訂正・コード修正: 既存ノートの Corrections セクションに追記するか、新しいノートとして作成することを提案する
- やり直しの要望: 次の連番で新しいノートとして作成を提案する
実験系列の振り返り
- README.md を読み取り、系列関係を把握する
- 各ノートの目的・考察・次のステップを読み取る
- 時系列で実験の流れを要約する
- 仮説の変遷
- 判断の分岐点と理由
- 各実験から得られた学び
- 未着手の次のステップをリストアップする
- 次に取り組むべき方向性を提案する
Git連携 (オプション)
.git/ が存在する場合のみ適用。初期化手順・運用ルールは references/git-integration.md を参照。
