|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +Guidance for AI coding agents (and human contributors) working in this repository. |
| 4 | + |
| 5 | +## Setup |
| 6 | + |
| 7 | +The project uses [uv](https://docs.astral.sh/uv/). `uv sync` creates the environment |
| 8 | +(`uv sync --group docs` adds the Sphinx toolchain). |
| 9 | + |
| 10 | +## Checks to run before considering a change done |
| 11 | + |
| 12 | +```sh |
| 13 | +uv run ruff format . # formatting |
| 14 | +uv run ruff check . # lint (ruff's default rule set) |
| 15 | +uv run ty check # type checking |
| 16 | +uv run vulture # dead code (min_confidence = 80, see pyproject.toml) |
| 17 | +uv run pytest # tests (runs in parallel with xdist) |
| 18 | +uv run sphinx-build -W docs docs/_build # docs, if docstrings or docs/ changed |
| 19 | +``` |
| 20 | + |
| 21 | +CI runs the same checks. `pre-commit install` runs ruff on each commit. |
| 22 | + |
| 23 | +### Tests must stay fast |
| 24 | + |
| 25 | +The whole suite should finish in seconds. Slow tests are a bug, not a cost of doing |
| 26 | +business: use small problem sizes and a capped `maxiter`, and assert the same |
| 27 | +properties. `conftest.py` pins BLAS to one thread because the test matrices are tiny and |
| 28 | +multithreaded BLAS makes them dramatically slower. Warnings are errors |
| 29 | +(`filterwarnings = ["error", ...]`); fix the cause, or add a narrowly-scoped, |
| 30 | +commented ignore for third-party warnings. |
| 31 | + |
| 32 | +### Dead code -- vulture |
| 33 | + |
| 34 | +Anything vulture reports at 80%+ confidence should be removed. Public methods and |
| 35 | +functions (the library API) intentionally have no in-repo callers and are not |
| 36 | +reported below that threshold; do not delete them just because they are unused here. |
| 37 | + |
| 38 | +## Conventions |
| 39 | + |
| 40 | +- Docstrings are NumPy style (they feed Sphinx autodoc). |
| 41 | +- Missing data is represented by `NaN`; solvers must ignore it, not impute it. |
| 42 | +- Public API lives in `tensorpack/__init__.py` (`__all__`). |
0 commit comments