Notebooks dienen der Erkundung; ausgelieferter Code lebt in getesteten Modulen.
Constitution — Notebook to production
Version 1.0.0 · Ratified 2026-11-10
These principles hold for every spec, plan and task of the project. A spec may add rules; it never weakens these.
-
Notebooks are for exploring. Notebooks are used to explore data and present results. Nothing in production imports a notebook or runs one as a scheduled job without going through the rules below.
-
Shipped code lives in tested modules. Logic that is reused or shipped moves into a Python package with pytest tests and type hints, and the notebook imports it. A function copied between notebooks is moved to the package.
-
Notebooks run top to bottom. Every committed notebook runs from a fresh kernel with Restart and Run All. CI executes them with nbconvert or papermill, with parameters for any paths or dates, and a failing notebook fails the build.
-
Clean diffs. Outputs are stripped before commit with nbstripout or a pre-commit hook, or the notebook is paired to a script with Jupytext. A pull request never carries megabytes of output.
-
Pinned environment. Every notebook states the environment it runs in through a locked dependency file, and data is read from versioned paths, never from a personal local copy.