{"filename":"tensorflow-deep-learning.mdc","content":"---\ndescription: TensorFlow and deep learning rules for building, training, evaluating, and deploying neural network models\nglobs: [\"**/*.py\", \"**/*.ipynb\", \"pyproject.toml\", \"requirements*.txt\", \"environment*.yml\"]\nalwaysApply: false\n---\n\n# TensorFlow and Deep Learning Rules\n\n## Project Structure\n\n- Separate data loading, model definition, training, evaluation, and serving code.\n- Use `tf.data` pipelines for scalable input processing.\n- Keep model hyperparameters in typed config files or dataclasses.\n- Store checkpoints, logs, and exported models outside source directories.\n- Keep notebooks exploratory; move repeatable training code into modules.\n\n## Model Development\n\n- Start with a small baseline model and a tiny overfit test before scaling.\n- Use Keras layers and models unless lower-level TensorFlow APIs are required.\n- Prefer explicit input shapes and named inputs/outputs.\n- Use callbacks for checkpointing, early stopping, learning-rate scheduling, and TensorBoard logging.\n- Use mixed precision only after validating numerical stability.\n- Pin random seeds where reproducibility matters, while documenting nondeterministic GPU behavior.\n\n## Training\n\n- Validate data shapes, dtypes, label ranges, and class balance before training.\n- Split data before augmentation or normalization fitting.\n- Use validation data for tuning and a separate test set for final reporting.\n- Track loss curves, metrics, learning rate, and resource use.\n- Save the best checkpoint by validation metric, not by final epoch.\n\n## Evaluation\n\n- Report task-appropriate metrics such as AUROC, F1, calibration, perplexity, BLEU/ROUGE, or MAE/RMSE.\n- Include confusion matrices or error slices for classification tasks.\n- Evaluate on edge cases and distribution shifts when data allows.\n- Compare against non-neural baselines when the dataset is small or tabular.\n\n## Deployment\n\n- Export models with clear input signatures.\n- Keep preprocessing consistent between training and serving.\n- Add smoke tests that load the exported model and run inference on sample inputs.\n- Monitor latency, memory, prediction drift, and input schema changes.\n\n## Common Mistakes\n\n- Do not tune architecture before verifying labels and data quality.\n- Do not leak validation data through preprocessing or augmentation.\n- Do not rely on accuracy alone for imbalanced data.\n- Do not deploy a notebook-only model.\n- Do not ignore batch size, dtype, and device differences between training and inference.\n"}