folder-organization

Use a layout with data/raw, data/processed, notebooks, src, scripts, tests, docs, results, and config directories. Keep raw data immutable, separate code from outputs, and include a README and environment file at the root.

Use lowercase names with hyphens or underscores, be descriptive but concise, and pick one separator style consistently. For sequential notebooks, use zero-padded numbers like 01-exploration.ipynb, and add dates or versions to important outputs.

Exclude large data files, generated outputs, environment directories like venv/, logs, temporary files, and secrets such as .env. Commit source code, documentation, configuration files, and small test datasets under 1MB.

Never modify raw data; store originals in data/raw/ and make them read-only if possible. Keep intermediate steps in data/interim and final analysis-ready files in data/processed, and document data provenance.

Avoid flat structures with everything in the root, ambiguous names like notebook1.ipynb or analysis_new.ipynb, and mixing data or output files inside source code directories. These patterns hurt discoverability and reproducibility.