← Todos os modelos

Notebooks são para explorar; o código entregue vive em módulos testados.

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.

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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.