메뉴
/feat-new 가 읽는 Ballog API 명세 MD의 YAML 스키마 정의. endpoints/types/msw/figma 필드와 작성 규칙. spec 파일 작성이나 파싱할 때 참조.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
| name | ballog-spec-format |
| description | /feat-new 가 읽는 Ballog API 명세 MD의 YAML 스키마 정의. endpoints/types/msw/figma 필드와 작성 규칙. spec 파일 작성이나 파싱할 때 참조. |
docs/specs/<feature>.md 안에 첫 ```yaml 코드 블록으로 작성한다. 첫 블록 외에는 무시.
domain: emotion-v2 # 필수. kebab-case 권장. entity 슬라이스 디렉토리 이름
layer: widgets # 선택. widgets(기본) | features | pages
figma: https://figma.com/design/... # 선택. --figma 생략 시 사용
endpoints: # 필수. 1개 이상
- name: getEmotionRecord # camelCase. 훅 이름 = use<Pascal>Query
method: GET # GET | POST | PATCH | PUT | DELETE
path: /emotion/:matchRecordId # 선행 슬래시, 경로 파라미터는 :name
params: # 선택. path/query 파라미터
matchRecordId: number
response: EmotionResponseDTO # types의 이름 or TS 문자열
- name: createEmotion
method: POST
path: /emotion
request: CreateEmotionRequestDTO
response: EmotionResponseDTO
invalidates: [getEmotionRecord] # 선택. mutation 성공 시 invalidate할 query name
types: # 필수
Emotion:
id: number
type: "'HAPPY' | 'SAD' | 'ANGRY'" # 유니온/리터럴은 문자열로 감싸기
createdAt: string
EmotionResponseDTO: "ApiResponseWithNoSuccess<Emotion[]>" # 값 위치에 TS 원문 허용
CreateEmotionRequestDTO:
type: "Emotion['type']"
matchRecordId: number
msw: # 선택
scenarios:
- endpoint: createEmotion # endpoints의 name과 일치
when: "body.matchRecordId === 0" # JS 표현식. `body`/`params`/`request` 참조 가능
status: 400
response: { error: "invalid match" }
ApiResponse<T>, ApiResponseWithNoSuccess<T>, ApiErrorMessage, KyHttpError 는 @/types/api/common 에서 자동 임포트.<camel>Queries.<name>._def 기준으로 invalidateQueries.:name 은 params에 반드시 선언. 자동으로 URL 치환 + 타입 반영.spec domain | directory | file/variable base | Pascal |
|---|---|---|---|
emotion | emotion/ | emotion | Emotion |
emotion-v2 | emotion-v2/ | emotionV2 | EmotionV2 |
demo-ticket | demo-ticket/ | demoTicket | DemoTicket |
demoTicket.api.ts, demoTicketGet)useDemoTicketQuery, DemoTicketResponseDTO)| spec 필드 | 생성 |
|---|---|
types.* | entities/<kebab>/model/<camel>.type.ts |
endpoints[].request/response | 같은 파일에 Request/Response DTO alias 추가 |
endpoints[GET] | <camel>Get.<name> + use<Pascal><Endpoint>Query |
endpoints[!GET] | <camel><Method>.<name> + use<Pascal><Endpoint>Mutation |
endpoints[].invalidates | mutation onSuccess 의 invalidateQueries |
msw.scenarios | handler 내부 조건 분기 |
figma | --figma 미지정 시 fallback URL |
Ballog entity 슬라이스 생성 템플릿. ky API 그룹, query-key-factory 등록, query/mutation 훅 네이밍과 invalidation 규칙. /feat-new 가 참조.
Ballog(apps/web) FSD 레이어 규칙. 의존 방향, public API, import 순서, 네이밍. 파일 생성/리뷰 시 경계 위반 검증에 사용.
Ballog MSW handler/data 생성 템플릿과 handlers.ts 레지스트리 삽입 규칙. /feat-new 가 참조.
Ballog 커밋 및 PR 메시지 컨벤션. 이모지 prefix(✨Feat/💄Style/✏️Fix)와 fix:/feat: 간결 스타일 혼용 규칙, 한국어 PR 본문 작성 틀. /review-pr 이 참조.
Ballog 프로젝트의 Tailwind + cn() 사용 규칙. 조건부 클래스 가독성, twMerge 충돌 회피, 반복 유틸 추출 기준. className을 작성하거나 리뷰할 때 참조.