---
name: domain-dictionary
description: 도메인 용어 사전(Ubiquitous Language) 생성 및 일관성 검증. 코드/스펙/대화에서 용어 추출, 동의어/모호어/과부하 탐지, 영-한 매핑, 규범 용어 제안. /domain-dictionary 또는 "도메인사전", "용어사전", "도메인 용어" 트리거. zephermine에서 자동 호출됨.
triggers:
  - "domain-dictionary"
  - "도메인사전"
  - "용어사전"
  - "도메인 용어"
  - "용어 통일"
  - "ubiquitous language"
auto_apply: false
---

# Domain Dictionary (도메인사전)

> Eric Evans의 *Domain-Driven Design* — Ubiquitous Language 개념을 한국 SI/현장의 영-한 혼용 환경에 맞게 적용.
> 한 프로젝트 안에서 **개발자, 도메인 전문가, 사업 담당자**가 같은 단어를 같은 뜻으로 쓰도록 강제하는 사전.

## 적용 시점

| 시점 | 진입점 |
|------|--------|
| 신규 기능 계획 시 | `zephermine`이 Spec Synthesis 직후 자동 호출 |
| 기존 코드베이스 분석 시 | `/domain-dictionary` 직접 호출 |
| 코드 리뷰 시 | `code-reviewer`가 `domain-dictionary.md` 위반을 검출 |
| 신규 멤버 온보딩 시 | `domain-dictionary.md` 한 장이 첫 자료 |

## 첫 실행 시 동작

스킬 첫 실행 시 글로벌 폴더 `~/.claude/memory/domain-dictionaries/`를 자동 생성하고 `references/global-readme-template.md`를 README.md로 복사합니다. 사용자가 `install.bat`/`install.sh`를 다시 실행하지 않아도 됩니다.

처음에는 글로벌 도메인 파일들이 비어있습니다(`ecommerce.md`, `healthcare.md` 등). 시간이 흐르면서 사용자의 zephermine 종료 시 명시 선택으로 누적됩니다 — 의도된 설계.

## 사전의 두 종류 (글로벌 + 프로젝트)

| 종류 | 위치 | 역할 |
|------|------|------|
| **글로벌** | `~/.claude/memory/domain-dictionaries/{도메인}.md` | 사용자 자산 — 자주 다루는 도메인의 누적 용어 (참고용 씨앗) |
| **프로젝트** (마스터) | `<project>/docs/domain-dictionary.md` | **진실의 원천** — 이 프로젝트만의 확정 사전 |
| **프로젝트** (델타) | `<project>/docs/plan/{feature}/domain-dictionary-delta.md` | 이번 feature에서 추가/변경된 이력 (zephermine 산출물) |

### 글로벌 사전 폴더 구조

```
~/.claude/memory/domain-dictionaries/
├── README.md          ← 사용 안내 + 도메인 분류 가이드
├── ecommerce.md       ← Cart, Order, SKU, Fulfillment...
├── healthcare.md      ← Patient, Encounter, Diagnosis...
├── finance.md         ← Position, Settlement, Counterparty...
└── general.md         ← 도메인 무관 (User, Session, Audit...)
```

### 관계: 참고형 + 선택적 채택 (자동 상속 ❌)

- 글로벌은 **씨앗만 제공**. 프로젝트 시작 시 사용자가 "어떤 용어 가져올래?" 명시 선택.
- 프로젝트 사전이 **최종 결정권자**. 글로벌과 다르게 정의해도 프로젝트가 우선.
- 프로젝트 변경의 글로벌 자동 업그레이드 ❌. 사용자가 명시적으로 선택한 항목만 글로벌에 반영.
- 자세한 동기화 절차: [global-sync.md](references/global-sync.md)

## 모드 결정

### 1. 컨텍스트 모드 (zephermine에서 자동 호출, Phase 2~3에서 진화)

| Phase | 사전 버전 | 동작 |
|-------|----------|------|
| Phase 2 (Step 8 끝) | v1 초안 | spec.md, interview.md + 글로벌 사전 후보에서 추출. 사용자 개입 없음 |
| Phase 3 (Step 10 끝) | v2 자동 병합 | 6개 전문가의 `## Dictionary Updates`를 자동 병합. CONFLICT는 미룸 |
| Phase 3 (Step 11 끝) | v3 확정 | 사용자 multiSelect 결과 반영 + 글로벌 반영 명시 선택 |

**산출 위치:**
- 마스터: `<project>/docs/domain-dictionary.md` (없으면 생성, 있으면 갱신)
- 델타: `<planning_dir>/domain-dictionary-delta.md` (이번 feature 변경 이력)

