기획문서 작성 규약 (CONVENTION)

이 문서는 worksout-planning-docs의 단일 기준(SSOT) 이다. 사람·AI(프론트 Claude, 백엔드 Kiro)가 모두 이 규약대로 문서를 읽고 쓴다.

원칙

Markdown 이 원본이다. 정적 사이트(Starlight)는 이 .md 를 렌더링한 결과물일 뿐, 문서를 이중화하지 않는다.
한 파일 = 한 관심사(도메인/화면). 필요한 파일만 읽어 토큰을 아낀다.
최신이 항상 명확해야 한다. 파일명에 버전을 넣지 않는다. 버전은 frontmatter + git 히스토리로 관리한다.

폴더 구조

worksout-planning-docs/
├── src/content/docs/          ← 문서 루트 (SSOT)
│   ├── conventions.md         ← 이 문서
│   ├── changelog.md           ← 전 스토어 변경 이력 (최신순)
│   └── stores/
│       └── yeti/
│           ├── index.md       ← YETI 목차
│           ├── Member/
│           │   ├── login.md
│           │   └── signup.md
│           ├── Content/
│           └── ...
├── .templates/domain.md       ← 새 문서 작성용 빈 틀
├── astro.config.mjs           ← 사이트 설정 (스토어 추가 시 sidebar 갱신)
└── src/content.config.ts      ← frontmatter 스키마

스토어별 폴더: stores/<store>/ (예: yeti, worksout, worksout-jp)
도메인 폴더: Member, Content, PLP, PDP, Cart, Search, Navigation, AI (PascalCase)
스토어를 추가하면 astro.config.mjs 의 sidebar 에 한 줄 추가한다.

파일명

버전을 파일명에 넣지 않는다. login.md (O) / login_v1.0.md (X)
kebab-case: hero-banner-cms.md, find-password.md
도메인 목차는 index.md (URL 상 폴더 루트가 된다)

frontmatter (필수)

모든 문서는 아래 YAML frontmatter 로 시작한다.

---
title: "[YETI] 로그인"        # 필수. 사이트 제목 · 사이드바 라벨
domain: member               # 도메인 (소문자)
screen: AUTH-LOGIN-01          # 화면 ID (여러 개면 AUTH-JOIN-01~005)
version: v1.0                # 현재 버전
status: Draft                # Draft | Final | Superseded
updated: 2026-06-25          # 마지막 수정일 (YYYY-MM-DD)
api:                         # 관련 API (백엔드 역검색용, 없으면 생략)
  - POST /auth/login
---

필드	필수	설명
`title`	O	문서 제목. Starlight 사이드바·페이지 제목이 된다
`domain`	O	도메인 소문자 (member, content, plp …)
`screen`	권장	Screen ID. Jira/Figma 화면과 매핑
`version`	O	현재 버전 (`v1.0`)
`status`	O	`Draft`(작성중) · `Final`(확정) · `Superseded`(폐기/대체됨)
`updated`	O	마지막 수정일
`api`	백엔드 관련 시	관련 엔드포인트 배열. 백엔드가 “이 API 기획 어디?” 로 역검색

Screen ID 규칙

형식: {GROUP}-{SUB}-{NN} 또는 서브 구분이 불필요하면 {GROUP}-{NN}

prefix 없음
GROUP — 대분류 코드 (아래 표)
SUB — 서브 화면 구분 (그룹 내 화면 종류가 여럿일 때)
NN — 2자리 순번 (01, 02 …)
하나의 URL이 상태에 따라 다른 화면으로 분기되면 별도 번호 부여
Screen ID는 스토어 내에서만 유일하면 된다 (전역 유일 아님). 예: YETI의 SHOP-PLP-01과 WORKSOUT의 SHOP-PLP-01은 서로 다른 스토어 문서(stores/yeti/... vs stores/worksout/...)이므로 충돌이 아니다. 파일 경로가 스토어를 구분한다.

그룹 코드표

도메인 (한글)	코드	서브 예시	Screen ID 예시
홈	HOME	—	HOME-01
쇼핑	SHOP	PLP / PDP / FLT(필터)	SHOP-PLP-01, SHOP-FLT-01
검색	SRCH	OVR(오버레이) / RES(결과)	SRCH-OVR-01
장바구니	CART	—	CART-01
결제	PAY	CHK(체크아웃) / DONE	PAY-CHK-01
주문	ORD	LIST / DETAIL / LOOKUP	ORD-LOOKUP-01
회원(인증)	AUTH	LOGIN / JOIN / FIND	AUTH-LOGIN-01
계정(마이페이지)	ACCT	MYP / INFO / WISH / CPN / GRD / PNT	ACCT-MYP-01
라플	RAF	LIST / DETAIL	RAF-LIST-01
콘텐츠	CNT	CMS / FAQ / NEWS / ABOUT / STORE / PAGE	CNT-FAQ-01
알림	NTF	SET(설정) / DTL(상세)	NTF-01, NTF-SET-01
딥링크	DEEP	—	DEEP-01
공통	CMN	RVW(앱 리뷰)	CMN-01, CMN-RVW-01
브랜드 페이지 (WORKSOUT 전용)	BRND	—	BRND-01
피드 (WORKSOUT 전용)	FEED	EDT(에디토리얼) / WEAR / SHORT(숏폼) / LIKE(찜한 피드)	FEED-01, FEED-SHORT-01
바코드 (WORKSOUT 전용)	BARC	—	BARC-01

CART(장바구니) 서브 예시에 ADD(담기 바텀시트) 추가, RAF(라플) 서브 예시에 APPLY(응모 입력) / CONFIRM(주의사항 확인) / DONE(응모 완료) 추가.

새 도메인이 생기면 이 표에 한 줄 추가한다.

본문 권장 섹션

.templates/domain.md 를 복사해 시작한다. 표준 섹션:

## 화면 정보 — Screen ID / Title / Path 표
## 개요 — 한두 문장 요약
## 화면 구성 — 입력 필드, 버튼/액션
## 정책 — 유효성, 예외, 상태 처리
## 시나리오 — 케이스별 동작 정의 (선택 — 분기가 복잡한 화면에 한해 작성)
## 미결 사항 — 운영팀 확정 필요 항목
## 변경 이력 — 버전별 변경 표 (아래 참고)

버전 · 변경점 관리

파일 하단 ## 변경 이력 표에 버전별로 한 줄씩 누적한다.

## 변경 이력
| 버전 | 날짜 | 변경 내용 |
|------|------|-----------|
| v1.1 | 2026-06-23 | 비디오 첨부 기능 추가 |
| v1.0 | 2026-06-23 | 최초 작성 |

문서를 수정하면: ① frontmatter version/updated 갱신 ② 본문 변경이력 한 줄 추가 ③ 루트 changelog.md 에 한 줄 추가.
정확한 diff 는 git 으로 본다: git log -p src/content/docs/stores/yeti/member/login.md

폐기 문서 처리

문서가 다른 문서로 대체되면 status: Superseded 로 바꾸고, 개요에 대체 문서 링크를 남긴다.
파일을 삭제하지 말고 Superseded 로 남겨 히스토리를 보존한다.

AI 가 문서를 읽는 순서 (토큰 최소)

changelog.md — “무엇이 바뀌었나” 확인 (작음)
stores/<store>/index.md — 관련 도메인·최신 버전 확인 (작음)
해당 도메인 파일 본문 — 필요한 것만 (필요분만)
정확한 diff 필요 시 git log/diff (온디맨드)

전체 문서를 한꺼번에 읽지 않는다.