serverpod:model

Serverpod .spy.yaml model file generation

항목	내용
Invoke	/serverpod:model
Category	kobic-workflow
Complexity	moderate
MCP Servers	serena, context7

/serverpod:model — 백엔드 데이터 설계도 만들기#

한마디로#

서버가 다룰 데이터의 "설계도"를 자동으로 그려주는 단계입니다. 예를 들어 "배너"라는 데이터를 만든다면, 배너에 어떤 정보(제목, 이미지 주소 등)가 들어가는지 정해진 양식의 파일로 한 번에 만들어 줍니다. 집을 짓기 전에 방·창문 위치를 정한 도면을 그리는 것과 같아요.

누가·언제 쓰나요#

새로운 데이터 종류(배너, 책, 결제 내역 등)를 서버에 추가해야 할 때
백엔드(서버)가 저장하고 주고받을 데이터 형태를 처음 정의할 때
전체 기능을 한 번에 만드는 /feature:create 작업의 1단계로 자동 호출될 때

무엇을 해주나요#

데이터 설계도 파일(.spy.yaml)들을 정해진 폴더에 만들어 줍니다. 기능 이름이 banner라면 다음과 같이 생깁니다.

본체 정의 (entities/{이름}.spy.yaml) — 이 데이터가 가진 항목들(제목, 작성자, 생성일시 등)
요청용 양식 (dto/{이름}_create_request.spy.yaml, ..._update_request.spy.yaml) — 데이터를 만들거나 수정할 때 주고받는 형식
응답용 양식 (dto/{이름}_list_response.spy.yaml) — 목록을 돌려줄 때의 형식(목록, 전체 개수, 다음 페이지 유무)
분류값 정의 (enum/{이름}_category.spy.yaml) — 정해진 선택지 목록(예: 일반·공지·이벤트)

모든 항목에는 한국어 설명이 붙고, 생성일시·수정일시 같은 필수 항목과 검색을 빠르게 하는 색인(index)이 자동으로 들어갑니다.

어떻게 쓰나요#

# 배너 모델 만들기
/serverpod:model banner Banner
  --fields  " title:String, imageUrl:String, linkUrl:String?, sortOrder:int, isActive:bool " 

 # 책 모델 만들기
/serverpod:model books Book
  --fields  " title:String, authorId:int, categoryId:int, price:double, coverUrl:String? " 

 # 결제 내역 모델 만들기
/serverpod:model payments Transaction
  --fields  " amount:double, type:TransactionType, description:String?, balanceAfter:double "

첫 번째 값은 기능 이름(소문자, 예: banner), 두 번째 값은 데이터 이름(대문자 시작, 예: Banner)입니다. 둘 다 반드시 필요합니다.
--fields 로 들어갈 항목들을 적습니다. 이름 뒤의 ? 는 "있어도 되고 없어도 되는 항목"이라는 뜻입니다.
--has-crud, --has-enum 은 각각 생성/수정 양식과 분류값 파일을 함께 만들지 정합니다(기본값은 둘 다 만듦).

안에서 무슨 일이 벌어지나요#

기존 방식 살펴보기 — 이미 만들어 둔 비슷한 데이터(배너·책 등)의 구조를 참고해 같은 스타일로 맞춥니다.
설계도 파일 생성 — 본체, 요청·응답 양식, 분류값 파일을 한 번에 만들고 각 항목에 한국어 설명을 붙입니다.
점검 — 모든 항목에 설명이 달렸는지, 생성일시·수정일시가 들어갔는지, 검색용 색인이 잘 정의됐는지 확인합니다.

파일이 만들어진 뒤에는 실제 코드와 데이터베이스에 반영하기 위한 명령(코드 생성, 변경분 만들기, 변경분 적용)을 이어서 실행합니다.

⚙️ 상세 옵션·실행 명세 (개발자 / AI 에이전트용)

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#

Parameter	Required	Description	Example
`feature_name`	✅	Feature module name (snake_case)	`banner`, `books`, `payments`
`entity_name`	✅	Entity name (PascalCase)	`Banner`, `Book`, `Transaction`
`--fields`	❌	Field definition list	`"title:String, content:String"`
`--has-crud`	❌	Auto-generate CRUD DTOs	`true` (default)
`--has-enum`	❌	Generate Enum file	`true` (default)

Behavioral Flow#

1. Analyze Existing Patterns#

Use Serena MCP to analyze existing model patterns:
- backend/kobic_server/lib/src/feature/banner/model/ (entities, dto, enum)
- backend/kobic_server/lib/src/feature/books/model/entities/

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/kobic_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#

/serverpod:model banner Banner
  --fields  " title:String, imageUrl:String, linkUrl:String?, sortOrder:int, isActive:bool "

Create book model#

/serverpod:model books Book
  --fields  " title:String, authorId:int, categoryId:int, price:double, coverUrl:String? "

Create payments transaction model#

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

Reference Agent#

See ${CLAUDE_PLUGIN_ROOT}/commands/agents/backend/serverpod-model-agent.md for detailed implementation rules

Core Rules Summary#

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