### 2. 코드베이스 모드 (직접 호출)
- 입력: 현재 작업 디렉토리의 코드, 기존 문서
- 출력: `<project>/docs/domain-dictionary.md` (마스터 직접 갱신)

### 3. 갱신 모드 (이미 마스터 사전이 있는 경우)
- 입력: 기존 마스터 + 새 변경사항
- 동작: 신규 용어 병합 (기존 항목 덮어쓰지 않음), 변경 이력에 행 추가
- 충돌 시 사용자 확인

## 워크플로우

### Step 1: 후보 용어 수집

추출 알고리즘과 패턴은 [extraction-guide.md](references/extraction-guide.md) 참조.

**컨텍스트 모드:**
- spec.md, interview.md의 명사/동사 추출
- team-reviews/domain-* 의 도메인 용어 추출

**코드베이스 모드:**
- Glob/Grep으로 클래스/함수/타입/변수 식별자 추출
- 주석, UI 문자열 리터럴(메뉴/라벨)에서 한국어 용어 추출
- 기존 README, docs/*.md에서 용어 추출

### Step 2: 문제 패턴 탐지

| 문제 | 예시 | 처리 |
|------|------|------|
| **동의어** (같은 개념, 다른 단어) | `cart` / `basket` / `bag` | 하나로 통일 제안 |
| **이의어** (같은 단어, 다른 개념) | `Order` = "주문" or "정렬"? | 분리 (`Order` vs `SortOrder`) |
| **과부하** (한 단어가 너무 많은 의미) | `User` = 고객/관리자/판매자 | 분리 (`Customer` / `Admin` / `Seller`) |
| **영-한 불일치** | DB는 `user`, UI는 "고객" | 매핑 명시 또는 통일 |
| **약어 남용** | `usrCfg` (=userConfig?) | 풀어쓰기 권장 |
| **외래어 표기 흔들림** | "어카운트" / "계정" / "account" | 한 표기로 통일 |

### Step 3: 규범 용어 제안

각 핵심 개념마다 다음 형식으로 정리:

```markdown
## Cart (장바구니)
- **정의**: 사용자가 결제 전 임시로 모은 상품 목록
- **영문 식별자**: `cart` (변수, 클래스 prefix)
- **한글 표기**: 장바구니 (UI, 문서)
- **관련 개념**: CartItem (장바구니 항목), Wishlist (찜 — 구매 의도 없음, 다른 개념)
- **금지 표현**: ~~basket~~, ~~bag~~, ~~shopping_list~~
- **예시**:
  - ✅ `cart.addItem(item)`, "장바구니에 담기"
  - ❌ `basket.push(item)`, "쇼핑백 추가"
- **위치**: `src/cart/` 모듈 전체
```

### Step 4: 사용자 확인

핵심 용어(상위 5~10개)를 AskUserQuestion(multiSelect)으로 확인:

```
"아래 용어 정의를 확인해주세요. 수정이 필요한 항목을 선택하세요."
header: "Domain Dictionary"
multiSelect: true
options:
  - label: "✅ Cart = 장바구니"
    description: "결제 전 임시 상품 목록. basket/bag 금지"
  - label: "✅ Wishlist = 찜"
    description: "구매 의도 없는 관심 상품. cart와 분리"
  ...
```

수정 요청 항목은 추가 질문으로 구체화.

### Step 5: 출력 (마스터 + 델타 + 글로벌 반영)

**컨텍스트 모드 (zephermine 흐름)**:

1. **마스터 갱신**: `<project>/docs/domain-dictionary.md`
2. **델타 작성**: `<planning_dir>/domain-dictionary-delta.md` (이번 feature 변경 이력)
3. **글로벌 반영** (사용자 선택 시): `~/.claude/memory/domain-dictionaries/{도메인}.md`에 항목 추가 + 출처 메타데이터

**코드베이스 모드 (직접 호출)**: 마스터 직접 갱신만.

마스터 사전 형식:

```markdown
# Domain Dictionary

> 생성일: YYYY-MM-DD
> 도메인: {프로젝트명/기능명}
> 버전: v1.0
> 대상 청중: 개발자 + 도메인 전문가 + 사업 담당자

## 핵심 용어 (Core Terms)

{각 용어의 정의 + 영-한 매핑 + 예시}

## 관계도 (Optional — 5개 이상의 핵심 용어가 있을 때)

​```mermaid
graph TD
  Customer -->|places| Order
  Order -->|contains| OrderItem
  OrderItem -->|references| Product
​```

## 외부 표준 매핑 (해당 시)

| 용어 | 외부 표준 | 매핑 |
|------|-----------|------|
| Patient | HL7 FHIR `Patient` | 1:1 |
| Diagnosis | ICD-10 코드 | 다대일 |

## 금지 표현 모음

| 금지 | 대신 사용 | 이유 |
|------|-----------|------|
| basket, bag | cart | Cart로 통일 |
| user (고객 의미로) | customer | User는 시스템 사용자 일반 |

## 변경 이력

| 날짜 | 변경 | 이유 |
|------|------|------|
| YYYY-MM-DD | 초안 | 첫 작성 |
```

델타 파일 형식 (`<planning_dir>/domain-dictionary-delta.md`):

```markdown
# Domain Dictionary Delta — {feature-name}

> 생성일: YYYY-MM-DD
> 마스터 사전: docs/domain-dictionary.md
> 이 feature에서 추가/변경된 항목만 기록

## v1 → v2 (Step 10 자동 병합)
- ADD Wishlist (출처: Domain Researcher) — 찜 정의
- REFINE Order (출처: Process Expert) — 결제 시점 명확화

## v2 → v3 (Step 11 사용자 확정)
- ✅ Cart 채택, Basket 거부 (CONFLICT 해소)
- ✅ Wishlist 추가 확정
- ✅ Order 다듬음 확정

## Global Dictionary Sync (사용자 명시 선택)
- ✅ Wishlist → ~/.claude/memory/domain-dictionaries/ecommerce.md
- ✅ Bundle → ecommerce.md
- ❌ FlashSale → 프로젝트 특수성으로 보류
```

### Step 6: 후속 안내

```
✅ 도메인사전 갱신 완료
   - 마스터: docs/domain-dictionary.md (v3, 핵심 용어 N개)
   - 델타: <planning_dir>/domain-dictionary-delta.md
   - 글로벌: ~/.claude/memory/domain-dictionaries/{도메인}.md (M개 추가)

다음 단계 (선택):
  zephermine 진행      → Step 12 Plan부터 사전 v3 따라 작성
  /argos               → 구현 후 사전 준수 감리
  코드 리뷰 시         → code-reviewer가 자동으로 위반 검출
```

## 갱신 모드 동작

기존 `domain-dictionary.md`가 있으면:

1. 기존 용어와 신규 용어를 비교
2. 신규 용어만 추가 (기존 항목 덮어쓰지 않음)
3. 충돌 시(같은 영문, 다른 정의) 사용자 확인
4. 변경 이력 표에 행 추가:
   ```markdown
   | 2026-04-28 | + Wishlist 추가 | 신규 기능 도입 |
   | 2026-04-28 | Cart 정의 정밀화 | 인터뷰에서 모호성 발견 |
   ```

## 제약

- **영-한 매핑이 핵심**: 한국 현장의 영-한 혼용을 명시적으로 처리
- **외부 표준 우선 검토**: 의료(FHIR/ICD-10), 금융(ISO 20022) 등 표준이 있으면 출발점으로 활용
- 용어 분쟁이 있으면 **사용자 결정 우선** — AI는 추천만
- 한 번 결정된 규범 용어는 변경 시 반드시 변경 이력 기록 (이력 보존)
- 사전은 **살아있는 문서** — 기능이 추가되면 갱신, 새 멤버 온보딩 시 첫 자료
- **분량 제한**: 핵심 용어 30개 이내. 더 많아지면 BoundedContext별로 분할 (`domain-dictionary-{context}.md`)

## 다른 스킬과의 관계

| 스킬 | 관계 |
|------|------|
| `zephermine` | Spec Synthesis 직후 이 스킬을 자동 호출 |
| `code-reviewer` | maintainability specialist가 사전 위반을 검출 |
| `argos` | 감리 시 코드/문서가 사전을 따르는지 검증 |
| `database-schema-designer` | 테이블/컬럼명이 사전의 영문 식별자를 따름 |
| `clio` | 최종 문서 생성 시 사전을 참조하여 용어 일관성 확보 |

## Related Files

| 파일 | 용도 |
|------|------|
| `references/extraction-guide.md` | 용어 추출 알고리즘과 패턴 상세 |
| `references/global-sync.md` | 글로벌 사전 폴더 구조, 도메인 자동 추정, 동기화 절차 |
| `<project>/docs/domain-dictionary.md` | **마스터** 사전 (프로젝트 단일, 진실의 원천) |
| `<planning_dir>/domain-dictionary-delta.md` | 델타 — 이번 feature에서 추가/변경된 이력 |
| `~/.claude/memory/domain-dictionaries/{도메인}.md` | 글로벌 사전 — 사용자 자산, 명시 선택으로만 추가됨 |