glossary

name	glossary
description	도메인 분석 + 유비쿼터스 언어 사전. 프로젝트의 핵심 용어·개념·관계를 대화로 추출하여 ./glossary.md에 누적한다. 3모드: (1) 파일 없으면 Init으로 초안 생성, (2) 호출 시 현재 대화 맥락에서 용어 Capture, (3) 대화 중 AI가 모르던 용어를 passive buffer에 쌓고 세션 종료 시 자동 Flush. "용어 정리", "도메인 분석", "유비쿼터스 언어", "용어 사전", "glossary", "/glossary" 등을 말할 때 사용. DDD Event Storming·Bounded Context 같은 방법론 의례는 포함하지 않는다 — 용어·관계·동의어·맥락 구분만.

/glossary — 도메인 분석 + 용어 사전

프로젝트의 핵심 용어와 개념을 대화로 뽑아 ./glossary.md에 고정한다. DDD의 "유비쿼터스 언어"와 같은 결이지만 Event Storming 같은 특정 방법론 의례는 포함하지 않는다. 도메인 분석의 산출물(용어·관계·동의어·맥락)에만 집중한다.

왜 필요한가: 팀과 AI가 같은 단어를 다르게 이해하면 구현도 엇갈린다. 용어를 파일로 고정하면 (1) 새 멤버·새 세션이 맥락을 빠르게 탑재하고, (2) 동의어 드리프트·역할 분산 같은 네이밍 문제를 사전에 막는다.

---

3가지 모드

모드 1: Init (파일 없음)

트리거: /glossary 호출 + ./glossary.md 미존재

동작:

1. 프로젝트 스캔 — README.md, CLAUDE.md, package.json의 name/description, 최상위 디렉토리명에서 핵심 명사 추출
2. 초안 구조 제시 후 사용자 확인
3. 확정 시 ./glossary.md 생성

모드 2: Capture (명시 호출)

트리거: /glossary 호출 + 파일 존재

동작:

1. 현재 대화 맥락에서 용어 후보 추출
2. 기존 사전과 중복 체크 → 신규만 제시
3. 사용자 확인 후 기존 파일에 병합

모드 3: Passive Detect (백그라운드)

트리거: AI가 대화 중 모르던 용어 조우 (판정 기준 아래)

동작:

1. 후보를 in-memory buffer에 쌓음 (저장 X, 대화 흐름 끊지 않음)
2. 세션 종료 시 Stop hook이 /glossary 재호출 → buffer flush
3. 사용자에게 후보 제시, 확인받은 것만 저장

"모르던 용어" 판정 (3조건 AND):

• (a) 사용자 메시지에 등장
• (b) AI의 일반 지식으로 의미가 확정되지 않음 (프로젝트 고유어 가능성)
• (c) 같은 세션에서 2회 이상 반복 OR 사용자가 정의를 곁들임

---

파일 포맷

저장 위치: ./glossary.md (프로젝트 루트 단일 파일, git 커밋)

---
name: glossary
updated: YYYY-MM-DD
---

# 도메인 용어 사전

## 핵심 개념

### {용어}
한 문장 정의.
- **관계**: (A는 B의 일종 / A는 B를 포함 / A는 B를 트리거)
- **동의어**: (프로젝트 안에서 같은 걸 다르게 부르는 이름들 — 통일 대상)
- **맥락 구분**: (같은 단어가 다른 곳에서 다른 뜻일 때 사용처 명시)
- **출처**: YYYY-MM-DD 대화 or 파일:라인

## 금칙어
- ~~{버려진 용어}~~ → {정식 용어}로 쓸 것. 이유: ...

## 후보 (미확정)
- {용어} — 언급 N회, 정의 미수집

---

동작 규칙

저장 게이트 (중요)

AI 자율 판단만으로는 절대 사전에 박지 않는다. 모든 저장은 다음 중 하나의 명시 게이트를 통과해야 한다:

• 사용자가 /glossary를 호출하고 제시된 후보를 확인
• 사용자가 "이거 사전에 넣어" 등 명시적 추가 요청
• 세션 종료 flush에서 사용자가 후보별로 승인

추출 범위

포함:

• 도메인 명사 (개념·엔티티·역할)
• 도메인 동사가 명사화된 것 (주문, 결제, 승인 등)
• 프로젝트 고유 약어·코드명

제외:

• 일반 기술 용어 (React, API, Git 등 — 이미 모두가 아는 것)
• 1회성 언급
• 구체 파일명·함수명 (코드 내 식별자는 naming-audit 영역)

관계 표기

단순화된 3종만 사용:

• isA: A는 B의 일종 (상속·유형 관계)
• hasA: A는 B를 포함 (구성·소유 관계)
• triggers: A가 B를 발생시킴 (이벤트·인과)

UML·ER 다이어그램 같은 무거운 표기는 지양. 글로 읽히는 사전 우선.

동의어 통일

같은 개념을 다르게 부르는 용어가 둘 이상 발견되면:

1. 사용자에게 정식 용어를 묻는다 (AI가 임의 선택 X)
2. 정식 용어 외는 "금칙어" 섹션에 이동
3. naming-audit 스킬과 연동 가능 — 사전에 금칙어가 있으면 naming-audit이 코드에서 해당 단어 검색

---

출력 순서 규약

/glossary 호출 시 응답 형식:

1. 현재 상태 요약 — 핵심 개념 N개, 금칙어 M개, 후보 K개
2. 이번 턴 변화 — 추가/수정/이동 제안 (모드별)
3. 확인 질문 — AskUserQuestion으로 후보 승인 받기 (2~4개로 압축)
4. 저장 — 승인된 것만 파일에 반영

승인 없이 파일을 건드리지 않는다.

---

superpowers·teo-stack 다른 스킬과의 경계

상황	쓸 스킬
네이밍 일관성 코드 감사	/naming-audit (코드 표면)
도메인 개념·용어 사전	/glossary (도메인 의미)
왜 이 개념이 있는지 해설 문서	/explain
요청 모호·진짜 동기 불명	/discuss

/naming-audit은 코드의 식별자가 일관된지 본다. /glossary는 도메인의 개념이 무엇인지 정의한다. 둘은 보완 — 사전이 있으면 audit의 기준이 생긴다.

---

설치 노트

모드 3(Passive Detect의 자동 Flush)을 활성화하려면 settings.json에 Stop hook이 필요하다:

{
  "hooks": {
    "Stop": [
      { "command": "echo 'glossary-flush-check'" }
    ]
  }
}

Stop hook 없이도 모드 1·2는 정상 동작한다. 자동 플러시가 불필요하면 설치 건너뛰어도 됨.