/serverpod:model#

Context Framework Note: This behavioral instruction activates when Claude Code users type /serverpod:model patterns.

Triggers#

• When a new Serverpod model (Entity, DTO, Enum) is needed
• When backend data model definition is needed
• Called in Step 1 of /feature:create orchestration

Context Trigger Pattern#

/serverpod:model {feature_name} {entity_name} [--options]

Parameters#

Behavioral Flow#

1. Analyze Existing Patterns#

Use Serena MCP to analyze existing model patterns:
- backend/petmedi_server/lib/src/feature/community/model/entity/post.spy.yaml
- backend/petmedi_server/lib/src/feature/chat/model/entity/chat_room.spy.yaml

2. Generate Model Files#

Entity File (entities/{entity_name}.spy.yaml):

### {Entity description}
class: {EntityName}
table: {table_name}

fields:
  ### Unique identifier
  id: int?

  ### {Field1 description}
  {field1}: {Type}

  ### {Field2 description}
  {field2}: {Type}?

  ### Author ID
  authorId: int

  ### Author name
  authorName: String

  ### Author profile image URL
  authorProfileUrl: String?

  ### Created timestamp
  createdAt: DateTime

  ### Updated timestamp
  updatedAt: DateTime?

indexes:
  {entity}_author_idx:
    fields: authorId
  {entity}_created_idx:
    fields: createdAt

Request DTO (dto/{entity_name}_create_request.spy.yaml):

### {Entity} creation request
class: {EntityName}CreateRequest

fields:
  ### {Field description}
  {requiredField}: {Type}
  ### {Optional field description}
  {optionalField}: {Type}?

Response DTO (dto/{entity_name}_list_response.spy.yaml):

### {Entity} list response
class: {EntityName}ListResponse

fields:
  ### {Entity} list
  items: List < {EntityName} > 
   ### Total count
  total: int
  ### Whether next page exists
  hasMore: bool

Enum (enum/{entity_name}_category.spy.yaml):

### {Entity} category
enum: {EntityName}Category
serialized: byName
values:
  - general
  - notice
  - event

3. Verification#

• Verify Korean comments on all fields
• Verify required fields (createdAt, updatedAt) included
• Verify index definitions

Output Files#

backend/petmedi_server/lib/src/feature/{feature_name}/model/
├── entities/
│   └── {entity_name}.spy.yaml
├── dto/
│   ├── {entity_name}_create_request.spy.yaml
│   ├── {entity_name}_update_request.spy.yaml
│   └── {entity_name}_list_response.spy.yaml
└── enum/
    └── {entity_name}_category.spy.yaml

Post-Generation Commands#

# Model code generation
melos run backend:pod:generate

# Create migration (for Entity changes)
melos run backend:pod:create-migration

# Apply migration
melos run backend:pod:run-migration

MCP Integration#

• Serena: Analyze existing model patterns, symbol search
• Context7: Serverpod model definition documentation reference

Examples#

Create post model#

/serverpod:model community Post
  --fields  " title:String, content:String, category:PostCategory, imageUrls:List < String > ? "

Create chat message model#

/serverpod:model chat Message
  --fields  " content:String, senderId:int, chatRoomId:int, readAt:DateTime? "

Create wallet transaction model#

/serverpod:model wallet Transaction
  --fields  " amount:double, type:TransactionType, description:String?, balanceAfter:double "

Reference Agent#

See ~/.claude/commands/agents/serverpod-model-agent.md for detailed implementation rules

Core Rules Summary#

1. Korean comments (###) required on all fields
2. createdAt, updatedAt fields required
3. Appropriate index definitions required
4. Foreign key relation definitions (when needed)
5. Default value settings (counters, status fields)