Home › Python Data & ML › Jupyter notebook hygiene rules

Jupyter notebook hygiene rules

Cursor rules for Jupyter notebooks in data projects: reproducible cells, small outputs, and moving code into modules.

CursorPython Data & ML

How to use

Save this as .cursor/rules/notebooks.mdc in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

---
description: Jupyter notebook hygiene conventions
globs: ["**/*.ipynb","notebooks/**/*.py"]
alwaysApply: false
---

# Jupyter notebooks

- A notebook must run top to bottom on a fresh kernel ("Restart & Run All"). No cells that depend on run order or deleted variables.
- First cell: imports and config (paths, seeds, display options). Second: load data. Keep paths relative to the repo root or from a config, never `/Users/...`.
- Functions longer than ~15 lines or reused twice move into `src/<package>/` and are imported; use `%load_ext autoreload` + `%autoreload 2` while developing.
- Each section starts with a markdown cell saying what it answers. End with a short "Findings" cell.
- Keep outputs small: `df.head()`, `df.describe()`, sample plots. No printing full DataFrames or 10k-line logs.
- Plots have titles, axis labels and units.
- Don't commit secrets or raw personal data in outputs. Strip outputs on commit if the repo uses `nbstripout`.
- Prefer vectorized pandas/polars over row loops; state the library and version used.
- Large intermediate data goes to `data/interim/` as Parquet, not pickles in the notebook dir.

## When editing an .ipynb
- Edit cells in place; don't rewrite the whole notebook JSON or change cell ids needlessly.
- Prefer a paired `.py` (jupytext percent format) if the repo has one, and edit that.

## Done when
`jupyter nbconvert --to notebook --execute <nb>.ipynb --output /tmp/check.ipynb` runs without errors.