serverpod-model-agent

Serverpod Model 전문가. .spy.yaml 모델 정의, 필드 타입, 인덱스 작업에 사용합니다.

항목	내용
실행 명령	`/cc-serverpod:model`
별칭	`/backend:model`, `/model:create`
모델	`sonnet`
사용 도구	`Read`, `Edit`, `Write`, `Glob`, `Grep`
연계 스킬	`serverpod`

한마디로#

새 기능에 필요한 "데이터 보관 양식(설계도)"을 자동으로 만들어 주는 도우미입니다. 물건을 넣을 서랍장을 짤 때 "이 칸엔 제목, 이 칸엔 작성자, 이 칸엔 작성 날짜"처럼 칸을 미리 정해 두는 일과 같아요.

누가·언제 쓰나요#

새 기능을 만들면서 어떤 정보를 저장할지 정의해야 하는 백엔드 개발자
/cc-serverpod:model 명령을 직접 실행할 때
전체 기능 생성(/cc-flutter:feature:create)의 첫 단계에서 자동으로 호출될 때

무엇을 해주나요#

데이터 양식 파일(.spy.yaml)을 정해진 폴더에 자동으로 만들어 줍니다. 구체적으로는:

Entity 파일 — 실제로 저장할 정보의 본체 양식 (예: {entity_name}.spy.yaml)
DTO 파일 — 만들기/수정하기/목록 보기 같은 작업에 쓰는 요청·응답 양식 (생성·수정·목록 응답용)
Enum 파일 — "상태값" 같은 정해진 선택지 목록 (필요한 경우에만)

만들어진 뒤에는 이 양식을 실제 코드로 바꾸는 작업(코드 생성)과, 데이터베이스 반영(마이그레이션)까지 이어집니다.

어떻게 쓰나요#

# 명령 실행 (별칭으로도 호출 가능)
/cc-serverpod:model
/backend:model
/model:create

실행할 때는 아래 값을 함께 넘깁니다. (✅ 표시는 반드시 필요한 값)

feature_name ✅ — 기능 모듈 이름 (snake_case, 예: community_post)
entity_name ✅ — 저장할 정보의 이름 (PascalCase, 예: Post)
fields ✅ — 어떤 칸(필드)들을 둘지 목록
has_crud — 만들기/수정 같은 작업용 양식(CRUD DTO)을 자동 생성할지 (기본값: 켜짐)

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

정해진 폴더 구조에 맞춰 Entity, DTO, Enum 양식 파일(.spy.yaml)을 만듭니다.
각 칸에는 한국어 설명, 작성·수정 날짜, 필요한 색인(index), 다른 데이터와의 연결 관계, 기본값(조회수·상태 등)을 빠짐없이 채웁니다.
양식을 다 만든 뒤 의존 모듈 → 기능 모듈 → 호스트 codegen을 실행합니다. 이 단계를 건너뛰면 새 양식이 SDK에 반영되지 않습니다.
Entity가 바뀐 경우에는 데이터베이스 반영용 마이그레이션을 만들고 적용합니다.

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

Role#

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

Activation Conditions#

Activated on /cc-serverpod:model command invocation
Called in Step 1 of /cc-flutter: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#

먼저 .cob/feature-layout.json을 읽고, 없으면 cob의 기존 legacy 트리 판정 → 나머지는 bundle을 따른다. marker를 보존하고 생성 배치 계약을 적용한다. {feature_name}_server는 type: module, client는 feature/{feature_name}/client의 {feature_name}_client다. 조립은 bundle.json, 결합은 host-integration.json; 신규 기본은 공식 4.0.3이다. 호스트에 기능 모델을 복제하지 않는다.

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}_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 .spy.yaml, run the actual project's bundle-aware codegen in requires DAG order: dependency modules → feature module → host. Use the matching official CLI (new default 4.0.3). For table changes create the module migration before regenerating the host's aggregate migration; preserve migration history.

# Root bundle-aware generation (when provided by the project)
dart run tool/feature_codegen.dart
# Run official create-migration in the module, then in the host; apply at the host.

Important#

If module→host codegen is skipped:

New models will not be reflected in the module/host SDK
Frontend cannot use new Entities/DTOs
Build errors will occur

Only for a project resolved as legacy, use its existing backend:pod:generate / migration scripts. DB integration tests always belong to backend/{project}_server/test/integration/; module pure tests belong to feature/{feature_name}/server/test/unit/.

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)