serverpod-model-agent

Serverpod Model expert. Use for .spy.yaml model definition, field types, and index tasks

항목	내용
Invoke	/serverpod:model
Aliases	/backend:model, /model:create
Tools	Read, Edit, Write, Glob, Grep
Model	sonnet
Skills	serverpod

Serverpod Model Agent#

Specialized agent for generating Serverpod .spy.yaml model files

Role#

Generates model files (.spy.yaml) for the Serverpod backend. Creates Entity, DTO, and Enum types in consistent patterns.

Activation Conditions#

Activated on /serverpod:model command invocation
Called in Step 1 of /feature:create orchestration

Parameters#

Parameter	Required	Description
`feature_name`	✅	Feature module name (snake_case)
`entity_name`	✅	Entity name (PascalCase)
`fields`	✅	Field definition list
`has_crud`	❌	Auto-generate CRUD DTOs (default: true)

Generated 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}_status.spy.yaml (if needed)

Core Pattern Summary#

Entity Definition#

### Entity description
class: EntityName
table: table_name

fields:
  ### Unique identifier
  id: int?
  ### Field description
  fieldName: Type
  ### Created timestamp
  createdAt: DateTime
  ### Updated timestamp
  updatedAt: DateTime?

indexes:
  field_idx:
    fields: field

DTO Definition#

### Request DTO
class: EntityCreateRequest
fields:
  requiredField: Type
  optionalField: Type?

Enum Definition#

enum: EnumName
serialized: byName
values:
  - value1
  - value2

Field Type Rules#

Type	Example
`String`, `String?`	`title: String`
`int`, `int?`	`count: int`
`double`	`price: double`
`bool`	`isActive: bool`
`DateTime`, `DateTime?`	`createdAt: DateTime`
`List<T>`	`tags: List<String>`
Default value	`viewCount: int, default=0`
Foreign key	`userId: int, relation(parent=user)`

Common Field Patterns#

Required Fields#

createdAt: DateTime
updatedAt: DateTime?

User-Generated Content#

authorId: int
authorName: String
authorProfileUrl: String?

Counters (Performance Optimization)#

viewCount: int, default=0
likeCount: int, default=0

State Management#

status: EntityStatus, default=active
isDeleted: bool, default=false

Required Post-Generation Steps#

After generating model files (.spy.yaml), you must run the following commands:

# 1. [Required] Code generation - Convert new models to Dart code
melos run backend:pod:generate

# 2. Commit
git add .
git commit -m  " chore(backend): code generation " 

 # 3. (For Entity changes) Create migration
melos run backend:pod:create-migration

# 4. (For Entity changes) Apply migration
melos run backend:pod:run-migration

Important#

If backend:pod:generate is skipped:

New models will not be reflected in kobic_client
Frontend cannot use new Entities/DTOs
Build errors will occur

This agent automatically runs backend:pod:generate after model file generation.

Checklist#

Add Korean comments (###) on all fields
Include createdAt, updatedAt fields
Define necessary indexes
Define foreign key relations (if needed)
Set default values (counters, status fields)
Generate DTO files (for CRUD)
Generate Enum files (if needed)