TensorFlow and Deep Learning

.cursorrules for TensorFlow and Deep Learning

# TensorFlow and Deep Learning Project Rules

## Project Structure

- Separate data loading, model definition, training, evaluation,
  and serving code into their own modules.
- Use `tf.data` pipelines for scalable input processing.
- Keep hyperparameters in typed config files or dataclasses.
- Store checkpoints, logs, and exported models outside source dirs.
- Keep notebooks exploratory. Move repeatable training code into modules.

## Model Development

- Start with a small baseline + a tiny overfit test before scaling.
- Use Keras layers and models unless lower-level TF APIs are required.
- Prefer explicit input shapes and named inputs/outputs.
- Use callbacks for checkpointing, early stopping, learning-rate
  scheduling, and TensorBoard logging.
- Use mixed precision only after validating numerical stability.
- Pin random seeds where reproducibility matters. Document
  nondeterministic GPU behavior.

## Training

- Validate shapes, dtypes, label ranges, and class balance before training.
- Split data before augmentation or normalization fitting.
- Use validation data for tuning. Hold out a separate test set for
  final reporting.
- Track loss curves, metrics, learning rate, and resource use.
- Save the best checkpoint by validation metric, not by final epoch.

## Evaluation

- Report task-appropriate metrics: AUROC, F1, calibration, perplexity,
  BLEU/ROUGE, or MAE/RMSE.
- Include confusion matrices or error slices for classification.
- Evaluate on edge cases and distribution shifts when data allows.
- Compare against non-neural baselines on small or tabular datasets.

## Deployment

- Export models with clear input signatures.
- Keep preprocessing consistent between training and serving.
- Add smoke tests that load the exported model and run inference on
  sample inputs.
- Monitor latency, memory, prediction drift, and input schema changes.

## Common Mistakes

- Don't tune architecture before verifying labels and data quality.
- Don't leak validation data through preprocessing or augmentation.
- Don't rely on accuracy alone for imbalanced data.
- Don't deploy a notebook-only model.
- Don't ignore batch size, dtype, and device differences between
  training and inference.

Related

• Cursor Rules Guide | Python Claude Rules