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

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

항목	내용
실행 명령	`/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 은 각각 생성/수정 양식과 분류값 파일을 함께 만들지 정합니다(기본값은 둘 다 만듦).

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

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

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

⚙️ 상세 옵션·실행 명세 (개발자 / 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#

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#

먼저 .cob/feature-layout.json을 읽고, 없으면 cob의 기존 legacy 트리 판정 → 나머지는 bundle을 따른다. marker를 보존하고 생성 배치 계약을 적용한다. 모델 소유자는 {feature_name}_server(type: module); SDK는 feature/{feature_name}/client의 {feature_name}_client다. bundle.json(조립) + host-integration.json(호스트 결합)을 구분하고 호스트에 모델을 복제하지 않는다.

1. Analyze Existing Patterns#

Use Serena MCP to analyze existing model patterns:
- feature/banner/server/lib/src/model/ (entities, dto, enum)
- feature/books/server/lib/src/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#

feature/{feature_name}/server/lib/src/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#

공식 CLI·호스트·모듈·client 버전을 맞춘다(신규 기본 4.0.3). requires DAG의 의존 모듈 → 기능 모듈 → 호스트 순으로 codegen하며, 테이블 변경은 모듈 migration → 호스트 집계 migration 순서로 공식 CLI를 실행한다. DB 통합 테스트는 backend/{project}_server/test/integration/에서 검증한다. legacy 판정일 때만 기존 melos backend 스크립트를 사용한다.

# Bundle-aware codegen, when provided by the project
dart run tool/feature_codegen.dart

MCP Integration#

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

Examples#

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

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)