Rule

tensorflow deep learning

via PatrickJS/awesome-cursorrules

TensorFlow and deep learning best practices for building, training, and deploying neural networks

What is tensorflow deep learning?

Comprehensive guide for TensorFlow-based machine learning projects, covering model development, training pipelines, evaluation methodology, and production deployment. Use this rule to establish reproducible workflows, avoid common pitfalls like data leakage and poor evaluation practices, and ensure consistency between training and serving environments.

Organize projects with separated data loading, model definition, training, and serving code using tf.data pipelines
Develop models with Keras layers, explicit input shapes, and callbacks for checkpointing, early stopping, and monitoring
Validate data quality and class balance before training; split data before augmentation or normalization fitting
Track loss curves, metrics, learning rate, and resource usage; save best checkpoint by validation metric
Report task-appropriate evaluation metrics (AUROC, F1, calibration, BLEU/ROUGE, MAE/RMSE) with confusion matrices and error analysis
Export models with clear input signatures and smoke tests; monitor latency, memory, prediction drift, and input schema changes in production

Applies to

File patterns this rule matches.

["**/*.py"

**/*.ipynb

pyproject.toml

requirements*.txt

"environment*.yml"]

Rule definition (reference)

Source of truth, from the repository.

TensorFlow and Deep Learning Rules

Project Structure

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

Model Development

Start with a small baseline model and a tiny overfit test before scaling.
Use Keras layers and models unless lower-level TensorFlow 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, while documenting nondeterministic GPU behavior.

Training

Validate data shapes, dtypes, label ranges, and class balance before training.
Split data before augmentation or normalization fitting.
Use validation data for tuning and 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 such as AUROC, F1, calibration, perplexity, BLEU/ROUGE, or MAE/RMSE.
Include confusion matrices or error slices for classification tasks.
Evaluate on edge cases and distribution shifts when data allows.
Compare against non-neural baselines when the dataset is small or tabular.

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

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