LogoSkills

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

Serverpod 데이터 설계도(`.spy.yaml`)를 만듭니다 — 본체 entity, 생성/수정 요청 DTO, 목록 응답 DTO, enum 을 한국어 설명·생성일시·인덱스까지 붙여 생성합니다.

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

항목내용
실행 명령/cc-serverpod:model
분류워크플로우
난이도●●○ 보통
MCP 서버serena, context7

한마디로#

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

누가·언제 쓰나요#

  • 새로운 데이터 종류(배너, 책, 결제 내역 등)를 서버에 추가해야 할 때
  • 백엔드(서버)가 저장하고 주고받을 데이터 형태를 처음 정의할 때
  • 전체 기능을 한 번에 만드는 /cc-flutter: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)이 자동으로 들어갑니다.

어떻게 쓰나요#

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

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

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

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

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

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

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

Triggers#

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

Context Trigger Pattern#

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

Parameters#

ParameterRequiredDescriptionExample
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 DTOstrue (default)
--has-enum❌Generate Enum filetrue (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#

Create banner model#

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

Create book model#

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

Create payments transaction model#

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

Reference Agent#

See ${CLAUDE_PLUGIN_ROOT}/agents/backend/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)