Data Project Rules

When to use this

For a Python data analysis, pipeline, or ML project. The emphasis differs from a web app template: data projects need explicit rules about what the agent may do to datasets, because those mistakes are often unrecoverable.

The template

# AGENTS.md

## Project

[One or two sentences: what this pipeline or analysis does.]

Stack: Python 3.12, pandas, scikit-learn, DuckDB. Dependencies managed with uv.

## Commands

- `uv sync` installs dependencies
- `uv run pytest` runs tests
- `uv run ruff check --fix` lints
- `uv run mypy src/` type checks
- `uv run python -m src.pipeline` runs the pipeline end to end

Run tests and mypy before saying a change is done.

## Structure

- `src/pipeline/` extraction and transformation steps
- `src/features/` feature engineering
- `src/models/` training and evaluation
- `notebooks/` exploration only, never imported by src
- `data/raw/` immutable source data
- `data/processed/` generated, safe to delete and rebuild

## Data rules

- `data/raw/` is read only. Never write to it, never modify it, never delete from it.
- Anything in `data/processed/` must be reproducible by rerunning the pipeline.
- Never commit data files. They are gitignored, keep it that way.
- Do not print full dataframes to output. Use `.head()` or `.describe()`.
- Set a random seed for anything stochastic, so results reproduce.

## Conventions

- Type hints on every function signature
- Use pathlib, not string paths
- Config goes in `config.yaml`, never hardcoded in source
- Notebooks are for exploration. Anything reused moves into `src/`.
- Log with the `logging` module, not `print`

## Do not

- Do not fill or drop missing values without being asked. Report them.
- Do not change a random seed to get a better result
- Do not add a dependency without asking
- Do not run anything that costs money, such as a paid API or a cloud training job, without asking
- Do not modify data in place

## Needs approval before proceeding

- Adding a dependency
- Any operation that writes outside `data/processed/`
- Anything that calls a paid API
- Deleting any file
- Changing the evaluation metric or the train and test split

What to change

Replace the stack and the commands with yours. If you use conda or poetry rather than uv, change every command accordingly.

The data rules section is the one to keep. An agent that rewrites your raw data has destroyed work that may not be recoverable, and it is the failure mode specific to this kind of project.