| 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 미존재
동작:
- 프로젝트 스캔 —
README.md, CLAUDE.md, package.json의 name/description, 최상위 디렉토리명에서 핵심 명사 추출
- 초안 구조 제시 후 사용자 확인
- 확정 시
./glossary.md 생성
모드 2: Capture (명시 호출)
트리거: /glossary 호출 + 파일 존재
동작:
- 현재 대화 맥락에서 용어 후보 추출
- 기존 사전과 중복 체크 → 신규만 제시
- 사용자 확인 후 기존 파일에 병합
모드 3: Passive Detect (백그라운드)
트리거: AI가 대화 중 모르던 용어 조우 (판정 기준 아래)
동작:
- 후보를 in-memory buffer에 쌓음 (저장 X, 대화 흐름 끊지 않음)
- 세션 종료 시 Stop hook이
/glossary 재호출 → buffer flush
- 사용자에게 후보 제시, 확인받은 것만 저장
"모르던 용어" 판정 (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 다이어그램 같은 무거운 표기는 지양. 글로 읽히는 사전 우선.
동의어 통일
같은 개념을 다르게 부르는 용어가 둘 이상 발견되면:
- 사용자에게 정식 용어를 묻는다 (AI가 임의 선택 X)
- 정식 용어 외는 "금칙어" 섹션에 이동
- naming-audit 스킬과 연동 가능 — 사전에 금칙어가 있으면 naming-audit이 코드에서 해당 단어 검색
출력 순서 규약
/glossary 호출 시 응답 형식:
- 현재 상태 요약 — 핵심 개념 N개, 금칙어 M개, 후보 K개
- 이번 턴 변화 — 추가/수정/이동 제안 (모드별)
- 확인 질문 — AskUserQuestion으로 후보 승인 받기 (2~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는 정상 동작한다. 자동 플러시가 불필요하면 설치 건너뛰어도 됨.
