ADR-0008: 서비스 폴더 컨벤션 — flat .md + B2C/B2B 디자인 시스템 분기
- 일자: 2026-05-14
- 상태: Accepted (Supersedes ADR-0006)
- 결정자: cony@yumyum.im
- 관련: 용어 정의, 디자인 시스템
배경 (Context)
ADR-0006 가 4 최상위 + sub-folder 구조 (20-store-portal/store-10-portal/, 30-marketing-home/ 안 4 sub-페이지) 를 결정했지만, 실제로 빌드·문서 작성을 해보니 다음 마찰점이 드러남:
- Sub-folder 가 비어 있는데 골격만 있는 상황이 빈번 —
store-20-app/index.md한 줄짜리 골격 → 그래도 폴더 2단 깊이 - VitePress 빌드 + 사이드바 매핑이 깊어짐 —
/20-product/20-store-portal/store-20-app/같은 URL - 상호 참조 (cross-reference) 가
../../../까지 올라감 — 가독성·유지보수성 저하 - 사용자(나)의 작업 흐름 — Finder 에서 사장님 운영 3채널을 한눈에 보고 싶지만 sub-folder 가 가려서 보기 힘듦
yumyum-NN-*prefix 가 이미 빠진 상태 (ADR-0006 후속작업) — 컨벤션이 이미 한 번 더 진화하고 있음
또한 디자인 시스템 측면의 결정 이 별도로 있었는데 (PR #79 v2):
- B2C (고객 앱 / 마케팅 사이트) = YumYum 브랜드 — warm yellow
#FFCC33(친근·식욕·신뢰) - B2B 도구 (사장님 Portal / 내부 어드민) = Binance + Wanted 프로페셔널 스타일 — cool yellow
#FCD535(밀도·기능·전문성)
이 분기는 30-design/10-owner-strategy.md 와 30-design/11-admin-binance-mapping.md 에 이미 문서화됐지만, 어느 서비스가 어느 시스템을 따르는지 의 매핑이 ADR 레벨로 못 박혀 있지 않았다. 본 ADR 에서 함께 정식화한다.
결정 (Decision)
A. 폴더 컨벤션 — flat .md sibling
20-product/ 안의 모든 서비스 문서는 sub-folder 없이 평평한 .md 파일로 둔다.
20-product/
index.md ← 카탈로그
10-user-app.md ← 1. User (B2C)
11-screens.md ← User 화면 명세
20-store-portal.md ← 2. Store-Portal Web (B2B)
21-store-app.md ← 2-1. Store App iOS/Android (B2B)
22-store-pos.md ← 2-2. Store POS Windows (B2B)
30-marketing-home.md ← 3. Marketing Home (B2C)
31-marketing-partners.md ← 3-1. Marketing Partners (B2C)
32-marketing-company.md ← 3-2. Marketing Company (B2C)
40-admin.md ← 4. Admin 내부 (B2B)네이밍 규칙
- 파일명:
NN-{service}-{role}.md(kebab-case, NN 숫자 prefix) - 같은 패밀리는 같은 10단위 번호로 그루핑 (
2x사장님 운영,3x마케팅) - 11, 25 등 추후 삽입 여유 남김
- 라벨 (코드명, 문서 본문 표기): PascalCase 또는
Foo-Bar형식, prefix 없음 (예:Store-Portal)
서브폴더 금지 원칙
20-product/안에서는 추가 폴더를 만들지 않는다.- 한 서비스에 여러 문서가 필요하면 같은 prefix 의 sibling 파일로 (예:
10-user-app.md+11-screens.md) - 만약 정말 깊이가 필요한 케이스가 생기면 별도 카테고리 폴더 (
60-…/) 로 빼는 걸 우선 검토
다른 카테고리 폴더 (30-design/, 90-decisions/ 등)
- 이미 같은 컨벤션을 따르고 있음 (
30-design/01-colors.md,90-decisions/adr-0001-*.md) - 본 ADR 은
20-product/의 컨벤션을 동일하게 맞춘 것
B. B2C / B2B 디자인 시스템 분기 정식화
각 서비스가 어느 디자인 시스템을 따르는지 ADR 레벨로 못 박는다.
| # | 서비스 | 디자인 시스템 | 메인 노랑 | 출처 |
|---|---|---|---|---|
| 1 | User | YumYum v2 (B2C) | #FFCC33 warm | 30-design/01~09.md |
| 2 | Store-Portal | Binance + Wanted (B2B) | #FCD535 cool | 30-design/10-owner-strategy.md, 11-admin-binance-mapping.md |
| 2-1 | Store-App | Binance + Wanted (B2B) | #FCD535 cool | 동상 |
| 2-2 | Store-POS | Binance + Wanted (B2B) | #FCD535 cool | 동상 |
| 3 | Marketing-Home | YumYum v2 (B2C) | #FFCC33 warm | 30-design/01~09.md |
| 3-1 | Marketing-Partners | YumYum v2 (B2C) | #FFCC33 warm | 동상 (Marketing 3 우산 공통) |
| 3-2 | Marketing-Company | YumYum v2 (B2C) | #FFCC33 warm | 동상 (Marketing 3 우산 공통) |
| 4 | Admin | Binance + Wanted (B2B) | #FCD535 cool | 30-design/10-owner-strategy.md, 11-admin-binance-mapping.md |
분기 원칙
Marketing-*우산 모두 B2C — 도메인이www든partners든, 콘텐츠 대상이 잠재 사장님이든, 로그인 전·마케팅·브랜드 표현 영역 이므로 YumYum v2 사용Store-*채널 모두 B2B — 사장님이 로그인 후 매장을 운영하는 도구. 정보 밀도·기능성 최우선Admin도 B2B — 운영팀 내부 도구. Store 와 같은 B2B 시스템 공유
로그인 경계 = 디자인 분기 경계. 마케팅(로그인 X) = B2C, 사장님 운영·내부(로그인 O) = B2B.
근거 (Rationale)
1. flat .md 는 골격 단계에서 가장 가벼움
| 비교 | sub-folder + index.md | flat .md |
|---|---|---|
| 신규 골격 생성 비용 | mkdir + touch 2단계 | touch 1단계 |
| Finder 에서 한눈에 보기 | 폴더 안 펼쳐야 | ✓ 즉시 |
| 상호 참조 깊이 | ../../../ 까지 | ./ 또는 ../ |
| VitePress URL | /20-product/foo/bar/ | /20-product/foo-bar |
| sub-페이지 추가 비용 | 폴더 안 새 .md | sibling .md (prefix 로 그루핑) |
골격이 채워지고 한 서비스에 진짜 많은 문서가 필요해질 때 그때 폴더로 승격해도 늦지 않다. YAGNI — 지금 필요한 컨벤션을 단순하게.
2. NN 숫자 prefix 가 그루핑·정렬을 대신함
- sub-folder 가 했던 "그루핑" 역할 →
2x,3x같은 prefix 가 대신 - "정렬" 역할 → 그대로
- "한 서비스에 여러 문서" 케이스 → 같은 prefix 의 sibling (10-user-app.md + 11-screens.md)
3. B2C/B2B 분기는 ADR 레벨로 못 박을 가치가 있음
- 디자인 토큰 선택, 컴포넌트 라이브러리 선택, Storybook 분리 여부 등 여러 후속 결정의 분기점
- "사장님 Portal 도 YumYum 브랜드 노랑으로 갈까?" 같은 추후 의문이 발생할 때 본 ADR 을 가리키면 됨
30-design/10-owner-strategy.md와11-admin-binance-mapping.md가 이 결정의 세부 근거 문서 이고, 본 ADR 은 서비스 ↔ 디자인 시스템 매핑 을 못 박는 진입점
4. 고려한 대안
대안 A: ADR-0006 sub-folder 구조 유지 (기각)
- 기각: 위 1번 (마찰점) 참조. 깊이가 비용보다 가치를 못 주고 있음.
대안 B: 모든 서비스를 YumYum v2 단일 디자인 시스템으로 (기각)
- 기각: B2C 와 B2B 의 사용 맥락·정보 밀도·전문성 요구가 본질적으로 다름.
30-design/10-owner-strategy.md의 분석 참조.
대안 C: B2C/B2B 분기는 그대로 두되 폴더 컨벤션은 그대로 (기각)
- 기각: 두 결정을 한 번에 정리하는 게 깔끔. 사용자 입장에서 "지금부터 이렇게 가자" 의 분기점이 명확.
결과 (Consequences)
긍정
- 신규 골격 추가가 1 단계로 단순화 —
touch 21-store-app.md만 하면 끝 - 상호 참조 경로가 짧고 안정적 —
../10-policy/glossary까지만 올라감 - VitePress URL 이 짧고 평평 —
/20-product/22-store-pos같은 형태 - Finder · GitHub 트리에서 한눈에 8개 서비스 보임
- B2C/B2B 디자인 분기가 ADR 레벨로 명확 — 추후 디자인 토큰·컴포넌트 결정의 기준점
주의 / 후속 필요
- 기존 cross-reference 일괄 업데이트 필요 — 50-operations / adr-0007 등의
/20-product/.../...경로 짧게 수정 (본 PR 에서 함께 수행) - NN 숫자가 변할 때 cross-ref 깨질 수 있음 — 큰 재구조 시 일괄 검색·치환 필요
- 한 서비스에 화면 명세 + API 명세 + 운영 가이드 등 다 들어가면 부족할 수 있음 — 그땐 prefix sibling 으로 분리, 정말 안 되면 다음 ADR 에서 폴더 승격 검토
20-product/외 다른 카테고리 (10-policy/,30-design/, …) 는 이미 flat 컨벤션을 따르고 있음 — 별도 작업 X
후속 작업
- [x]
20-product/모든 sub-folder → flat.md변환 (5 → 8 파일) - [x]
21-store-app.md,22-store-pos.md골격 정리 (기존store-20-app/,store-30-pos/흡수) - [x]
31-marketing-partners.md,32-marketing-company.md신규 골격 (기존30-marketing-home/의 Partners / Company 섹션 분리) - [x]
20-product/index.md카탈로그 갱신 (8 서비스 + 디자인 시스템 컬럼) - [x]
.vitepress/config.mts사이드바 갱신 - [x]
10-policy/glossary.md§1-1 갱신 (flat 파일명 표 + 디자인 컬럼) - [x]
50-operations/partner-onboarding-sop.md,90-decisions/adr-0007-phase-0-1-2.md의 경로 수정 - [x] ADR-0006 ⚠️ Superseded 표시
- [x]
90-decisions/index.md에 본 ADR 등록 - [ ] 디자인 토큰 (
.vitepress/theme/style.css) B2C 정식화 — Marketing-* / User 적용 (별도 PR) - [ ] B2B Storybook 분리 검토 (별도 ADR 가능)