playbooks

home / skills / tlabs-xyz / tbtc-v2-performance / backend-models

backend-models skill

/.claude/skills/backend-models

This skill guides you in designing, validating, and optimizing backend models with correct types, constraints, relationships, and lifecycle hooks.

npx playbooks add skill tlabs-xyz/tbtc-v2-performance --skill backend-models

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
2.0 KB
---
name: Backend Models
description: Define database models with clear naming, appropriate data types, proper constraints, and well-defined relationships. Use this skill when creating new database models or entities, defining model schemas, implementing model validations, setting up model relationships (one-to-one, one-to-many, many-to-many), adding timestamps or audit fields, defining database constraints (NOT NULL, UNIQUE, foreign keys), choosing appropriate data types for fields, implementing model hooks or lifecycle methods, creating indexes on model fields, working with ORM model files, or refactoring existing model definitions. Use when working with model files in directories like models/, entities/, or schema/ for ORMs like Sequelize, TypeORM, Prisma, SQLAlchemy, ActiveRecord, Django models, or Mongoose.
---

## When to use this skill

- When creating new database model or entity classes
- When defining model schemas and field definitions
- When implementing model-level validations
- When setting up model relationships (one-to-one, one-to-many, many-to-many)
- When adding timestamps, audit fields, or soft delete functionality
- When defining database constraints (NOT NULL, UNIQUE, foreign keys)
- When choosing appropriate data types for model fields
- When implementing model hooks, lifecycle methods, or computed properties
- When creating indexes on model fields
- When working with model files in models/, entities/, or schema/ directories
- When refactoring existing model definitions for consistency
- When working with ORMs like Sequelize, TypeORM, Prisma, SQLAlchemy, ActiveRecord, Django models, or Mongoose
- When defining cascade behaviors for relationships

# Backend Models

This Skill provides Claude Code with specific guidance on how to adhere to coding standards as they relate to how it should handle backend models.

## Instructions

For details, refer to the information provided in this file:
[backend models](../../../agent-os/standards/backend/models.md)

Overview

This skill helps you design and maintain backend database models with clear naming, appropriate data types, proper constraints, and well-defined relationships. It focuses on creating consistent, maintainable model schemas for ORMs like TypeORM, Prisma, Sequelize, Mongoose, Django, SQLAlchemy, and ActiveRecord. Use it to ensure models are validated, indexed, and ready for real-world queries and migrations.

How this skill works

I inspect model files and schema definitions under directories like models/, entities/, or schema/ and recommend concrete changes: field types, nullability, defaults, indexes, and foreign keys. I enforce relationship patterns (one-to-one, one-to-many, many-to-many), lifecycle hooks, timestamps/audit fields, and cascade rules, and I suggest refactors to improve naming and consistency. I also help add constraints and indexes that improve data integrity and query performance.

When to use it

  • Creating new model or entity classes for a feature or service
  • Defining or refactoring field types, nullability, defaults, or validations
  • Setting up or revising relationships and cascade behaviors
  • Adding timestamps, audit fields, soft deletes, or lifecycle hooks
  • Creating indexes or defining database constraints (UNIQUE, NOT NULL, FK)

Best practices

  • Use clear, singular resource names and consistent field naming (snake_case or camelCase across models)
  • Prefer explicit types and NOT NULL where appropriate; add defaults for predictable behavior
  • Model relationships explicitly with foreign keys and constrained cascade rules; avoid implicit joins
  • Add indexes for frequently filtered or joined fields and UNIQUE constraints for natural keys
  • Include created_at/updated_at and optional deleted_at for audit and soft-delete requirements
  • Centralize validations and hooks in the model layer, not duplicated in controllers

Example use cases

  • Define a User model with email UNIQUE, hashed password, created_at/updated_at, and an index on email
  • Refactor an Order/OrderItem relationship to enforce foreign keys and ON DELETE CASCADE
  • Add a many-to-many join table with explicit composite UNIQUE index for Product and Tag
  • Migrate string-based status fields to an ENUM type with a default value and validations
  • Introduce soft-delete by adding deleted_at and filtering queries at the model scope

FAQ

Should I always use NOT NULL for all fields?

Prefer NOT NULL for fields that are required by business logic. Use nullable fields only when missing data is expected; document optional fields clearly.

Where should I put complex validations?

Keep validations close to the model layer so they apply consistently across services. Use schema-level validators or ORM hooks for cross-field checks.